# sasl_frame_codec requirements ## Overview `sasl_frame_codec` is module that encodes/decodes SASL frames per the AMQP ISO. ## Exposed API ```C #define SASL_MECHANISMS (uint64_t)0x40 #define SASL_INIT (uint64_t)0x41 #define SASL_CHALLENGE (uint64_t)0x42 #define SASL_RESPONSE (uint64_t)0x43 #define SASL_OUTCOME (uint64_t)0x44 typedef struct SASL_FRAME_CODEC_INSTANCE_TAG* SASL_FRAME_CODEC_HANDLE; typedef void(*ON_SASL_FRAME_RECEIVED)(void* context, AMQP_VALUE sasl_frame_value); typedef void(*ON_SASL_FRAME_CODEC_ERROR)(void* context); 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); MOCKABLE_FUNCTION(, void, sasl_frame_codec_destroy, SASL_FRAME_CODEC_HANDLE, sasl_frame_codec); 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); ``` ### sasl_frame_codec_create ```C 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); ``` **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.**]** **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.**]** **SRS_SASL_FRAME_CODEC_01_020: [**sasl_frame_codec_create shall subscribe for SASL frames with the given frame_codec.**]** **SRS_SASL_FRAME_CODEC_01_021: [**If subscribing for SASL frames fails, sasl_frame_codec_create shall fail and return NULL.**]** **SRS_SASL_FRAME_CODEC_01_022: [**sasl_frame_codec_create shall create a decoder to be used for decoding SASL values.**]** **SRS_SASL_FRAME_CODEC_01_023: [**If creating the decoder fails, sasl_frame_codec_create shall fail and return NULL.**]** **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.**]** ### sasl_frame_codec_destroy ```C MOCKABLE_FUNCTION(, void, sasl_frame_codec_destroy, SASL_FRAME_CODEC_HANDLE, sasl_frame_codec); ``` **SRS_SASL_FRAME_CODEC_01_025: [**sasl_frame_codec_destroy shall free all resources associated with the sasl_frame_codec instance.**]** **SRS_SASL_FRAME_CODEC_01_026: [**If sasl_frame_codec is NULL, sasl_frame_codec_destroy shall do nothing.**]** **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.**]** **SRS_SASL_FRAME_CODEC_01_028: [**The decoder created in sasl_frame_codec_create shall be destroyed by sasl_frame_codec_destroy.**]** ### sasl_frame_codec_encode_frame ```C 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); ``` **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.**]** **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.**]** **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.**]** **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.**]** **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.**]** **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.**]** **SRS_SASL_FRAME_CODEC_01_035: [**Encoding of the sasl_frame_value and its fields shall be done by calling amqpvalue_encode.**]** ### Receive frames **SRS_SASL_FRAME_CODEC_01_039: [**sasl_frame_codec shall decode the sasl-frame value as a described type.**]** **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.**]** **SRS_SASL_FRAME_CODEC_01_041: [**Once the sasl frame is decoded, the callback on_sasl_frame_received shall be called.**]** **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.**]** **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.**]** **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.**]** ## ISO section (receive) 5.3.1 SASL Frames 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. ... Figure 5.5: SASL Frame **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.**]** ## ISO section (send) 5.3.1 SASL Frames 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.**]** ... Figure 5.5: SASL Frame **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. **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. **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.