Debian Codegraph @

src/vendor/azure-uamqp-c/devdoc/sasl_server_io_requirements.md

raw
1 # sasl_server_io requirements
2
3 ## Overview
4
5 `sasl_server_io` is module that implements a concrete IO, that implements the section 5.3 of the AMQP ISO, allowing the usage on the server side of different negotiable SASL mechanisms.
6 The module allows by its configuration passed at create time the selection of one of several SASL mechanisms.
7 The implementation of each SASL mechanism for the server side is not part of this module.
8 The SASL server IO module communicates with concrete SASL mechanisms implementations through the `sasl_server_mechanism` API.
9
10 ## Exposed API
11
12 ```C
13 typedef struct SASL_SERVER_IO_TAG
14 {
15 SERVER_PROTOCOL_IO_CONFIG server_protocol_io;
16 const SASL_SERVER_MECHANISM_HANDLE* sasl_server_mechanisms;
17 size_t sasl_server_mechanism_count;
18 } SASL_SERVER_IO;
19
20 MOCKABLE_FUNCTION(, const IO_INTERFACE_DESCRIPTION*, sasl_server_io_get_interface_description);
21 ```
22
23 ### sasl_server_io_get_interface_description
24
25 ```C
26 MOCKABLE_FUNCTION(, const IO_INTERFACE_DESCRIPTION*, sasl_server_io_get_interface_description);
27 ```
28
29 **SRS_SASL_SERVER_IO_01_001: [** `sasl_server_io_get_interface_description` shall return a pointer to an `IO_INTERFACE_DESCRIPTION` structure that contains pointers to the functions: `sasl_server_io_create`, `sasl_server_io_destroy`, `sasl_server_io_open_async`, `sasl_server_io_close_async`, `sasl_server_io_send_async`, `sasl_server_io_setoptions` and `sasl_server_io_dowork`. **]**
30
31 ### sasl_server_io_create
32
33 ```C
34 CONCRETE_IO_HANDLE sasl_server_io_create(void* io_create_parameters);
35 ```
36
37 `sasl_server_io_create` is the implementation provided via `sasl_server_io_get_interface_description` for the `concrete_io_create` member.
38
39 **SRS_SASL_SERVER_IO_01_002: [** `sasl_server_io_create` shall return on success a non-NULL handle to a new SASL server IO instance. **]**
40
41 **SRS_SASL_SERVER_IO_01_003: [** If `io_create_parameters` is NULL, `sasl_server_io_create` shall fail and return NULL. **]**
42
43 **SRS_SASL_SERVER_IO_01_096: [** If the member `sasl_server_mechanisms` is NULL and `sasl_server_mechanism_count` is non-zero `sasl_server_io_create` shall fail and return NULL. **]**
44
45 **SRS_SASL_SERVER_IO_01_097: [** If the member `sasl_server_mechanism_count` is 0, `sasl_server_mechanism_count` is non-zero `sasl_server_io_create` shall fail and return NULL. **]**
46
47 **SRS_SASL_SERVER_IO_01_004: [** `io_create_parameters` shall be used as a pointer to the `server_protocol_io` member of a `SASL_SERVER_IO` structure (thus giving access to the entire `SASL_SERVER_IO` structure). **]**
48
49 **SRS_SASL_SERVER_IO_01_005: [** The SASL server mechanism handles shall be copied for later use. **]**
50
51 **SRS_SASL_SERVER_IO_01_006: [** If allocating memory for the SASL server mechanism handles array fails, `sasl_server_io_create` shall fail and return NULL. **]**
52
53 **SRS_SASL_SERVER_IO_01_007: [** If memory cannot be allocated for the new instance, `sasl_server_io_create` shall fail and return NULL. **]**
54
55 **SRS_SASL_SERVER_IO_01_008: [** `sasl_server_io_create` shall create a frame codec to be used for encoding/decoding frames by calling `frame_codec_create`. **]**
56
57 **SRS_SASL_SERVER_IO_01_009: [** If `frame_codec_create` fails, then `sasl_server_io_create` shall fail and return NULL. **]**
58
59 **SRS_SASL_SERVER_IO_01_010: [** `sasl_server_io_create` shall create a `sasl_frame_codec` to be used for SASL frame encoding/decoding by calling `sasl_frame_codec_create` and passing the just created frame codec as argument. **]**
60
61 **SRS_SASL_SERVER_IO_01_011: [** If `sasl_frame_codec_create` fails, then `sasl_server_io_create` shall fail and return NULL. **]**
62
63 ### sasl_server_io_destroy
64
65 ```C
66 void sasl_server_io_destroy(CONCRETE_IO_HANDLE sasl_server_io);
67 ```
68
69 `sasl_server_io_destroy` is the implementation provided via `sasl_server_io_get_interface_description` for the `concrete_io_destroy` member.
70
71 **SRS_SASL_SERVER_IO_01_012: [** `sasl_server_io_destroy` shall free all resources associated with the SASL server IO handle. **]**
72
73 **SRS_SASL_SERVER_IO_01_013: [** `sasl_server_io_destroy` shall destroy the SASL frame codec created in `sasl_server_io_create` by calling `sasl_frame_codec_destroy`. **]**
74
75 **SRS_SASL_SERVER_IO_01_014: [** `sasl_server_io_destroy` shall destroy the frame codec created in `sasl_server_io_create` by calling `frame_codec_destroy`. **]**
76
77 **SRS_SASL_SERVER_IO_01_015: [** If the argument `sasl_server_io` is NULL, `sasl_server_io_destroy` shall do nothing. **]**
78
79 ### sasl_server_io_open_async
80
81 ```C
82 int sasl_server_io_open_async(CONCRETE_IO_HANDLE sasl_server_io, ON_IO_OPEN_COMPLETE on_io_open_complete, void* on_io_open_complete_context, ON_BYTES_RECEIVED on_bytes_received, void* on_bytes_received_context, ON_IO_ERROR on_io_error, void* on_io_error_context)
83 ```
84
85 `sasl_server_io_open_async` is the implementation provided via `sasl_server_io_get_interface_description` for the `concrete_io_open` member.
86
87 **SRS_SASL_SERVER_IO_01_016: [** `sasl_server_io_open_async` shall populate the `on_bytes_received` pointer passed as part of the create parameters with the `on_underlying_bytes_received` function pointer. **]**
88
89 **SRS_SASL_SERVER_IO_01_017: [** `sasl_server_io_open_async` shall populate the `on_bytes_received_context` pointer passed as part of the create parameters with the IO handle. **]**
90
91 **SRS_SASL_SERVER_IO_01_018: [** `sasl_server_io_open_async` shall kick off the SASL handshake by encoding and sending the SASL mechanisms frame. **]**
92
93 **SRS_SASL_SERVER_IO_01_019: [** The SASL mechanisms encoded in the SASL mechanisms frame shall be the ones passed via the create parameters. **]**
94
95 **SRS_SASL_SERVER_IO_01_020: [** The name of each SASL mechanism shall be obtained by calling `sasl_server_mechanism_get_mechanism_name`. **]**
96
97 **SRS_SASL_SERVER_IO_01_095: [** When populating the frame, the order of the mechanisms shall be the preserved. **]**
98
99 **SRS_SASL_SERVER_IO_01_021: [** If `sasl_server_mechanism_get_mechanism_name` fails, `sasl_server_io_open_async` shall fail and return non-zero value. **]**
100
101 **SRS_SASL_SERVER_IO_01_022: [** If creating the mechanisms AMQP values fails, `sasl_server_io_open_async` shall fail and return non-zero value. **]**
102
103 **SRS_SASL_SERVER_IO_01_023: [** The SASL mechanisms encode shall be done by calling `sasl_frame_codec_encode_frame`. **]**
104
105 **SRS_SASL_SERVER_IO_01_024: [** On success, `sasl_server_io_open_async` shall return 0. **]**
106
107 **SRS_SASL_SERVER_IO_01_025: [** If any of the `sasl_server_io`, `on_io_open_complete`, `on_bytes_received` or `on_io_error` arguments is NULL, `sasl_server_io_open_async` shall fail and return a non-zero value. **]**
108
109 **SRS_SASL_SERVER_IO_01_026: [** `on_io_open_complete_context`, `on_bytes_received_context` and `on_io_error_context` shall be allowed to be NULL. **]**
110
111 **SRS_SASL_SERVER_IO_01_027: [** If `sasl_frame_codec_encode_frame` fails, `sasl_server_io_open_async` shall fail and return non-zero value. **]**
112
113 **SRS_SASL_SERVER_IO_01_028: [** `sasl_server_io_open_async` when already OPENING shall fail and return a non-zero value. **]**
114
115 ### sasl_server_io_close_async
116
117 ```C
118 int sasl_server_io_close_async(CONCRETE_IO_HANDLE sasl_server_io, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* on_io_close_complete_context);
119 ```
120
121 `sasl_server_io_close_async` is the implementation provided via `sasl_server_io_get_interface_description` for the `concrete_io_close` member.
122
123 **SRS_SASL_SERVER_IO_01_029: [** `sasl_server_io_close_async` shall close the underlying io handle passed in `sasl_server_io_create` by calling `xio_close`. **]**
124
125 **SRS_SASL_SERVER_IO_01_030: [** On success, `sasl_server_io_close_async` shall return 0. **]**
126
127 **SRS_SASL_SERVER_IO_01_031: [** `sasl_server_io_close_async` when the IO is not open shall fail and return a non-zero value. **]**
128
129 **SRS_SASL_SERVER_IO_01_032: [** If `sasl_server_io_close_async` is called when the IO is OPENING shall close the underlying IO and call the `on_io_open_complete` callback with `IO_OPEN_CANCELLED`. **]**
130
131 **SRS_SASL_SERVER_IO_01_033: [** If `sasl_server_io` is NULL, `sasl_server_io_close_async` shall fail and return a non-zero value. **]**
132
133 **SRS_SASL_SERVER_IO_01_034: [** If `xio_close` fails, then `sasl_server_io_close_async` shall return a non-zero value. **]**
134
135 **SRS_SASL_SERVER_IO_01_035: [** If `sasl_server_io_close_async` is closed while already CLOSING it shall fail and return a non-zero value. **]**
136
137 ### sasl_server_io_send_async
138
139 ```C
140 int sasl_server_io_send_async(CONCRETE_IO_HANDLE sasl_server_io, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context);
141 ```
142
143 `sasl_server_io_send_async` is the implementation provided via `sasl_server_io_get_interface_description` for the `concrete_io_send` member.
144
145 **SRS_SASL_SERVER_IO_01_036: [** If the SASL server IO state is OPEN, `sasl_server_io_send_async` shall call `xio_send` on the underlying IO passed to `sasl_server_io_create`, while passing as arguments the `buffer`, `size`, `on_send_complete` and `callback_context` arguments. **]**
146
147 **SRS_SASL_SERVER_IO_01_037: [** On success, If `sasl_server_io_send_async` shall return 0. **]**
148
149 **SRS_SASL_SERVER_IO_01_038: [** If the `sasl_server_io` or `buffer` argument is NULL, `sasl_server_io_send_async` shall fail and return a non-zero value. **]**
150
151 **SRS_SASL_SERVER_IO_01_039: [** If `sasl_server_io_send_async` is called while the IO is not OPEN, `sasl_server_io_send_async` shall fail and return a non-zero value. **]**
152
153 **SRS_SASL_SERVER_IO_01_040: [** If `size` is 0, `sasl_server_io_send_async` shall fail and return a non-zero value. **]**
154
155 **SRS_SASL_SERVER_IO_01_041: [** If the call to `xio_send` fails, then `sasl_server_io_send_async` shall fail and return a non-zero value. **]**
156
157 ### sasl_server_io_dowork
158
159 ```C
160 void sasl_server_io_dowork(CONCRETE_IO_HANDLE sasl_server_io);
161 ```
162
163 `sasl_server_io_dowork` is the implementation provided via `sasl_server_io_get_interface_description` for the `concrete_io_dowork` member.
164
165 **SRS_SASL_SERVER_IO_01_042: [** `sasl_server_io_dowork` shall call the `xio_dowork` on the underlying IO passed in `sasl_server_io_create`.**]**
166
167 **SRS_SASL_SERVER_IO_01_043: [** If the `sasl_server_io` argument is NULL, `sasl_server_io_dowork` shall do nothing. **]**
168
169 ### sasl_server_io_setoption
170
171 ```C
172 int sasl_server_io_setoption(CONCRETE_IO_HANDLE sasl_server_io, const char* option_name, const void* value);
173 ```
174
175 `sasl_server_io_setoption` is the implementation provided via `sasl_server_io_get_interface_description` for the `concrete_io_setoption` member.
176
177 **SRS_SASL_SERVER_IO_01_044: [** `sasl_server_io_setoption` shall forward options to underlying io by calling `xio_setoption`. **]**
178
179 **SRS_SASL_SERVER_IO_01_045: [** On success `sasl_server_io_setoption` shall return 0. **]**
180
181 **SRS_SASL_SERVER_IO_01_046: [** If `sasl_server_io` or `option_name` is NULL, `sasl_server_io_setoption` shall fail and return a non-zero value. **]**
182
183 **SRS_SASL_SERVER_IO_01_047: [** If `xio_setoption` fails, `sasl_server_io_setoption` shall fail and return a non-zero value. **]**
184
185 ### sasl_server_io_retrieve_options
186
187 ```C
188 OPTIONHANDLER_HANDLE sasl_server_io_retrieve_options(CONCRETE_IO_HANDLE header_detect_io)
189 ```
190
191 `sasl_server_io_retrieve_options` is the implementation provided via `header_detect_io_get_interface_description` for the `concrete_io_retrieveoptions` member.
192
193 **SRS_SASL_SERVER_IO_01_048: [** `sasl_server_io_retrieve_options` shall create a new `OPTIONHANDLER_HANDLE` by calling `OptionHandler_Create` and on success it shall return a non-NULL handle to the newly created option handler. **]**
194
195 **SRS_SASL_SERVER_IO_01_049: [** No options shall be added to the newly created option handler. **]**
196
197 **SRS_SASL_SERVER_IO_01_050: [** If `OptionHandler_Create` fails, `sasl_server_io_retrieve_options` shall return NULL. **]**
198
199 **SRS_SASL_SERVER_IO_01_051: [** If `header_detect_io` is NULL, `sasl_server_io_retrieve_options` shall return NULL. **]**
200
201 ### on_underlying_bytes_received
202
203 ```C
204 void on_underlying_io_bytes_received(void* context, const unsigned char* buffer, size_t size)
205 ```
206
207 **SRS_SASL_SERVER_IO_01_052: [** `on_underlying_bytes_received` called with a NULL `context` shall do nothing. **]**
208
209 **SRS_SASL_SERVER_IO_01_053: [** When the `on_underlying_bytes_received` callback is called and the SASL server IO is OPEN, the bytes shall be indicated to the user of SASL server IO by calling the `on_bytes_received` that was passed in `sasl_server_io_open_async`. **]**
210
211 **SRS_SASL_SERVER_IO_01_054: [** If `buffer` is NULL or size is zero, nothing should be indicated as received and an error should be indicated by calling the `on_io_error` callback shall be triggered, while passing the `on_io_error_context` to it. **]**
212
213 **SRS_SASL_SERVER_IO_01_055: [** If bytes are received when the SASL server IO state is OPENING, the bytes shall be consumed by the SASL server IO to satisfy the SASL handshake by calling `frame_codec_receive_bytes` with each byte that was received. **]**
214
215 **SRS_SASL_SERVER_IO_01_056: [** If bytes are received when the SASL server IO state is in ERROR, SASL server IO shall do nothing. **]**
216
217 **SRS_SASL_SERVER_IO_01_057: [** Any bytes that are extra and were not consumed for the SASL shandshake shall be indicated to the user of SASL server IO by calling the `on_bytes_received` that was passed in `sasl_server_io_open_async`. **]**
218
219 ### on_sasl_frame_received_callback
220
221 ```C
222 void on_sasl_frame_received_callback(void* context, AMQP_VALUE sasl_frame);
223 ```
224
225 **SRS_SASL_SERVER_IO_01_058: [** `on_sasl_frame_received_callback` with a NULL `context` shall do nothing. **]**
226
227 **SRS_SASL_SERVER_IO_01_059: [** If `on_sasl_frame_received_callback` is called when the IO is OPEN then the SASL server IO shall call the `on_io_open_complete` callback with `IO_OPEN_ERROR` and close the IO. **]**
228
229 **SRS_SASL_SERVER_IO_01_060: [** When a frame is indicated as received by the SASL frame codec it shall be processed as described in the ISO. **]**
230
231 **SRS_SASL_SERVER_IO_01_061: [** The calls to the concrete implementation of the SASL mechanism shall be done by calling `sasl_server_mechanism_handle_initial_response` and `sasl_server_mechanism_handle_response`. **]**
232
233 **SRS_SASL_SERVER_IO_01_062: [** When a frame needs to be sent as part of the SASL handshake frame exchange, the send shall be done by calling `sasl_frame_codec_encode_frame`. **]**
234
235 **SRS_SASL_SERVER_IO_01_063: [** If `sasl_frame_codec_encode_frame` fails, then the SASL server IO shall call the `on_io_open_complete` callback with `IO_OPEN_ERROR` and close the IO. **]**
236
237 **SRS_SASL_SERVER_IO_01_064: [** When the SASL handshake is complete, if the handshake is successful, the SASL server IO shall be considered OPEN and the `on_io_open_complete` callback shall be called with `IO_OPEN_OK`. **]**
238
239 **SRS_SASL_SERVER_IO_01_065: [** If any error is encountered when parsing the received frame, the SASL server IO state shall call the `on_io_open_complete` callback with `IO_OPEN_ERROR` and close the IO. **]**
240
241 **SRS_SASL_SERVER_IO_01_066: [** If the handshake fails (i.e. the outcome is an error) the SASL server IO state shall call the `on_io_open_complete` callback with `IO_OPEN_ERROR` and close the IO. **]**
242
243 ### on_bytes_encoded
244
245 ```C
246 void on_bytes_encoded(void* context, const unsigned char* bytes, size_t length, bool encode_complete)
247 ```
248
249 **SRS_SASL_SERVER_IO_01_067: [** When SASL server IO is notified by the SASL frame codec of bytes that have been encoded via the `on_bytes_encoded` callback while the SASL server IO is OPENING, it shall send these bytes by calling `xio_send` on the underlying IO. **]**
250
251 **SRS_SASL_SERVER_IO_01_068: [** When `on_bytes_encoded` is called with a NULL `context` it shall do nothing. **]**
252
253 **SRS_SASL_SERVER_IO_01_069: [** When `on_bytes_encoded` is called with NULL bytes it shall call the `on_io_open_complete` callback with `IO_OPEN_ERROR` and close the IO. **]**
254
255 **SRS_SASL_SERVER_IO_01_070: [** When `on_bytes_encoded` is called with 0 `size` it shall call the `on_io_open_complete` callback with `IO_OPEN_ERROR` and close the IO. **]**
256
257 **SRS_SASL_SERVER_IO_01_071: [** If `xio_send` fails, the SASL server IO state shall call the `on_io_open_complete` callback with `IO_OPEN_ERROR` and close the IO. **]**
258
259 **SRS_SASL_SERVER_IO_01_072: [** If `on_bytes_encoded` is called when already OPEN, then the `on_io_error` callback shall be called while passing to it `on_io_error_context`. **]**
260
261 ### on_frame_codec_error
262
263 ```C
264 void on_frame_codec_error(void* context);
265 ```
266
267 **SRS_SASL_SERVER_IO_01_073: [** When `on_frame_codec_error` is called while OPENING SASL server IO shall call the `on_io_open_complete` callback with `IO_OPEN_ERROR` and close the IO. **]**
268
269 **SRS_SASL_SERVER_IO_01_074: [** When `on_frame_codec_error` is called when the IO is OPEN then the `on_io_error` callback shall be called while passing to it `on_io_error_context`. **]**
270
271 **SRS_SASL_SERVER_IO_01_075: [** When `on_frame_codec_error` is called with NULL `context`, `on_frame_codec_error` shall do nothing. **]**
272
273 **SRS_SASL_SERVER_IO_01_076: [** When `on_frame_codec_error` is called after the IO had an error, `on_frame_codec_error` shall do nothing. **]**
274
275 ### on_sasl_frame_codec_error
276
277 ```C
278 void on_sasl_frame_codec_error(void* context);
279 ```
280
281 **SRS_SASL_SERVER_IO_01_077: [** When `on_sasl_frame_codec_error` is called when OPENING the SASL server IO shall call the `on_io_open_complete` callback with `IO_OPEN_ERROR` and close the IO. **]**
282
283 **SRS_SASL_SERVER_IO_01_078: [** When `on_sasl_frame_codec_error` is called when the IO is OPEN then the `on_io_error` callback shall be called while passing to it `on_io_error_context`. **]**
284
285 **SRS_SASL_SERVER_IO_01_079: [** When `on_sasl_frame_codec_error` is called with NULL `context`, `on_sasl_frame_codec_error` shall do nothing. **]**
286
287 **SRS_SASL_SERVER_IO_01_080: [** When `on_sasl_frame_codec_error` is called after the IO had an error, `on_sasl_frame_codec_error` shall do nothing. **]**
288
289 ## ISO section
290
291 To establish a SASL layer, each peer MUST start by sending a protocol header.
292 The protocol header consists of the upper case ASCII letters "AMQP" followed by a protocol id of three, followed by three unsigned bytes representing the major, minor, and revision of the specification version (currently 1 (SASL-MAJOR), 0 (SASLMINOR), 0 (SASL-REVISION)). In total this is an 8-octet sequence:
293
294 ...
295
296 Figure 5.3: Protocol Header for SASL Security Layer
297
298 Other than using a protocol id of three, the exchange of SASL layer headers follows the same rules specified in the version negotiation section of the transport specification (See Part 2: section 2.2).
299 The following diagram illustrates the interaction involved in creating a SASL security layer:
300
301 ...
302
303 Figure 5.4: Establishing a SASL Security Layer
304
305 SASL Negotiation
306
307 **SRS_SASL_SERVER_IO_01_081: [** The peer acting as the SASL server MUST announce supported authentication mechanisms using the sasl-mechanisms frame. **]**
308 **SRS_SASL_SERVER_IO_01_082: [** The partner MUST then choose one of the supported mechanisms and initiate a sasl exchange. **]**
309
310 SASL Client SASL Server
311
312 **SRS_SASL_SERVER_IO_01_083: [** <-- SASL-MECHANISMS **]**
313 **SRS_SASL_SERVER_IO_01_084: [** SASL-INIT --> **]**
314 ...
315 **SRS_SASL_SERVER_IO_01_085: [** <-- SASL-CHALLENGE * **]**
316 **SRS_SASL_SERVER_IO_01_086: [** SASL-RESPONSE --> **]**
317 ...
318 **SRS_SASL_SERVER_IO_01_087: [** <-- SASL-OUTCOME **]**
319
320 * Note that **SRS_SASL_SERVER_IO_01_088: [** the SASL challenge/response step can occur zero or more times depending on the details of the SASL mechanism chosen. **]**
321
322 Figure 5.6: SASL Exchange
323
324 **SRS_SASL_SERVER_IO_01_089: [** The peer playing the role of the SASL client and the peer playing the role of the SASL server MUST correspond to the TCP client and server respectively. **]**
325
326 5.3.3 Security Frame Bodies
327
328 5.3.3.1 SASL Mechanisms
329
330 **SRS_SASL_SERVER_IO_01_090: [** Advertise available sasl mechanisms. **]**
331
332 \<type name="sasl-mechanisms" class="composite" source="list" provides="sasl-frame">
333 \<descriptor name="amqp:sasl-mechanisms:list" code="0x00000000:0x00000040"/>
334 \<field name="sasl-server-mechanisms" type="symbol" multiple="true" mandatory="true"/>
335 \</type>
336
337 Advertises the available SASL mechanisms that can be used for authentication.
338
339 Field Details
340
341 **SRS_SASL_SERVER_IO_01_091: [** sasl-server-mechanisms supported sasl mechanisms **]**
342
343 **SRS_SASL_SERVER_IO_01_092: [** A list of the sasl security mechanisms supported by the sending peer. **]**
344 **SRS_SASL_SERVER_IO_01_093: [** It is invalid for this list to be null or empty. **]**
345 **SRS_SASL_SERVER_IO_01_094: [** If the sending peer does not require its partner to authenticate with it, then it SHOULD send a list of one element with its value as the SASL mechanism ANONYMOUS. **]**
346 The server mechanisms are ordered in decreasing level of preference.
347
348 5.3.3.2 SASL Init
349
350 Initiate sasl exchange.
351
352 \<type name="sasl-init" class="composite" source="list" provides="sasl-frame">
353
354 \<descriptor name="amqp:sasl-init:list" code="0x00000000:0x00000041"/>
355
356 \<field name="mechanism" type="symbol" mandatory="true"/>
357
358 \<field name="initial-response" type="binary"/>
359
360 \<field name="hostname" type="string"/>
361
362 \</type>
363
364 **SRS_SASL_SERVER_IO_01_098: [** Selects the sasl mechanism and provides the initial response if needed. **]**
365
366 Field Details
367
368 mechanism selected security mechanism
369 **SRS_SASL_SERVER_IO_01_099: [** The name of the SASL mechanism used for the SASL exchange. **]**
370 **SRS_SASL_SERVER_IO_01_100: [** If the selected mechanism is not supported by the receiving peer, it MUST close the connection with the authentication-failure close-code. **]** Each peer MUST authenticate using the highest-level security profile it can handle from the list provided by the partner.
371 initial-response security response data
372 **SRS_SASL_SERVER_IO_01_101: [** A block of opaque data passed to the security mechanism. **]** The contents of this data are defined by the SASL security mechanism.
373 hostname the name of the target host
374 The DNS name of the host (either fully qualified or relative) to which the sending peer is connecting.
375 **SRS_SASL_SERVER_IO_01_102: [** It is not mandatory to provide the hostname. **]** If no hostname is provided the receiving peer SHOULD select a default based on its own configuration.
376 This field can be used by AMQP proxies to determine the correct back-end service to connect the client to, and to determine the domain to validate the client's credentials against.
377 This field might already have been specified by the server name indication extension as described in RFC-4366 [RFC4366, if a TLS layer is used, in which case this field SHOULD either be null or contain the same value.] It is undefined what a different value to those already specified means.
378
379 5.3.3.3 SASL Challenge
380
381 **SRS_SASL_SERVER_IO_01_103: [** Security mechanism challenge. **]**
382
383 \<type name="sasl-challenge" class="composite" source="list" provides="sasl-frame">
384
385 \<descriptor name="amqp:sasl-challenge:list" code="0x00000000:0x00000042"/>
386
387 \<field name="challenge" type="binary" mandatory="true"/>
388
389 \</type>
390
391 Send the SASL challenge data as defined by the SASL specification.
392
393 Field Details
394
395 challenge security challenge data
396
397 **SRS_SASL_SERVER_IO_01_104: [** Challenge information, a block of opaque binary data passed to the security mechanism. **]**
398
399 5.3.3.4 SASL Response
400
401 Security mechanism response.
402
403 \<type name="sasl-response" class="composite" source="list" provides="sasl-frame">
404
405 \<descriptor name="amqp:sasl-response:list" code="0x00000000:0x00000043"/>
406
407 \<field name="response" type="binary" mandatory="true"/>
408
409 \</type>
410
411 **SRS_SASL_SERVER_IO_01_105: [** Send the SASL response data as defined by the SASL specification. **]**
412
413 Field Details
414
415 response security response data
416
417 **SRS_SASL_SERVER_IO_01_106: [** A block of opaque data passed to the security mechanism. **]** The contents of this data are defined by the SASL security mechanism.
418
419 5.3.3.5 SASL Outcome
420
421 **SRS_SASL_SERVER_IO_01_107: [** Indicates the outcome of the sasl dialog. **]**
422
423 \<type name="sasl-outcome" class="composite" source="list" provides="sasl-frame">
424
425 \<descriptor name="amqp:sasl-outcome:list" code="0x00000000:0x00000044"/>
426
427 \<field name="code" type="sasl-code" mandatory="true"/>
428
429 \<field name="additional-data" type="binary"/>
430
431 \</type>
432
433 **SRS_SASL_SERVER_IO_01_108: [** This frame indicates the outcome of the SASL dialog. **]**
434 **SRS_SASL_SERVER_IO_01_109: [** Upon successful completion of the SASL dialog the security layer has been established **]**, and the peers MUST exchange protocol headers to either start a nested security layer, or to establish the AMQP connection.
435
436 Field Details
437
438 code indicates the outcome of the sasl dialog
439
440 **SRS_SASL_SERVER_IO_01_110: [** A reply-code indicating the outcome of the SASL dialog. **]**
441
442 additional-data additional data as specified in RFC-4422
443
444 **SRS_SASL_SERVER_IO_01_111: [** The additional-data field carries additional data on successful authentication outcome as specified by the SASL specification [RFC4422.] **]**
445 **SRS_SASL_SERVER_IO_01_112: [** If the authentication is unsuccessful, this field is not set. **]**
446
447 5.3.3.6 SASL Code
448
449 **SRS_SASL_SERVER_IO_01_113: [** Codes to indicate the outcome of the sasl dialog. **]**
450
451 \<type name="sasl-code" class="restricted" source="ubyte">
452
453 \<choice name="ok" value="0"/>
454
455 \<choice name="auth" value="1"/>
456
457 \<choice name="sys" value="2"/>
458
459 \<choice name="sys-perm" value="3"/>
460
461 \<choice name="sys-temp" value="4"/>
462
463 \</type>
464
465 Valid Values
466
467 **SRS_SASL_SERVER_IO_01_114: [** 0 Connection authentication succeeded. **]**
468 **SRS_SASL_SERVER_IO_01_115: [** 1 Connection authentication failed due to an unspecified problem with the supplied credentials. **]**
469 **SRS_SASL_SERVER_IO_01_116: [** 2 Connection authentication failed due to a system error. **]**
470 **SRS_SASL_SERVER_IO_01_117: [** 3 Connection authentication failed due to a system error that is unlikely to be corrected without intervention. **]**
471 **SRS_SASL_SERVER_IO_01_118: [** 4 Connection authentication failed due to a transient system error. **]**
472
473 5.3.4 Constant Definitions
474
475 SASL-MAJOR 1 major protocol version.
476 SASL-MINOR 0 minor protocol version.
477 SASL-REVISION 0 protocol revision.