| 1 |
# sasl_frame_codec requirements |
| 2 |
|
| 3 |
## Overview |
| 4 |
|
| 5 |
`sasl_frame_codec` is module that encodes/decodes SASL frames per the AMQP ISO. |
| 6 |
|
| 7 |
## Exposed API |
| 8 |
|
| 9 |
```C |
| 10 |
#define SASL_MECHANISMS (uint64_t)0x40 |
| 11 |
#define SASL_INIT (uint64_t)0x41 |
| 12 |
#define SASL_CHALLENGE (uint64_t)0x42 |
| 13 |
#define SASL_RESPONSE (uint64_t)0x43 |
| 14 |
#define SASL_OUTCOME (uint64_t)0x44 |
| 15 |
|
| 16 |
typedef struct SASL_FRAME_CODEC_INSTANCE_TAG* SASL_FRAME_CODEC_HANDLE; |
| 17 |
typedef void(*ON_SASL_FRAME_RECEIVED)(void* context, AMQP_VALUE sasl_frame_value); |
| 18 |
typedef void(*ON_SASL_FRAME_CODEC_ERROR)(void* context); |
| 19 |
|
| 20 |
MOCKABLE_FUNCTION(, SASL_FRAME_CODEC_HANDLE, sasl_frame_codec_create, FRAME_CODEC_HANDLE, frame_codec, ON_SASL_FRAME_RECEIVED, on_sasl_frame_received, ON_SASL_FRAME_CODEC_ERROR, on_sasl_frame_codec_error, void*, callback_context); |
| 21 |
MOCKABLE_FUNCTION(, void, sasl_frame_codec_destroy, SASL_FRAME_CODEC_HANDLE, sasl_frame_codec); |
| 22 |
MOCKABLE_FUNCTION(, int, sasl_frame_codec_encode_frame, SASL_FRAME_CODEC_HANDLE, sasl_frame_codec, AMQP_VALUE, sasl_frame_value, ON_BYTES_ENCODED, on_bytes_encoded, void*, callback_context); |
| 23 |
``` |
| 24 |
|
| 25 |
### sasl_frame_codec_create |
| 26 |
|
| 27 |
```C |
| 28 |
MOCKABLE_FUNCTION(, SASL_FRAME_CODEC_HANDLE, sasl_frame_codec_create, FRAME_CODEC_HANDLE, frame_codec, ON_SASL_FRAME_RECEIVED, on_sasl_frame_received, ON_SASL_FRAME_CODEC_ERROR, on_sasl_frame_codec_error, void*, callback_context); |
| 29 |
``` |
| 30 |
|
| 31 |
**SRS_SASL_FRAME_CODEC_01_018: [**sasl_frame_codec_create shall create an instance of an sasl_frame_codec and return a non-NULL handle to it.**]** |
| 32 |
**SRS_SASL_FRAME_CODEC_01_019: [**If any of the arguments frame_codec, on_sasl_frame_received or on_sasl_frame_codec_error is NULL, sasl_frame_codec_create shall return NULL.**]** |
| 33 |
**SRS_SASL_FRAME_CODEC_01_020: [**sasl_frame_codec_create shall subscribe for SASL frames with the given frame_codec.**]** |
| 34 |
**SRS_SASL_FRAME_CODEC_01_021: [**If subscribing for SASL frames fails, sasl_frame_codec_create shall fail and return NULL.**]** |
| 35 |
**SRS_SASL_FRAME_CODEC_01_022: [**sasl_frame_codec_create shall create a decoder to be used for decoding SASL values.**]** |
| 36 |
**SRS_SASL_FRAME_CODEC_01_023: [**If creating the decoder fails, sasl_frame_codec_create shall fail and return NULL.**]** |
| 37 |
**SRS_SASL_FRAME_CODEC_01_024: [**If allocating memory for the new sasl_frame_codec fails, then sasl_frame_codec_create shall fail and return NULL.**]** |
| 38 |
|
| 39 |
### sasl_frame_codec_destroy |
| 40 |
|
| 41 |
```C |
| 42 |
MOCKABLE_FUNCTION(, void, sasl_frame_codec_destroy, SASL_FRAME_CODEC_HANDLE, sasl_frame_codec); |
| 43 |
``` |
| 44 |
|
| 45 |
**SRS_SASL_FRAME_CODEC_01_025: [**sasl_frame_codec_destroy shall free all resources associated with the sasl_frame_codec instance.**]** |
| 46 |
**SRS_SASL_FRAME_CODEC_01_026: [**If sasl_frame_codec is NULL, sasl_frame_codec_destroy shall do nothing.**]** |
| 47 |
**SRS_SASL_FRAME_CODEC_01_027: [**sasl_frame_codec_destroy shall unsubscribe from receiving SASL frames from the frame_codec that was passed to sasl_frame_codec_create.**]** |
| 48 |
**SRS_SASL_FRAME_CODEC_01_028: [**The decoder created in sasl_frame_codec_create shall be destroyed by sasl_frame_codec_destroy.**]** |
| 49 |
|
| 50 |
### sasl_frame_codec_encode_frame |
| 51 |
|
| 52 |
```C |
| 53 |
MOCKABLE_FUNCTION(, int, sasl_frame_codec_encode_frame, SASL_FRAME_CODEC_HANDLE, sasl_frame_codec, AMQP_VALUE, sasl_frame_value, ON_BYTES_ENCODED, on_bytes_encoded, void*, callback_context); |
| 54 |
``` |
| 55 |
|
| 56 |
**SRS_SASL_FRAME_CODEC_01_029: [**sasl_frame_codec_encode_frame shall encode the frame header and sasl_frame_value AMQP value in a SASL frame and on success it shall return 0.**]** |
| 57 |
**SRS_SASL_FRAME_CODEC_01_030: [**If sasl_frame_codec or sasl_frame_value is NULL, sasl_frame_codec_encode_frame shall fail and return a non-zero value.**]** |
| 58 |
**SRS_SASL_FRAME_CODEC_01_031: [**sasl_frame_codec_encode_frame shall encode the frame header and its contents by using frame_codec_encode_frame.**]** |
| 59 |
**SRS_SASL_FRAME_CODEC_01_032: [**The payload frame size shall be computed based on the encoded size of the sasl_frame_value and its fields.**]** |
| 60 |
**SRS_SASL_FRAME_CODEC_01_033: [**The encoded size of the sasl_frame_value and its fields shall be obtained by calling amqpvalue_get_encoded_size.**]** |
| 61 |
**SRS_SASL_FRAME_CODEC_01_034: [**If any error occurs during encoding, sasl_frame_codec_encode_frame shall fail and return a non-zero value.**]** |
| 62 |
**SRS_SASL_FRAME_CODEC_01_035: [**Encoding of the sasl_frame_value and its fields shall be done by calling amqpvalue_encode.**]** |
| 63 |
|
| 64 |
### Receive frames |
| 65 |
|
| 66 |
**SRS_SASL_FRAME_CODEC_01_039: [**sasl_frame_codec shall decode the sasl-frame value as a described type.**]** |
| 67 |
**SRS_SASL_FRAME_CODEC_01_040: [**Decoding the sasl-frame type shall be done by feeding the bytes to the decoder create in sasl_frame_codec_create.**]** |
| 68 |
**SRS_SASL_FRAME_CODEC_01_041: [**Once the sasl frame is decoded, the callback on_sasl_frame_received shall be called.**]** |
| 69 |
**SRS_SASL_FRAME_CODEC_01_042: [**The decoded sasl-frame value and the context passed in sasl_frame_codec_create shall be passed to on_sasl_frame_received.**]** |
| 70 |
**SRS_SASL_FRAME_CODEC_01_046: [**If any error occurs while decoding a frame, the decoder shall switch to an error state where decoding shall not be possible anymore.**]** |
| 71 |
**SRS_SASL_FRAME_CODEC_01_049: [**If any error occurs while decoding a frame, the decoder shall call the on_sasl_frame_codec_error and pass to it the callback_context, both of those being the ones given to sasl_frame_codec_create.**]** |
| 72 |
|
| 73 |
## ISO section (receive) |
| 74 |
|
| 75 |
5.3.1 SASL Frames |
| 76 |
|
| 77 |
SASL performatives are framed as per Part 2: section 2.3. **SRS_SASL_FRAME_CODEC_01_001: [**A SASL frame has a type code of 0x01.**]** **SRS_SASL_FRAME_CODEC_01_006: [**Bytes 6 and 7 of the header are ignored.**]** Implementations SHOULD set these to 0x00. **SRS_SASL_FRAME_CODEC_01_007: [**The extended header is ignored.**]** Implementations SHOULD therefore set DOFF to 0x02. |
| 78 |
|
| 79 |
... |
| 80 |
|
| 81 |
Figure 5.5: SASL Frame |
| 82 |
|
| 83 |
**SRS_SASL_FRAME_CODEC_01_008: [**The maximum size of a SASL frame is defined by MIN-MAX-FRAME-SIZE.**]** There is no mechanism within the SASL negotiation to negotiate a different size. **SRS_SASL_FRAME_CODEC_01_009: [**The frame body of a SASL frame MUST contain exactly one AMQP type, whose type encoding MUST have provides="sasl-frame".**]** **SRS_SASL_FRAME_CODEC_01_010: [**Receipt of an empty frame is an irrecoverable error.**]** |
| 84 |
|
| 85 |
## ISO section (send) |
| 86 |
|
| 87 |
5.3.1 SASL Frames |
| 88 |
|
| 89 |
SASL performatives are framed as per Part 2: section 2.3. **SRS_SASL_FRAME_CODEC_01_011: [**A SASL frame has a type code of 0x01.**]** **SRS_SASL_FRAME_CODEC_01_012: [**Bytes 6 and 7 of the header are ignored.**]** **SRS_SASL_FRAME_CODEC_01_013: [**Implementations SHOULD set these to 0x00.**]** **SRS_SASL_FRAME_CODEC_01_014: [**The extended header is ignored.**]** **SRS_SASL_FRAME_CODEC_01_015: [**Implementations SHOULD therefore set DOFF to 0x02.**]** |
| 90 |
|
| 91 |
... |
| 92 |
|
| 93 |
Figure 5.5: SASL Frame |
| 94 |
|
| 95 |
**SRS_SASL_FRAME_CODEC_01_016: [**The maximum size of a SASL frame is defined by MIN-MAX-FRAME-SIZE.**]** There is no mechanism within the SASL negotiation to negotiate a different size. |
| 96 |
**SRS_SASL_FRAME_CODEC_01_017: [**The minimum size of a SASL frame is defined by MIN_FRAME_SIZE (1 byte).**]** Allowing size of zero can expose a vulnerability to malloc attacks. |
| 97 |
**SRS_SASL_FRAME_CODEC_01_047: [**The frame body of a SASL frame MUST contain exactly one AMQP type, whose type encoding MUST have provides="sasl-frame".**]** Receipt of an empty frame is an irrecoverable error. |