| 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. |