Debian Codegraph @

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

raw
1 # saslclientio requirements
2
3 ## Overview
4
5 `saslclientio` is module that implements a SASL client concrete IO, per the section 5.3 of the AMQP ISO.
6
7 ## Exposed API
8
9 ```C
10 typedef struct SASLCLIENTIO_CONFIG_TAG
11 {
12 XIO_HANDLE underlying_io;
13 SASL_MECHANISM_HANDLE sasl_mechanism;
14 } SASLCLIENTIO_CONFIG;
15
16 MOCKABLE_FUNCTION(, const IO_INTERFACE_DESCRIPTION*, saslclientio_get_interface_description);
17 ```
18
19 ### saslclientio_create
20
21 ```C
22 CONCRETE_IO_HANDLE saslclientio_create(void* io_create_parameters);
23 ```
24
25 `saslclientio_create` is the implementation provided via `header_detect_io_get_interface_description` for the `concrete_io_create` member.
26
27 **SRS_SASLCLIENTIO_01_004: [**`saslclientio_create` shall return on success a non-NULL handle to a new SASL client IO instance.**]**
28
29 **SRS_SASLCLIENTIO_01_005: [**If `io_create_parameters` is NULL, `saslclientio_create` shall fail and return NULL.**]**
30
31 **SRS_SASLCLIENTIO_01_006: [**If memory cannot be allocated for the new instance, `saslclientio_create` shall fail and return NULL.**]**
32
33 **SRS_SASLCLIENTIO_01_089: [**`saslclientio_create` shall create a frame codec to be used for encoding/decoding frames by calling `frame_codec_create` and passing `on_frame_codec_error` and a context as arguments.**]**
34
35 **SRS_SASLCLIENTIO_01_090: [**If `frame_codec_create` fails, then `saslclientio_create` shall fail and return NULL.**]**
36
37 **SRS_SASLCLIENTIO_01_084: [**`saslclientio_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.**]**
38
39 **SRS_SASLCLIENTIO_01_085: [**If `sasl_frame_codec_create` fails, then `saslclientio_create` shall fail and return NULL.**]**
40
41 **SRS_SASLCLIENTIO_01_092: [**If any of the `sasl_mechanism` or `underlying_io` members of the configuration structure are NULL, `saslclientio_create` shall fail and return NULL.**]**
42
43 ### saslclientio_destroy
44
45 ```C
46 void saslclientio_destroy(CONCRETE_IO_HANDLE sasl_client_io);
47 ```
48
49 `saslclientio_destroy` is the implementation provided via `header_detect_io_get_interface_description` for the `concrete_io_destroy` member.
50
51 **SRS_SASLCLIENTIO_01_007: [**`saslclientio_destroy` shall free all resources associated with the SASL client IO handle.**]**
52
53 **SRS_SASLCLIENTIO_01_086: [**`saslclientio_destroy` shall destroy the SASL frame codec created in `saslclientio_create` by calling `sasl_frame_codec_destroy`.**]**
54
55 **SRS_SASLCLIENTIO_01_091: [**`saslclientio_destroy` shall destroy the frame codec created in `saslclientio_create` by calling `frame_codec_destroy`.**]**
56
57 **SRS_SASLCLIENTIO_01_008: [**If the argument `sasl_client_io` is NULL, `saslclientio_destroy` shall do nothing.**]**
58
59 ### saslclientio_open_async
60
61 ```C
62 int saslclientio_open_async(CONCRETE_IO_HANDLE sasl_client_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);
63 ```
64
65 `saslclientio_open_async` is the implementation provided via `header_detect_io_get_interface_description` for the `concrete_io_open` member.
66
67 **SRS_SASLCLIENTIO_01_009: [**`saslclientio_open` shall call `xio_open` on the `underlying_io` passed to `saslclientio_create`.**]**
68
69 **SRS_SASLCLIENTIO_01_010: [**On success, `saslclientio_open_async` shall return 0.**]**
70
71 **SRS_SASLCLIENTIO_01_011: [**If any of the `sasl_client_io`, `on_io_open_complete`, `on_bytes_received` or `on_io_error` arguments is NULL, `saslclientio_open` shall fail and return a non-zero value.**]**
72
73 **SRS_SASLCLIENTIO_01_012: [**If the open of the `underlying_io` fails, `saslclientio_open_async` shall fail and return non-zero value.**]**
74
75 **SRS_SASLCLIENTIO_01_013: [**`saslclientio_open_async` shall pass to `xio_open` the `on_underlying_io_open_complete` as `on_io_open_complete` argument, `on_underlying_io_bytes_received` as `on_bytes_received` argument and `on_underlying_io_error` as `on_io_error` argument.**]**
76
77 ### saslclientio_close_async
78
79 ```C
80 int saslclientio_close_async(CONCRETE_IO_HANDLE sasl_client_io, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* on_io_close_complete_context);
81 ```
82
83 `saslclientio_close_async` is the implementation provided via `header_detect_io_get_interface_description` for the `concrete_io_close` member.
84
85 **SRS_SASLCLIENTIO_01_015: [**`saslclientio_close_async` shall close the underlying io handle passed in `saslclientio_create` by calling `xio_close`.**]**
86
87 **SRS_SASLCLIENTIO_01_016: [**On success, `saslclientio_close_async` shall return 0.**]**
88
89 **SRS_SASLCLIENTIO_01_098: [**`saslclientio_close_async` shall only perform the close if the state is OPEN, OPENING or ERROR.**]**
90
91 **SRS_SASLCLIENTIO_01_097: [**If `saslclientio_close_async` is called when the IO is in the `IO_STATE_NOT_OPEN` state, `saslclientio_close_async` shall fail and return a non zero value.**]**
92
93 **SRS_SASLCLIENTIO_01_017: [**If `sasl_client_io` is NULL, `saslclientio_close_async` shall fail and return a non-zero value.**]**
94
95 **SRS_SASLCLIENTIO_01_018: [**If `xio_close` fails, then `saslclientio_close_async` shall return a non-zero value.**]**
96
97 ### saslclientio_send_async
98
99 ```C
100 int saslclientio_send_async(CONCRETE_IO_HANDLE sasl_client_io, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context);
101 ```
102
103 `saslclientio_send_async` is the implementation provided via `header_detect_io_get_interface_description` for the `concrete_io_send` member.
104
105 **SRS_SASLCLIENTIO_01_019: [**If `saslclientio_send_async` is called while the SASL client IO state is not `IO_STATE_OPEN`, `saslclientio_send_async` shall fail and return a non-zero value.**]**
106
107 **SRS_SASLCLIENTIO_01_020: [**If the SASL client IO state is `IO_STATE_OPEN`, `saslclientio_send_async` shall call `xio_send` on the `underlying_io` passed to `saslclientio_create`, while passing as arguments the `buffer`,`size`, `on_send_complete` and `callback_context`.**]**
108
109 **SRS_SASLCLIENTIO_01_021: [**On success, `saslclientio_send_async` shall return 0.**]**
110
111 **SRS_SASLCLIENTIO_01_022: [**If the `sasl_client_io` or `buffer` argument is NULL, `saslclientio_send_async` shall fail and return a non-zero value.**]**
112
113 **SRS_SASLCLIENTIO_01_023: [**If `size` is 0, `saslclientio_send_async` shall fail and return a non-zero value.**]**
114
115 **SRS_SASLCLIENTIO_01_127: [** `on_send_complete` shall be allowed to be NULL. **]**
116
117 **SRS_SASLCLIENTIO_01_024: [**If the call to `xio_send` fails, then `saslclientio_send_async` shall fail and return a non-zero value.**]**
118
119 ### saslclientio_dowork
120
121 ```C
122 void saslclientio_dowork(CONCRETE_IO_HANDLE sasl_client_io);
123 ```
124
125 `saslclientio_dowork` is the implementation provided via `header_detect_io_get_interface_description` for the `concrete_io_dowork` member.
126
127 **SRS_SASLCLIENTIO_01_025: [**`saslclientio_dowork` shall call the `xio_dowork` on the `underlying_io` passed in `saslclientio_create`.**]**
128
129 **SRS_SASLCLIENTIO_01_099: [**If the state of the IO is `IO_NOT_OPEN`, `saslclientio_dowork` shall make no calls to the underlying IO.**]**
130
131 **SRS_SASLCLIENTIO_01_026: [**If the `sasl_client_io` argument is NULL, `saslclientio_dowork` shall do nothing.**]**
132
133 ### saslclientio_get_interface_description
134
135 ```C
136 MOCKABLE_FUNCTION(, const IO_INTERFACE_DESCRIPTION*, saslclientio_get_interface_description);
137 ```
138
139 **SRS_SASLCLIENTIO_01_087: [**`saslclientio_get_interface_description` shall return a pointer to an `IO_INTERFACE_DESCRIPTION` structure that contains pointers to the functions: `saslclientio_create`, `saslclientio_destroy`, `saslclientio_open_async`, `saslclientio_close_async`, `saslclientio_send_async`, `saslclientio_setoption`, `saslclientio_retrieveoptions` and `saslclientio_dowork`.**]**
140
141 ### saslclientio_setoption
142
143 ```C
144 int saslclientio_setoption(CONCRETE_IO_HANDLE sasl_client_io, const char* option_name, const void* value);
145 ```
146
147 `saslclientio_setoption` is the implementation provided via `header_detect_io_get_interface_description` for the `concrete_io_setoption` member.
148
149 **SRS_SASLCLIENTIO_03_001: [**`saslclientio_setoption` shall forward all unhandled options to underlying io by calling `xio_setoption`.**]**
150
151 **SRS_SASLCLIENTIO_01_128: [** On success, `saslclientio_setoption` shall return 0. **]**
152
153 **SRS_SASLCLIENTIO_01_129: [** If `xio_setoption` fails, `saslclientio_setoption` shall fail and return a non-zero value. **]**
154
155 **SRS_SASLCLIENTIO_01_130: [** If `sasl_client_io` or `option_name` is NULL, `saslclientio_setoption` shall fail and return a non-zero value. **]**
156
157 **SRS_SASLCLIENTIO_01_131: [** SASL client IO shall handle the following options: **]**
158
159 **SRS_SASLCLIENTIO_01_132: [** - logtrace - bool. **]**
160
161 ### saslclientio_retrieveoption
162
163 ```C
164 OPTIONHANDLER_HANDLE saslclientio_retrieveoptions(CONCRETE_IO_HANDLE sasl_client_io);
165 ```
166
167 `saslclientio_retrieveoptions` is the implementation provided via `header_detect_io_get_interface_description` for the `concrete_io_retrieveoptions` member.
168
169 **SRS_SASLCLIENTIO_01_133: [** `saslclientio_retrieveoptions` shall create an option handler by calling `OptionHandler_Create`. **]**
170
171 **SRS_SASLCLIENTIO_01_134: [** `saslclientio_retrieveoptions` shall add the handled options to it: **]**
172
173 **SRS_SASLCLIENTIO_01_135: [** - logtrace - bool. **]**
174
175 **SRS_SASLCLIENTIO_01_136: [** If the `logtrace` option was not set it shall not be added to the option Handler. **]**
176
177 **SRS_SASLCLIENTIO_01_137: [** The options shall be added by calling `OptionHandler_AddOption`. **]**
178
179 **SRS_SASLCLIENTIO_01_138: [** If `OptionHandler_AddOption` or `OptionHandler_Create` fails then `saslclientio_retrieveoptions` shall fail and return NULL. **]**
180
181 **SRS_SASLCLIENTIO_01_139: [** When `saslclientio_retrieveoptions` is called with NULL `sasl_client_io` it shall fail and return NULL. **]**
182
183 ### on_underlying_io_bytes_received
184
185 ```C
186 void on_underlying_io_bytes_received(void* context, const unsigned char* buffer, size_t size)
187 ```
188
189 **SRS_SASLCLIENTIO_01_027: [**When the `on_underlying_io_bytes_received` callback passed to the underlying IO is called and the SASL client IO state is `IO_STATE_OPEN`, the bytes shall be indicated to the user of SASL client IO by calling the `on_bytes_received` callback that was passed in `saslclientio_open`.**]**
190
191 **SRS_SASLCLIENTIO_01_140: [** If the `context` argument is NULL, `on_underlying_io_bytes_received` shall do nothing. **]**
192
193 **SRS_SASLCLIENTIO_01_028: [**If `buffer` is NULL or `size` is zero, nothing should be indicated as received, the state shall be switched to ERROR and the `on_io_error` callback shall be triggered.**]**
194
195 **SRS_SASLCLIENTIO_01_029: [**The `context` argument for `on_io_error` shall be set to the `on_io_error_context` passed in `saslclientio_open`.**]**
196
197 **SRS_SASLCLIENTIO_01_030: [**If bytes are received when the SASL client IO state is `IO_STATE_OPENING`, the bytes shall be consumed by the SASL client IO to satisfy the SASL handshake.**]**
198
199 **SRS_SASLCLIENTIO_01_031: [**If bytes are received when the SASL client IO state is `IO_STATE_ERROR`, SASL client IO shall do nothing.**]**
200
201 ### State handling
202
203 The following actions matrix shall be implemented when a new state change is received from the underlying IO:
204
205 |SASL state\new underlying IO state|`NOT_OPEN` |`OPENING` |`OPEN` |`ERROR` |
206 |----------------------------------|-------------|-------------------------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------|
207 |`NOT_OPEN` |do nothing |do nothing |do nothing |do nothing |
208 |`OPENING` |not possible |do nothing |**`SRS_SASLCLIENTIO_01_105`: [**start header exchange**]**|**SRS_SASLCLIENTIO_01_101: [**`on_open_complete` with `IO_OPEN_ERROR`**]**|
209 |`OPEN` |not possible |**`SRS_SASLCLIENTIO_01_110`: [**raise ERROR**]** |**`SRS_SASLCLIENTIO_01_106`: [**raise error**]** |**SRS_SASLCLIENTIO_01_102: [**raise ERROR**]** |
210 |`ERROR` |not possible |**`SRS_SASLCLIENTIO_01_111`: [**do nothing**]** |**`SRS_SASLCLIENTIO_01_107`: [**do nothing**]** |**SRS_SASLCLIENTIO_01_103: [**do nothing**]** |
211
212 Starting the header exchange is done as follows:
213
214 **SRS_SASLCLIENTIO_01_078: [**SASL client IO shall start the header exchange by sending the SASL header.**]**
215
216 **SRS_SASLCLIENTIO_01_095: [**Sending the header shall be done by using `xio_send`.**]**
217
218 **SRS_SASLCLIENTIO_01_077: [**If sending the SASL header fails, the `on_io_open_complete` callback shall be triggered with `IO_OPEN_ERROR`.**]**
219
220 **SRS_SASLCLIENTIO_01_116: [**If the underlying IO indicates another open while the after the header exchange has been started an error shall be indicated by calling `on_io_error`.**]**
221
222 ### on_sasl_frame_received_callback
223
224 ```C
225 void on_sasl_frame_received_callback(void* context, AMQP_VALUE sasl_frame);
226 ```
227
228 **SRS_SASLCLIENTIO_01_117: [**If `on_sasl_frame_received_callback` is called when the state of the IO is OPEN then the `on_io_error` callback shall be triggered.**]**
229
230 **SRS_SASLCLIENTIO_01_118: [**If `on_sasl_frame_received_callback` is called in the OPENING state but the header exchange has not yet been completed, then the `on_io_error` callback shall be triggered.**]**
231 When a frame is indicated as received by sasl_frame_codec it shall be processed as described in the ISO.
232
233 **SRS_SASLCLIENTIO_01_070: [**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_SASLCLIENTIO_01_071: [**If `sasl_frame_codec_encode_frame` fails, then the `on_io_error` callback shall be triggered.**]**
236
237 **SRS_SASLCLIENTIO_01_072: [**When the SASL handshake is complete, if the handshake is successful, the SASL client IO state shall be switched to `IO_STATE_OPEN` and the `on_io_open_complete` callback shall be called with `IO_OPEN_OK`.**]**
238
239 **SRS_SASLCLIENTIO_01_119: [**If any error is encountered when parsing the received frame, the `on_io_open_complete` callback shall be triggered with `IO_OPEN_ERROR`.**]**
240
241 **SRS_SASLCLIENTIO_01_073: [**If the handshake fails (i.e. the outcome is an error) the `on_io_open_complete` callback shall be triggered with `IO_OPEN_ERROR`.**]**
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_SASLCLIENTIO_01_120: [**When SASL client IO is notified by `sasl_frame_codec` of bytes that have been encoded via the `on_bytes_encoded` callback and SASL client IO is in the state OPENING, SASL client IO shall send these bytes by using `xio_send`.**]**
250
251 **SRS_SASLCLIENTIO_01_121: [**If `xio_send` fails, the `on_io_error` callback shall be triggered.**]**
252
253 ### on_frame_codec_error
254
255 ```C
256 void on_frame_codec_error(void* context);
257 ```
258
259 **SRS_SASLCLIENTIO_01_122: [**When `on_frame_codec_error` is called while in the OPENING state the `on_io_open_complete` callback shall be triggered with `IO_OPEN_ERROR`.**]**
260
261 **SRS_SASLCLIENTIO_01_143: [** When `on_frame_codec_error` is called while in the OPEN state the `on_io_error` callback shall be triggered. **]**
262
263 **SRS_SASLCLIENTIO_01_123: [**When `on_frame_codec_error` is called in the ERROR state nothing shall be done.**]**
264
265 ### on_sasl_frame_codec_error
266
267 ```C
268 void on_sasl_frame_codec_error(void* context);
269 ```
270
271 **SRS_SASLCLIENTIO_01_141: [** When `on_sasl_frame_codec_error` is called while in the OPENING state the `on_io_open_complete` callback shall be triggered with `IO_OPEN_ERROR`. **]**
272
273 **SRS_SASLCLIENTIO_01_144: [** When `on_sasl_frame_codec_error` is called while OPEN state the `on_io_error` callback shall be triggered. **]**
274
275 **SRS_SASLCLIENTIO_01_142: [** When `on_sasl_frame_codec_error` is called in the ERROR state nothing shall be done. **]**
276
277 ## SASL negotiation
278
279 **SRS_SASLCLIENTIO_01_067: [**The SASL frame exchange shall be started as soon as the SASL header handshake is done.**]**
280
281 **SRS_SASLCLIENTIO_01_068: [**During the SASL frame exchange that constitutes the handshake the received bytes from the underlying IO shall be fed to the frame codec instance created in `saslclientio_create` by calling `frame_codec_receive_bytes`.**]**
282
283 **SRS_SASLCLIENTIO_01_088: [**If `frame_codec_receive_bytes` fails, the `on_io_error` callback shall be triggered.**]**
284
285 ## ISO section
286
287 **SRS_SASLCLIENTIO_01_001: [**To establish a SASL layer, each peer MUST start by sending a protocol header.**]**
288 **SRS_SASLCLIENTIO_01_002: [**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:
289
290 ...
291
292 Figure 5.3: Protocol Header for SASL Security Layer
293
294 **SRS_SASLCLIENTIO_01_003: [**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).**]**
295 The following diagram illustrates the interaction involved in creating a SASL security layer:
296
297 ...
298
299 Figure 5.4: Establishing a SASL Security Layer
300
301 SASL Negotiation
302
303 **SRS_SASLCLIENTIO_01_032: [**The peer acting as the SASL server MUST announce supported authentication mechanisms using the sasl-mechanisms frame.**]**
304 **SRS_SASLCLIENTIO_01_033: [**The partner MUST then choose one of the supported mechanisms and initiate a sasl exchange.**]**
305
306 SASL Client SASL Server
307
308 **SRS_SASLCLIENTIO_01_034: [**<-- SASL-MECHANISMS**]**
309 **SRS_SASLCLIENTIO_01_035: [**SASL-INIT -->**]**
310 ...
311 **SRS_SASLCLIENTIO_01_036: [**<-- SASL-CHALLENGE ***]**
312 **SRS_SASLCLIENTIO_01_037: [**SASL-RESPONSE -->**]**
313 ...
314 **SRS_SASLCLIENTIO_01_038: [**<-- SASL-OUTCOME**]**
315
316 * Note that **SRS_SASLCLIENTIO_01_039: [**the SASL challenge/response step can occur zero or more times depending on the details of the SASL mechanism chosen.**]**
317
318 Figure 5.6: SASL Exchange
319
320 **SRS_SASLCLIENTIO_01_040: [**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.**]**
321
322 5.3.3 Security Frame Bodies
323
324 5.3.3.1 SASL Mechanisms
325
326 Advertise available sasl mechanisms.
327
328 \<type name="sasl-mechanisms" class="composite" source="list" provides="sasl-frame">
329 \<descriptor name="amqp:sasl-mechanisms:list" code="0x00000000:0x00000040"/>
330 \<field name="sasl-server-mechanisms" type="symbol" multiple="true" mandatory="true"/>
331 \</type>
332
333 Advertises the available SASL mechanisms that can be used for authentication.
334
335 Field Details
336
337 sasl-server-mechanisms supported sasl mechanisms
338
339 **SRS_SASLCLIENTIO_01_041: [**A list of the sasl security mechanisms supported by the sending peer.**]** **SRS_SASLCLIENTIO_01_042: [**It is invalid for this list to be null or empty.**]** 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. **SRS_SASLCLIENTIO_01_043: [**The server mechanisms are ordered in decreasing level of preference.**]**
340
341 5.3.3.2 SASL Init
342
343 Initiate sasl exchange.
344
345 \<type name="sasl-init" class="composite" source="list" provides="sasl-frame">
346
347 \<descriptor name="amqp:sasl-init:list" code="0x00000000:0x00000041"/>
348
349 \<field name="mechanism" type="symbol" mandatory="true"/>
350
351 \<field name="initial-response" type="binary"/>
352
353 \<field name="hostname" type="string"/>
354
355 \</type>
356
357 **SRS_SASLCLIENTIO_01_054: [**Selects the sasl mechanism and provides the initial response if needed.**]**
358
359 Field Details
360
361 mechanism selected security mechanism
362
363 **SRS_SASLCLIENTIO_01_045: [**The name of the SASL mechanism used for the SASL exchange.**]** If the selected mechanism is not supported by the receiving peer, it MUST close the connection with the authentication-failure close-code. **SRS_SASLCLIENTIO_01_046: [**Each peer MUST authenticate using the highest-level security profile it can handle from the list provided by the partner.**]**
364 initial-response security response data
365 **SRS_SASLCLIENTIO_01_047: [**A block of opaque data passed to the security mechanism.**]** **SRS_SASLCLIENTIO_01_048: [**The contents of this data are defined by the SASL security mechanism.**]**
366 hostname the name of the target host
367 **SRS_SASLCLIENTIO_01_049: [**The DNS name of the host (either fully qualified or relative) to which the sending peer is connecting.**]**
368 **SRS_SASLCLIENTIO_01_050: [**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.
369 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.
370 **SRS_SASLCLIENTIO_01_051: [**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.
371
372 5.3.3.3 SASL Challenge
373
374 Security mechanism challenge.
375
376 \<type name="sasl-challenge" class="composite" source="list" provides="sasl-frame">
377
378 \<descriptor name="amqp:sasl-challenge:list" code="0x00000000:0x00000042"/>
379
380 \<field name="challenge" type="binary" mandatory="true"/>
381
382 \</type>
383
384 **SRS_SASLCLIENTIO_01_052: [**Send the SASL challenge data as defined by the SASL specification.**]**
385
386 Field Details
387
388 challenge security challenge data
389
390 **SRS_SASLCLIENTIO_01_053: [**Challenge information, a block of opaque binary data passed to the security mechanism.**]**
391
392 5.3.3.4 SASL Response
393
394 Security mechanism response.
395
396 \<type name="sasl-response" class="composite" source="list" provides="sasl-frame">
397
398 \<descriptor name="amqp:sasl-response:list" code="0x00000000:0x00000043"/>
399
400 \<field name="response" type="binary" mandatory="true"/>
401
402 \</type>
403
404 **SRS_SASLCLIENTIO_01_055: [**Send the SASL response data as defined by the SASL specification.**]**
405
406 Field Details
407
408 response security response data
409
410 **SRS_SASLCLIENTIO_01_056: [**A block of opaque data passed to the security mechanism.**]** **SRS_SASLCLIENTIO_01_057: [**The contents of this data are defined by the SASL security mechanism.**]**
411
412 5.3.3.5 SASL Outcome
413
414 Indicates the outcome of the sasl dialog.
415
416 \<type name="sasl-outcome" class="composite" source="list" provides="sasl-frame">
417
418 \<descriptor name="amqp:sasl-outcome:list" code="0x00000000:0x00000044"/>
419
420 \<field name="code" type="sasl-code" mandatory="true"/>
421
422 \<field name="additional-data" type="binary"/>
423
424 \</type>
425
426 **SRS_SASLCLIENTIO_01_058: [**This frame indicates the outcome of the SASL dialog.**]****SRS_SASLCLIENTIO_01_059: [**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.
427
428 Field Details
429
430 code indicates the outcome of the sasl dialog
431
432 **SRS_SASLCLIENTIO_01_060: [**A reply-code indicating the outcome of the SASL dialog.**]**
433
434 additional-data additional data as specified in RFC-4422
435
436 **SRS_SASLCLIENTIO_01_061: [**The additional-data field carries additional data on successful authentication outcome as specified by the SASL specification [RFC4422**]**.] If the authentication is unsuccessful, this field is not set.
437
438 5.3.3.6 SASL Code
439
440 Codes to indicate the outcome of the sasl dialog.
441
442 \<type name="sasl-code" class="restricted" source="ubyte">
443
444 \<choice name="ok" value="0"/>
445
446 \<choice name="auth" value="1"/>
447
448 \<choice name="sys" value="2"/>
449
450 \<choice name="sys-perm" value="3"/>
451
452 \<choice name="sys-temp" value="4"/>
453
454 \</type>
455
456 Valid Values
457
458 **SRS_SASLCLIENTIO_01_062: [**0 Connection authentication succeeded.**]**
459 **SRS_SASLCLIENTIO_01_063: [**1 Connection authentication failed due to an unspecified problem with the supplied credentials.**]**
460 **SRS_SASLCLIENTIO_01_064: [**2 Connection authentication failed due to a system error.**]**
461 **SRS_SASLCLIENTIO_01_065: [**3 Connection authentication failed due to a system error that is unlikely to be corrected without intervention.**]**
462 **SRS_SASLCLIENTIO_01_066: [**4 Connection authentication failed due to a transient system error.**]**
463
464 5.3.4 Constant Definitions
465
466 **SRS_SASLCLIENTIO_01_124: [**SASL-MAJOR 1 major protocol version.**]**
467 **SRS_SASLCLIENTIO_01_125: [**SASL-MINOR 0 minor protocol version.**]**
468 **SRS_SASLCLIENTIO_01_126: [**SASL-REVISION 0 protocol revision.**]**