| 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.**]** |