Debian Codegraph @

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

raw
1 # cbs requirements
2
3 ## Overview
4
5 `cbs` is module that implements the CBS draft specification.
6
7 ##Exposed API
8
9 ```c
10 #define CBS_OPERATION_RESULT_VALUES \
11 CBS_OPERATION_RESULT_OK, \
12 CBS_OPERATION_RESULT_CBS_ERROR, \
13 CBS_OPERATION_RESULT_OPERATION_FAILED, \
14 CBS_OPERATION_RESULT_INSTANCE_CLOSED
15
16 DEFINE_ENUM(CBS_OPERATION_RESULT, CBS_OPERATION_RESULT_VALUES)
17
18 #define CBS_OPEN_COMPLETE_RESULT_VALUES \
19 CBS_OPEN_OK, \
20 CBS_OPEN_ERROR, \
21 CBS_OPEN_CANCELLED
22
23 DEFINE_ENUM(CBS_OPEN_COMPLETE_RESULT, CBS_OPEN_COMPLETE_RESULT_VALUES)
24
25 typedef struct CBS_INSTANCE_TAG* CBS_HANDLE;
26 typedef void(*ON_CBS_OPEN_COMPLETE)(void* context, CBS_OPEN_COMPLETE_RESULT open_complete_result);
27 typedef void(*ON_CBS_ERROR)(void* context);
28 typedef void(*ON_CBS_OPERATION_COMPLETE)(void* context, CBS_OPERATION_RESULT complete_result, unsigned int status_code, const char* status_description);
29
30 MOCKABLE_FUNCTION(, CBS_HANDLE, cbs_create, SESSION_HANDLE, session);
31 MOCKABLE_FUNCTION(, void, cbs_destroy, CBS_HANDLE, cbs);
32 MOCKABLE_FUNCTION(, int, cbs_open_async, CBS_HANDLE, cbs, ON_CBS_OPEN_COMPLETE, on_cbs_open_complete, void*, on_cbs_open_complete_context, ON_CBS_ERROR, on_cbs_error, void*, on_cbs_error_context);
33 MOCKABLE_FUNCTION(, int, cbs_close, CBS_HANDLE, cbs);
34 MOCKABLE_FUNCTION(, ASYNC_OPERATION_HANDLE, cbs_put_token_async, CBS_HANDLE, cbs, const char*, type, const char*, audience, const char*, token, ON_CBS_OPERATION_COMPLETE, on_cbs_put_token_complete, void*, on_cbs_put_token_complete_context);
35 MOCKABLE_FUNCTION(, ASYNC_OPERATION_HANDLE, cbs_delete_token_async, CBS_HANDLE, cbs, const char*, type, const char*, audience, ON_CBS_OPERATION_COMPLETE, on_cbs_delete_token_complete, void*, on_cbs_delete_token_complete_context);
36 MOCKABLE_FUNCTION(, int, cbs_set_trace, CBS_HANDLE, cbs, bool, trace_on);
37 ```
38
39 ### cbs_create
40
41 ```c
42 MOCKABLE_FUNCTION(, CBS_HANDLE, cbs_create, SESSION_HANDLE, session);
43 ```
44
45 **SRS_CBS_01_001: [** `cbs_create` shall create a new CBS instance and on success return a non-NULL handle to it. **]**
46 **SRS_CBS_01_033: [** If `session` is NULL then `cbs_create` shall fail and return NULL. **]**
47 **SRS_CBS_01_097: [** `cbs_create` shall create a singly linked list for pending operations by calling `singlylinkedlist_create`. **]**
48 **SRS_CBS_01_101: [** If `singlylinkedlist_create` fails, `cbs_create` shall fail and return NULL. **]**
49 **SRS_CBS_01_076: [** If allocating memory for the new handle fails, `cbs_create` shall fail and return NULL. **]**
50 **SRS_CBS_01_034: [** `cbs_create` shall create an AMQP management handle by calling `amqp_management_create`. **]**
51 **SRS_CBS_01_035: [** If `amqp_management_create` fails then `cbs_create` shall fail and return NULL. **]**
52 **SRS_CBS_01_117: [** `cbs_create` shall set the override status code key name on the AMQP management handle to `status-code` by calling `amqp_management_set_override_status_code_key_name`. **]**
53 **SRS_CBS_01_118: [** `cbs_create` shall set the override status description key name on the AMQP management handle to `status-description` by calling `amqp_management_set_override_status_description_key_name`. **]**
54 **SRS_CBS_01_116: [** If setting the override key names fails, then `cbs_create` shall fail and return NULL. **]**
55
56 ### cbs_destroy
57
58 ```c
59 MOCKABLE_FUNCTION(, void, cbs_destroy, CBS_HANDLE, cbs);
60 ```
61
62 **SRS_CBS_01_036: [** `cbs_destroy` shall free all resources associated with the handle `cbs`. **]**
63 **SRS_CBS_01_037: [** If `cbs` is NULL, `cbs_destroy` shall do nothing. **]**
64 **SRS_CBS_01_100: [** If the CBS instance is not closed, all actions performed by `cbs_close` shall be performed. **]**
65 **SRS_CBS_01_099: [** All pending operations shall be freed. **]**
66 **SRS_CBS_01_098: [** `cbs_destroy` shall free the pending operations list by calling `singlylinkedlist_destroy`. **]**
67 **SRS_CBS_01_038: [** `cbs_destroy` shall free the AMQP management handle created in `cbs_create` by calling `amqp_management_destroy`. **]**
68
69 ### cbs_open_async
70
71 ```c
72 MOCKABLE_FUNCTION(, int, cbs_open_async, CBS_HANDLE, cbs, ON_CBS_OPEN_COMPLETE, on_cbs_open_complete, void*, on_cbs_open_complete_context, ON_CBS_ERROR, on_cbs_error, void*, on_cbs_error_context);
73 ```
74
75 **SRS_CBS_01_039: [** `cbs_open_async` shall open the cbs communication by calling `amqp_management_open_async` on the AMQP management handle created in `cbs_create`. **]**
76 **SRS_CBS_01_077: [** On success, `cbs_open_async` shall return 0. **]**
77 **SRS_CBS_01_040: [** If any of the arguments `cbs`, `on_cbs_open_complete` or `on_cbs_error` is NULL, then `cbs_open_async` shall fail and return a non-zero value. **]**
78 **SRS_CBS_01_041: [** If `amqp_management_open_async` fails, shall fail and return a non-zero value. **]**
79 **SRS_CBS_01_042: [** `on_cbs_open_complete_context` and `on_cbs_error_context` shall be allowed to be NULL. **]**
80 **SRS_CBS_01_043: [** `cbs_open_async` while already open or opening shall fail and return a non-zero value. **]**
81 **SRS_CBS_01_078: [** The cbs instance shall be considered OPENING until the `on_amqp_management_open_complete` callback is called by the AMQP management instance indicating that the open has completed (succesfull or not). **]**
82
83 ### cbs_close
84
85 ```c
86 MOCKABLE_FUNCTION(, int, cbs_close, CBS_HANDLE, cbs);
87 ```
88
89 **SRS_CBS_01_044: [** `cbs_close` shall close the CBS instance by calling `amqp_management_close` on the underlying AMQP management handle. **]**
90 **SRS_CBS_01_080: [** On success, `cbs_close` shall return 0. **]**
91 **SRS_CBS_01_079: [** If `cbs_close` is called while OPENING, the `on_cbs_open_complete` callback shall be called with `CBS_OPEN_CANCELLED`, while passing the `on_cbs_open_complete_context` as argument. **]**
92 **SRS_CBS_01_045: [** If the argument `cbs` is NULL, `cbs_close` shall fail and return a non-zero value. **]**
93 **SRS_CBS_01_046: [** If `amqp_management_close` fails, `cbs_close` shall fail and return a non-zero value. **]**
94 **SRS_CBS_01_047: [** `cbs_close` when closed shall fail and return a non-zero value. **]**
95 **SRS_CBS_01_048: [** `cbs_close` when not opened shall fail and return a non-zero value. **]**
96 **SRS_CBS_01_099: [** All pending operations shall be freed. **]**
97
98 ### cbs_put_token_async
99
100 ```c
101 MOCKABLE_FUNCTION(, ASYNC_OPERATION_HANDLE, cbs_put_token_async, CBS_HANDLE, cbs, const char*, type, const char*, audience, const char*, token, ON_CBS_OPERATION_COMPLETE, on_cbs_put_token_complete, void*, on_cbs_put_token_complete_context);
102 ```
103
104 **SRS_CBS_01_049: [** `cbs_put_token_async` shall construct a request message for the `put-token` operation. **]**
105 **SRS_CBS_01_081: [** On success `cbs_put_token_async` shall return an `ASYNC_OPERATION_HANDLE`. **]**
106 **SRS_CBS_09_001: [** The `ASYNC_OPERATION_HANDLE` cancel function shall cancel the underlying amqp management operation, remove this operation from the pending list, destroy this async operation. **]**
107 **SRS_CBS_01_050: [** If any of the arguments `cbs`, `type`, `audience`, `token` or `on_cbs_put_token_complete` is NULL `cbs_put_token_async` shall fail and return a non-zero value. **]**
108 **SRS_CBS_01_083: [** `on_cbs_put_token_complete_context` shall be allowed to be NULL. **]**
109 **SRS_CBS_01_051: [** `cbs_put_token_async` shall start the AMQP management operation by calling `amqp_management_execute_operation_async`, while passing to it: **]**
110 **SRS_CBS_01_052: [** The `amqp_management` argument shall be the one for the AMQP management instance created in `cbs_create`. **]**
111 **SRS_CBS_01_053: [** The `operation` argument shall be `put-token`. **]**
112 **SRS_CBS_01_054: [** The `type` argument shall be set to the `type` argument. **]**
113 **SRS_CBS_01_055: [** The `locales` argument shall be set to NULL. **]**
114 **SRS_CBS_01_056: [** The `message` argument shall be the message constructed earlier according to the CBS spec. **]**
115 **SRS_CBS_01_072: [** If constructing the message fails, `cbs_put_token_async` shall fail and return a non-zero value. **]**
116 **SRS_CBS_01_084: [** If `amqp_management_execute_operation_async` fails `cbs_put_token_async` shall fail and return a non-zero value. **]**
117 **SRS_CBS_01_057: [** The arguments `on_execute_operation_complete` and `context` shall be set to a callback that is to be called by the AMQP management module when the operation is complete. **]**
118 **SRS_CBS_01_058: [** If `cbs_put_token_async` is called when the CBS instance is not yet open or in error, it shall fail and return `NULL`. **]**
119
120 ### cbs_delete_token_async
121
122 ```c
123 MOCKABLE_FUNCTION(, ASYNC_OPERATION_HANDLE, cbs_delete_token_async, CBS_HANDLE, cbs, const char*, type, const char*, audience, ON_CBS_OPERATION_COMPLETE, on_cbs_delete_token_complete, void*, on_cbs_delete_token_complete_context);
124 ```
125
126 **SRS_CBS_01_059: [** `cbs_delete_token_async` shall construct a request message for the `delete-token` operation. **]**
127 **SRS_CBS_01_082: [** On success `cbs_delete_token_async` shall return an `ASYNC_OPERATION_HANDLE`. **]**
128 **SRS_CBS_09_001: [** The `ASYNC_OPERATION_HANDLE` cancel function shall cancel the underlying amqp management operation, remove this operation from the pending list, destroy this async operation. **]**
129 **SRS_CBS_01_060: [** If any of the arguments `cbs`, `type`, `audience` or `on_cbs_delete_token_complete` is NULL `cbs_put_token_async` shall fail and return a non-zero value. **]**
130 **SRS_CBS_01_086: [** `on_cbs_delete_token_complete_context` shall be allowed to be NULL. **]**
131 **SRS_CBS_01_061: [** `cbs_delete_token_async` shall start the AMQP management operation by calling `amqp_management_execute_operation_async`, while passing to it: **]**
132 **SRS_CBS_01_085: [** The `amqp_management` argument shall be the one for the AMQP management instance created in `cbs_create`. **]**
133 **SRS_CBS_01_062: [** The `operation` argument shall be `delete-token`. **]**
134 **SRS_CBS_01_063: [** The `type` argument shall be set to the `type` argument. **]**
135 **SRS_CBS_01_064: [** The `locales` argument shall be set to NULL. **]**
136 **SRS_CBS_01_065: [** The `message` argument shall be the message constructed earlier according to the CBS spec. **]**
137 **SRS_CBS_01_071: [** If constructing the message fails, `cbs_delete_token_async` shall fail and return a non-zero value. **]**
138 **SRS_CBS_01_087: [** If `amqp_management_execute_operation_async` fails `cbs_put_token_async` shall fail and return a non-zero value. **]**
139 **SRS_CBS_01_066: [** The arguments `on_execute_operation_complete` and `context` shall be set to a callback that is to be called by the AMQP management module when the operation is complete. **]**
140 **SRS_CBS_01_067: [** If `cbs_delete_token_async` is called when the CBS instance is not yet open or in error, it shall fail and return `NULL`. **]**
141
142 ### cbs_set_trace
143
144 ```c
145 MOCKABLE_FUNCTION(, int, cbs_set_trace, CBS_HANDLE, cbs, bool, trace_on);
146 ```
147
148 **SRS_CBS_01_088: [** `cbs_set_trace` shall enable or disable tracing by calling `amqp_management_set_trace` to pass down the `trace_on` value. **]**
149 **SRS_CBS_01_089: [** On success, `cbs_set_trace` shall return 0. **]**
150 **SRS_CBS_01_090: [** If the argument `cbs` is NULL, `cbs_set_trace` shall fail and return a non-zero value. **]**
151
152 ### on_amqp_management_open_complete
153
154 ```c
155 void on_amqp_management_open_complete(void* context, AMQP_MANAGEMENT_OPEN_RESULT open_result);
156 ```
157
158 **SRS_CBS_01_105: [** When `on_amqp_management_open_complete` is called with NULL `context`, it shall do nothing. **]**
159 **SRS_CBS_01_106: [** If CBS is OPENING and `open_result` is `AMQP_MANAGEMENT_OPEN_OK` the callback `on_cbs_open_complete` shall be called with `CBS_OPEN_OK` and the `on_cbs_open_complete_context` shall be passed as argument. **]**
160 **SRS_CBS_01_107: [** If CBS is OPENING and `open_result` is `AMQP_MANAGEMENT_OPEN_ERROR` the callback `on_cbs_open_complete` shall be called with `CBS_OPEN_ERROR` and the `on_cbs_open_complete_context` shall be passed as argument. **]**
161 **SRS_CBS_01_108: [** If CBS is OPENING and `open_result` is `AMQP_MANAGEMENT_OPEN_CANCELLED` the callback `on_cbs_open_complete` shall be called with `CBS_OPEN_CANCELLED` and the `on_cbs_open_complete_context` shall be passed as argument. **]**
162 **SRS_CBS_01_109: [** When `on_amqp_management_open_complete` is called when the CBS is OPEN, the callback `on_cbs_error` shall be called and the `on_cbs_error_context` shall be passed as argument. **]**
163 **SRS_CBS_01_113: [** When `on_amqp_management_open_complete` reports a failure, the underlying AMQP management shall be closed by calling `amqp_management_close`. **]**
164
165 ```c
166 void on_amqp_management_error(void* context);
167 ```
168
169 **SRS_CBS_01_110: [** When `on_amqp_management_error` is called with NULL `context`, it shall do nothing. **]**
170 **SRS_CBS_01_111: [** If CBS is OPENING the callback `on_cbs_open_complete` shall be called with `CBS_OPEN_ERROR` and the `on_cbs_open_complete_context` shall be passed as argument. **]**
171 **SRS_CBS_01_114: [** Additionally the underlying AMQP management shall be closed by calling `amqp_management_close`. **]**
172 **SRS_CBS_01_112: [** If CBS is OPEN the callback `on_cbs_error` shall be called and the `on_cbs_error_context` shall be passed as argument. **]**
173
174 ### on_amqp_management_execute_operation_complete
175
176 ```c
177 void on_amqp_management_execute_operation_complete(void* context, OPERATION_RESULT operation_result, unsigned int status_code, const char* status_description);
178 ```
179
180 **SRS_CBS_01_091: [** When `on_amqp_management_execute_operation_complete` is called with a NULL context it shall do nothing. **]**
181 **SRS_CBS_01_103: [** The `context` shall be used to obtain the pending operation information stored in the pending operations linked list by calling `singlylinkedlist_item_get_value`. **]**
182 **SRS_CBS_01_104: [** If `singlylinkedlist_item_get_value` returns NULL, `on_amqp_management_execute_operation_complete` shall do nothing. **]**
183 **SRS_CBS_01_092: [** When `on_amqp_management_execute_operation_complete` is called with `AMQP_MANAGEMENT_EXECUTE_OPERATION_OK`, the associated cbs operation complete callback shall be called with `CBS_OPERATION_RESULT_OK` and passing the `on_cbs_put_token_complete_context` as the context argument. **]**
184 **SRS_CBS_01_093: [** When `on_amqp_management_execute_operation_complete` is called with `AMQP_MANAGEMENT_EXECUTE_OPERATION_ERROR`, the associated cbs operation complete callback shall be called with `CBS_OPERATION_RESULT_CBS_ERROR` and passing the `on_cbs_put_token_complete_context` as the context argument. **]**
185 **SRS_CBS_01_094: [** When `on_amqp_management_execute_operation_complete` is called with `AMQP_MANAGEMENT_EXECUTE_OPERATION_FAILED_BAD_STATUS`, the associated cbs operation complete callback shall be called with `CBS_OPERATION_RESULT_OPERATION_FAILED` and passing the `on_cbs_put_token_complete_context` as the context argument. **]**
186 **SRS_CBS_01_115: [** When `on_amqp_management_execute_operation_complete` is called with `AMQP_MANAGEMENT_EXECUTE_OPERATION_INSTANCE_CLOSED`, the associated cbs operation complete callback shall be called with `CBS_OPERATION_RESULT_INSTANCE_CLOSED` and passing the `on_cbs_put_token_complete_context` as the context argument. **]**
187 **SRS_CBS_01_095: [** `status_code` and `status_description` shall be passed as they are to the cbs operation complete callback. **]**
188 **SRS_CBS_01_102: [** The pending operation shall be removed from the pending operations list by calling `singlylinkedlist_remove`. **]**
189 **SRS_CBS_01_096: [** The `context` for the operation shall also be freed. **]**
190
191 ### Relevant parts from the CBS spec:
192
193 **SRS_CBS_01_002: [** Tokens are communicated between AMQP peers by sending specially-formatted AMQP messages to the Claims-based Security Node. **]**
194 **SRS_CBS_01_003: [** The mechanism follows the scheme defined in the AMQP Management specification [AMQPMAN]. **]**
195
196 4.1 Putting a Token
197
198 **SRS_CBS_01_004: [** A token is sent to the CBS Node by transferring a "put-token" message. **]**
199
200 4.1.1 Request Message
201
202 The request message has the following application-properties:
203
204 Key Optional Value Type Value Contents
205 **SRS_CBS_01_005: [** operation No string "put-token" **]**
206 **SRS_CBS_01_006: [** Type No string The type of the token being put, e.g., "amqp:jwt". **]**
207 **SRS_CBS_01_007: [** name No string The "audience" to which the token applies. **]**
208 **SRS_CBS_01_008: [** expiration Yes timestamp The expiry time of the token. **]**
209
210 **SRS_CBS_01_009: [** The body of the message MUST contain the token. **]**
211 **SRS_CBS_01_010: [** The type of the body is dependent on the type of token being put. **]**
212
213 The table below lists the body types for common token types:
214
215 Token Type Token Description Body Type
216 amqp:jwt JSON Web Token (JWT) AMQP Value (string)
217 amqp:swt Simple Web Token (SWT) AMQP Value (string)
218
219 4.1.2 Response Message
220
221 **SRS_CBS_01_014: [** The response message has the following application-properties: **]**
222
223 Key Optional Value Type Value Contents
224 **SRS_CBS_01_013: [** status-code No int HTTP response code [RFC2616]. **]**
225 **SRS_CBS_01_015: [** status-description Yes string Description of the status. **]**
226
227 **SRS_CBS_01_016: [** The body of the message MUST be empty. **]**
228
229 If the request was successful then the status-code MUST contain 200.
230 If the request was unsuccessful due to a processing error then the status-code SHOULD contain 500 and further information MAY be provided in the status-description.
231 For error conditions related to the content of the request, e.g., unsupported token type, malformed request etc., the status-code SHOULD contain 400 and a detailed description SHOULD NOT be provided in the status-description, in line with general best practice for security-related protocols.
232
233 4.2 Deleting a Token
234
235 **SRS_CBS_01_020: [** To instruct a peer to delete a token associated with a specific audience, a "delete-token" message can be sent to the CBS Node **]**
236
237 4.2.1 Request Message
238
239 **SRS_CBS_01_021: [** The request message has the following application-properties: **]**
240
241 Key Mandatory Value Type Value Contents
242 **SRS_CBS_01_022: [** operation Yes string "delete-token" **]**
243 **SRS_CBS_01_023: [** Type Yes string The type of the token being deleted, e.g., "amqp:jwt". **]**
244 **SRS_CBS_01_024: [** name Yes string The "audience" of the token being deleted. **]**
245
246 **SRS_CBS_01_025: [** The body of the message MUST be empty. **]**
247
248 4.2.2 Response Message
249
250 **SRS_CBS_01_026: [** The response message has the following application-properties: **]**
251
252 Key Mandatory Value Type Value Contents
253 **SRS_CBS_01_027: [** status-code Yes int HTTP response code [RFC2616]. **]**
254 **SRS_CBS_01_028: [** status-description No string Description of the status. **]**
255
256 **SRS_CBS_01_029: [** The body of the message MUST be empty. **]**
257
258 If the request was successful then the status-code MUST contain 200.
259 If the request was unsuccessful due to a processing error then the status-code SHOULD contain 500 and further information MAY be provided in the status-description.
260 For error conditions related to the content of the request, the status-code SHOULD contain 400 and a detailed description SHOULD NOT be provided in the status-description, in line with general best practice for security-related protocols.
261
262 Note that a condition in which the token was not found should be treated as success.