Debian Codegraph @

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

raw
1 # `sasl_mechanism` requirements
2
3 ## Overview
4
5 `sasl_mechanism` is a module that implements a SASL mechanism interface, abstracting from its consumers functionality of providing init bytes, handling the challenge and providing a response for it as part of the SASL negotiation.
6
7 ## Exposed API
8
9 ```C
10 typedef struct SASL_MECHANISM_INSTANCE_TAG* SASL_MECHANISM_HANDLE;
11 typedef void* CONCRETE_SASL_MECHANISM_HANDLE;
12
13 typedef struct SASL_MECHANISM_BYTES_TAG
14 {
15 const void* bytes;
16 uint32_t length;
17 } SASL_MECHANISM_BYTES;
18
19 typedef CONCRETE_SASL_MECHANISM_HANDLE(*SASL_MECHANISM_CREATE)(void* config);
20 typedef void(*SASL_MECHANISM_DESTROY)(CONCRETE_SASL_MECHANISM_HANDLE concrete_sasl_mechanism);
21 typedef int(*SASL_MECHANISM_GET_INIT_BYTES)(CONCRETE_SASL_MECHANISM_HANDLE concrete_sasl_mechanism, SASL_MECHANISM_BYTES* init_bytes);
22 typedef const char*(*SASL_MECHANISM_GET_MECHANISM_NAME)(CONCRETE_SASL_MECHANISM_HANDLE concrete_sasl_mechanism);
23 typedef int(*SASL_MECHANISM_CHALLENGE)(CONCRETE_SASL_MECHANISM_HANDLE concrete_sasl_mechanism, const SASL_MECHANISM_BYTES* challenge_bytes, SASL_MECHANISM_BYTES* response_bytes);
24
25 typedef struct SASL_MECHANISM_INTERFACE_TAG
26 {
27 SASL_MECHANISM_CREATE concrete_sasl_mechanism_create;
28 SASL_MECHANISM_DESTROY concrete_sasl_mechanism_destroy;
29 SASL_MECHANISM_GET_INIT_BYTES concrete_sasl_mechanism_get_init_bytes;
30 SASL_MECHANISM_GET_MECHANISM_NAME concrete_sasl_mechanism_get_mechanism_name;
31 SASL_MECHANISM_CHALLENGE concrete_sasl_mechanism_challenge;
32 } SASL_MECHANISM_INTERFACE_DESCRIPTION;
33
34 MOCKABLE_FUNCTION(, SASL_MECHANISM_HANDLE, saslmechanism_create, const SASL_MECHANISM_INTERFACE_DESCRIPTION*, sasl_mechanism_interface_description, void*, sasl_mechanism_create_parameters);
35 MOCKABLE_FUNCTION(, void, saslmechanism_destroy, SASL_MECHANISM_HANDLE, sasl_mechanism);
36 MOCKABLE_FUNCTION(, int, saslmechanism_get_init_bytes, SASL_MECHANISM_HANDLE, sasl_mechanism, SASL_MECHANISM_BYTES*, init_bytes);
37 MOCKABLE_FUNCTION(, const char*, saslmechanism_get_mechanism_name, SASL_MECHANISM_HANDLE, sasl_mechanism);
38 MOCKABLE_FUNCTION(, int, saslmechanism_challenge, SASL_MECHANISM_HANDLE, sasl_mechanism, const SASL_MECHANISM_BYTES*, challenge_bytes, SASL_MECHANISM_BYTES*, response_bytes);
39 ```
40
41 ### saslmechanism_create
42
43 ```C
44 MOCKABLE_FUNCTION(, SASL_MECHANISM_HANDLE, saslmechanism_create, const SASL_MECHANISM_INTERFACE_DESCRIPTION*, sasl_mechanism_interface_description, void*, sasl_mechanism_create_parameters);
45 ```
46
47 **SRS_SASL_MECHANISM_01_001: [**`saslmechanism_create` shall return on success a non-NULL handle to a new SASL mechanism interface.**]**
48
49 **SRS_SASL_MECHANISM_01_002: [**In order to instantiate the concrete SASL mechanism implementation the function `concrete_sasl_mechanism_create` from the `sasl_mechanism_interface_description` shall be called, passing the `sasl_mechanism_create_parameters` to it.**]**
50
51 **SRS_SASL_MECHANISM_01_003: [**If the underlying `concrete_sasl_mechanism_create` call fails, `saslmechanism_create` shall return NULL.**]**
52
53 **SRS_SASL_MECHANISM_01_004: [**If the argument `sasl_mechanism_interface_description` is NULL, `saslmechanism_create` shall return NULL.**]**
54
55 **SRS_SASL_MECHANISM_01_005: [**If any `sasl_mechanism_interface_description` member is NULL, `saslmechanism_create` shall fail and return NULL.**]**
56
57 **SRS_SASL_MECHANISM_01_006: [**If allocating the memory needed for the SASL mechanism interface fails then `saslmechanism_create` shall fail and return NULL.**]**
58
59 ### saslmechanism_destroy
60
61 ```C
62 MOCKABLE_FUNCTION(, void, saslmechanism_destroy, SASL_MECHANISM_HANDLE, sasl_mechanism);
63 ```
64
65 **SRS_SASL_MECHANISM_01_007: [**`saslmechanism_destroy` shall free all resources associated with the SASL mechanism handle.**]**
66
67 **SRS_SASL_MECHANISM_01_008: [**`saslmechanism_destroy` shall also call the `concrete_sasl_mechanism_destroy` function that is member of the `sasl_mechanism_interface_description` argument passed to `saslmechanism_create`, while passing as argument to `concrete_sasl_mechanism_destroy` the result of the underlying concrete SASL mechanism handle.**]**
68
69 **SRS_SASL_MECHANISM_01_009: [**If the argument `sasl_mechanism` is NULL, `saslmechanism_destroy` shall do nothing.**]**
70
71 ### saslmechanism_get_init_bytes
72
73 ```C
74 MOCKABLE_FUNCTION(, int, saslmechanism_get_init_bytes, SASL_MECHANISM_HANDLE, sasl_mechanism, SASL_MECHANISM_BYTES*, init_bytes);
75 ```
76
77 **SRS_SASL_MECHANISM_01_010: [**`saslmechanism_get_init_bytes` shall call the specific `concrete_sasl_mechanism_get_init_bytes` function specified in `saslmechanism_create`, passing the `init_bytes` argument to it.**]**
78
79 **SRS_SASL_MECHANISM_01_011: [**On success, `saslmechanism_get_init_bytes` shall return 0.**]**
80
81 **SRS_SASL_MECHANISM_01_012: [**If the argument `sasl_mechanism` is NULL, `saslmechanism_get_init_bytes` shall fail and return a non-zero value.**]**
82
83 **SRS_SASL_MECHANISM_01_013: [**If the underlying `concrete_sasl_mechanism_get_init_bytes` fails, `saslmechanism_get_init_bytes` shall fail and return a non-zero value.**]**
84
85 ### saslmechanism_get_mechanism_name
86
87 ```C
88 MOCKABLE_FUNCTION(, const char*, saslmechanism_get_mechanism_name, SASL_MECHANISM_HANDLE, sasl_mechanism);
89 ```
90
91 **SRS_SASL_MECHANISM_01_014: [**`saslmechanism_get_mechanism_name` shall call the specific `concrete_sasl_mechanism_get_mechanism_name` function specified in `saslmechanism_create`.**]**
92
93 **SRS_SASL_MECHANISM_01_015: [**On success, `saslmechanism_get_mechanism_name` shall return a pointer to a string with the mechanism name.**]**
94
95 **SRS_SASL_MECHANISM_01_016: [**If the argument `sasl_mechanism` is NULL, `saslmechanism_get_mechanism_name` shall fail and return a non-zero value.**]**
96
97 **SRS_SASL_MECHANISM_01_017: [**If the underlying `concrete_sasl_mechanism_get_mechanism_name` fails, `saslmechanism_get_mechanism_name` shall return NULL.**]**
98
99 ### saslmechanism_challenge
100
101 ```C
102 MOCKABLE_FUNCTION(, int, saslmechanism_challenge, SASL_MECHANISM_HANDLE, sasl_mechanism, const SASL_MECHANISM_BYTES*, challenge_bytes, SASL_MECHANISM_BYTES*, response_bytes);
103 ```
104
105 **SRS_SASL_MECHANISM_01_018: [**`saslmechanism_challenge` shall call the specific `concrete_sasl_mechanism_challenge` function specified in `saslmechanism_create`, while passing the `challenge_bytes` and `response_bytes` arguments to it.**]**
106
107 **SRS_SASL_MECHANISM_01_019: [**On success, `saslmechanism_challenge` shall return 0.**]**
108
109 **SRS_SASL_MECHANISM_01_020: [**If the argument `sasl_mechanism` is NULL, `saslmechanism_challenge` shall fail and return a non-zero value.**]**
110
111 **SRS_SASL_MECHANISM_01_021: [**If the underlying `concrete_sasl_mechanism_challenge` fails, `saslmechanism_challenge` shall fail and return a non-zero value.**]**