Debian Codegraph @

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

raw
1 # `sasl_server_mechanism` requirements
2
3 ## Overview
4
5 `sasl_server_mechanism` is a module that implements a SASL mechanism interface for the server portion of the SASL standard, abstracting from its consumers functionality of handling initial and subsequent responses as part of the SASL negotiation.
6
7 ## Exposed API
8
9 ```C
10 typedef struct SASL_SERVER_MECHANISM_INSTANCE_TAG* SASL_SERVER_MECHANISM_HANDLE;
11 typedef void* CONCRETE_SASL_SERVER_MECHANISM_HANDLE;
12
13 typedef struct SASL_SERVER_MECHANISM_BYTES_TAG
14 {
15 const void* bytes;
16 uint32_t length;
17 } SASL_SERVER_MECHANISM_BYTES;
18
19 typedef CONCRETE_SASL_SERVER_MECHANISM_HANDLE(*SASL_SERVER_MECHANISM_CREATE)(void* config);
20 typedef void(*SASL_SERVER_MECHANISM_DESTROY)(CONCRETE_SASL_SERVER_MECHANISM_HANDLE concrete_sasl_server_mechanism);
21 typedef int(*SASL_SERVER_MECHANISM_HANDLE_INITIAL_RESPONSE)(CONCRETE_SASL_SERVER_MECHANISM_HANDLE concrete_sasl_server_mechanism, const SASL_SERVER_MECHANISM_BYTES* initial_response_bytes, const char* hostname, bool* send_challenge, SASL_SERVER_MECHANISM_BYTES* challenge_bytes);
22 typedef int(*SASL_SERVER_MECHANISM_HANDLE_RESPONSE)(CONCRETE_SASL_SERVER_MECHANISM_HANDLE concrete_sasl_server_mechanism, const SASL_SERVER_MECHANISM_BYTES* response_bytes, bool* send_next_challenge, SASL_SERVER_MECHANISM_BYTES* next_challenge_bytes);
23 typedef const char*(*SASL_SERVER_MECHANISM_GET_MECHANISM_NAME)(void);
24
25 typedef struct SASL_SERVER_MECHANISM_INTERFACE_DESCRIPTION_TAG
26 {
27 SASL_SERVER_MECHANISM_CREATE create;
28 SASL_SERVER_MECHANISM_DESTROY destroy;
29 SASL_SERVER_MECHANISM_HANDLE_INITIAL_RESPONSE handle_initial_response;
30 SASL_SERVER_MECHANISM_HANDLE_RESPONSE handle_response;
31 SASL_SERVER_MECHANISM_GET_MECHANISM_NAME get_mechanism_name;
32 } SASL_SERVER_MECHANISM_INTERFACE_DESCRIPTION;
33
34 MOCKABLE_FUNCTION(, SASL_SERVER_MECHANISM_HANDLE, sasl_server_mechanism_create, const SASL_SERVER_MECHANISM_INTERFACE_DESCRIPTION*, sasl_server_mechanism_interface_description, void*, sasl_server_mechanism_create_parameters);
35 MOCKABLE_FUNCTION(, void, sasl_server_mechanism_destroy, SASL_SERVER_MECHANISM_HANDLE, sasl_server_mechanism);
36 MOCKABLE_FUNCTION(, int, sasl_server_mechanism_handle_initial_response, SASL_SERVER_MECHANISM_HANDLE, sasl_server_mechanism, const SASL_SERVER_MECHANISM_BYTES*, initial_response_bytes, const char*, hostname, bool*, send_challenge, SASL_SERVER_MECHANISM_BYTES*, challenge_bytes);
37 MOCKABLE_FUNCTION(, int, sasl_server_mechanism_handle_response, SASL_SERVER_MECHANISM_HANDLE, sasl_server_mechanism, const SASL_SERVER_MECHANISM_BYTES*, response_bytes, bool*, send_next_challenge, SASL_SERVER_MECHANISM_BYTES*, next_challenge_bytes);
38 MOCKABLE_FUNCTION(, const char*, sasl_server_mechanism_get_mechanism_name, SASL_SERVER_MECHANISM_HANDLE, sasl_server_mechanism);
39 ```
40
41 ### sasl_server_mechanism_create
42
43 ```C
44 MOCKABLE_FUNCTION(, SASL_SERVER_MECHANISM_HANDLE, sasl_server_mechanism_create, const SASL_SERVER_MECHANISM_INTERFACE_DESCRIPTION*, sasl_server_mechanism_interface_description, void*, sasl_server_mechanism_create_parameters);
45 ```
46
47 **SRS_SASL_SERVER_MECHANISM_01_001: [**`sasl_server_mechanism_create` shall return on success a non-NULL handle to a new SASL server mechanism interface.**]**
48
49 **SRS_SASL_SERVER_MECHANISM_01_002: [** In order to instantiate the concrete SASL server mechanism implementation the function `create` from the `sasl_server_mechanism_interface_description` shall be called, passing the `sasl_server_mechanism_create_parameters` to it.**]**
50
51 **SRS_SASL_SERVER_MECHANISM_01_003: [** If the underlying `create` call fails, `sasl_server_mechanism_create` shall return NULL. **]**
52
53 **SRS_SASL_SERVER_MECHANISM_01_004: [** If the argument `sasl_server_mechanism_interface_description` is NULL, `sasl_server_mechanism_create` shall return NULL.**]**
54
55 **SRS_SASL_SERVER_MECHANISM_01_005: [** If any `sasl_server_mechanism_interface_description` member is NULL, `sasl_server_mechanism_create` shall fail and return NULL.**]**
56
57 **SRS_SASL_SERVER_MECHANISM_01_006: [** If allocating the memory needed for the SASL server mechanism interface fails then `sasl_server_mechanism_create` shall fail and return NULL. **]**
58
59 ### sasl_server_mechanism_destroy
60
61 ```C
62 MOCKABLE_FUNCTION(, void, sasl_server_mechanism_destroy, SASL_SERVER_MECHANISM_HANDLE, sasl_server_mechanism);
63 ```
64
65 **SRS_SASL_SERVER_MECHANISM_01_007: [** `sasl_server_mechanism_destroy` shall free all resources associated with the SASL mechanism handle. **]**
66
67 **SRS_SASL_SERVER_MECHANISM_01_008: [** `sasl_server_mechanism_destroy` shall also call the `destroy` function that is member of the `sasl_mechanism_interface_description` argument passed to `sasl_server_mechanism_create`, while passing as argument to `destroy` the result of the underlying concrete SASL mechanism handle. **]**
68
69 **SRS_SASL_SERVER_MECHANISM_01_009: [** If the argument `sasl_server_mechanism` is NULL, `sasl_server_mechanism_destroy` shall do nothing. **]**
70
71 ### sasl_server_mechanism_handle_initial_response
72
73 ```C
74 MOCKABLE_FUNCTION(, int, sasl_server_mechanism_handle_initial_response, SASL_SERVER_MECHANISM_HANDLE, sasl_server_mechanism, const SASL_SERVER_MECHANISM_BYTES*, initial_response_bytes, const char*, hostname, bool*, send_challenge, SASL_SERVER_MECHANISM_BYTES*, challenge_bytes);
75 ```
76
77 **SRS_SASL_SERVER_MECHANISM_01_010: [** `sasl_server_mechanism_handle_initial_response` shall call the specific `handle_initial_response` function specified in `sasl_server_mechanism_create`, passing the `initial_response_bytes`, `hostname`, `send_challenge` and `challenge_bytes` arguments to it. **]**
78
79 **SRS_SASL_SERVER_MECHANISM_01_011: [** On success, `sasl_server_mechanism_handle_initial_response` shall return 0. **]**
80
81 **SRS_SASL_SERVER_MECHANISM_01_012: [** If the argument `sasl_server_mechanism` is NULL, `sasl_server_mechanism_handle_initial_response` shall fail and return a non-zero value. **]**
82
83 **SRS_SASL_SERVER_MECHANISM_01_013: [** If the underlying `handle_initial_response` fails, `sasl_server_mechanism_handle_initial_response` shall fail and return a non-zero value. **]**
84
85 ### sasl_server_mechanism_handle_response
86
87 ```C
88 MOCKABLE_FUNCTION(, int, sasl_server_mechanism_handle_response, SASL_SERVER_MECHANISM_HANDLE, sasl_server_mechanism, const SASL_SERVER_MECHANISM_BYTES*, response_bytes, bool*, send_next_challenge, SASL_SERVER_MECHANISM_BYTES*, next_challenge_bytes);
89 ```
90
91 **SRS_SASL_SERVER_MECHANISM_01_014: [** `sasl_server_mechanism_handle_response` shall call the specific `handle_response` function specified in `sasl_server_mechanism_create`, passing the `response_bytes`, `send_next_challenge` and `next_challenge_bytes` arguments to it. **]**
92
93 **SRS_SASL_SERVER_MECHANISM_01_016: [** On success, `sasl_server_mechanism_handle_response` shall return 0. **]**
94
95 **SRS_SASL_SERVER_MECHANISM_01_017: [** If the argument `sasl_server_mechanism` is NULL, `sasl_server_mechanism_handle_response` shall fail and return a non-zero value. **]**
96
97 **SRS_SASL_SERVER_MECHANISM_01_018: [** If the underlying `handle_response` fails, `sasl_server_mechanism_handle_response` shall fail and return a non-zero value. **]**
98
99 ### sasl_server_mechanism_get_mechanism_name
100
101 ```C
102 MOCKABLE_FUNCTION(, const char*, sasl_server_mechanism_get_mechanism_name, SASL_SERVER_MECHANISM_HANDLE, sasl_server_mechanism);
103 ```
104
105 **SRS_SASL_SERVER_MECHANISM_01_019: [** `sasl_server_mechanism_get_mechanism_name` shall call the specific `get_mechanism_name` function specified in `sasl_server_mechanism_create`. **]**
106
107 **SRS_SASL_SERVER_MECHANISM_01_020: [** On success, `sasl_server_mechanism_get_mechanism_name` shall return a pointer to a string with the mechanism name. **]**
108
109 **SRS_SASL_SERVER_MECHANISM_01_021: [** If the argument `sasl_server_mechanism` is NULL, `sasl_server_mechanism_get_mechanism_name` shall fail and return a non-zero value. **]**
110
111 **SRS_SASL_SERVER_MECHANISM_01_022: [** If the underlying `get_mechanism_name` fails, `sasl_server_mechanism_get_mechanism_name` shall return NULL. **]**