| 1 |
# HTTPAPIEX SAS Requirements |
| 2 |
|
| 3 |
================ |
| 4 |
|
| 5 |
## Overview |
| 6 |
|
| 7 |
This module is used to manage the SAS Tokens within HTTP headers that are passing through to the HTTPAPIEX interface. |
| 8 |
A guiding principle of this module to that if SAS Tokens are being used within the http headers then at all costs SAS token expiration should be avoided. |
| 9 |
Retransmission is very expensive. Additionally this module does not try to enforce any policy on the headers. |
| 10 |
For instance, if there is no "Authorization" header, this module will make no attempt to error out. It will still try to invoke the HTTPAPIEX_ExecuteRequest. |
| 11 |
|
| 12 |
## References |
| 13 |
|
| 14 |
[SAS Token Create requirements] |
| 15 |
|
| 16 |
[HTTPAPIEX requirements] |
| 17 |
|
| 18 |
[HTTP headers requirements] |
| 19 |
|
| 20 |
## Exposed API |
| 21 |
|
| 22 |
```c |
| 23 |
typedef void* HTTPAPIEX_SAS_HANDLE; |
| 24 |
|
| 25 |
extern HTTPAPIEX_SAS_HANDLE HTTPAPIEX_SAS_Create(STRING_HANDLE key, STRING_HANDLE uriResource, STRING_HANDLE keyName); |
| 26 |
|
| 27 |
extern HTTPAPIEX_SAS_HANDLE HTTPAPIEX_SAS_Create_From_String(const char* key, const char* uriResource, const char* keyName); |
| 28 |
|
| 29 |
extern void HTTPAPIEX_SAS_Destroy(HTTPAPIEX_SAS_HANDLE handle); |
| 30 |
|
| 31 |
extern HTTPAPIEX_RESULT HTTPAPIEX_SAS_ExecuteRequest(HTTPAPIEX_SAS_HANDLE sasHandle, HTTPAPIEX_HANDLE handle, HTTPAPI_REQUEST_TYPE requestType, const char* relativePath, HTTP_HEADERS_HANDLE requestHttpHeadersHandle, BUFFER_HANDLE requestContent, unsigned int* statusCode, HTTP_HEADERS_HANDLE responseHeadersHandle, BUFFER_HANDLE responseContent); |
| 32 |
``` |
| 33 |
|
| 34 |
### HTTPAPIEX_SAS_Create |
| 35 |
|
| 36 |
```c |
| 37 |
extern HTTPAPIEX_SAS_HANDLE HTTPAPIEX_SAS_Create(STRING_HANDLE key, STRING_HANDLE uriResource, STRING_HANDLE keyName); |
| 38 |
``` |
| 39 |
|
| 40 |
**SRS_HTTPAPIEXSAS_01_001: [** HTTPAPIEX_SAS_Create shall create a new instance of HTTPAPIEX_SAS and return a non-NULL handle to it. **]** |
| 41 |
|
| 42 |
**SRS_HTTPAPIEXSAS_06_001: [** If the parameter key is NULL then HTTPAPIEX_SAS_Create shall return NULL. **]** |
| 43 |
|
| 44 |
**SRS_HTTPAPIEXSAS_06_002: [** If the parameter uriResource is NULL then HTTPAPIEX_SAS_Create shall return NULL. **]** |
| 45 |
|
| 46 |
**SRS_HTTPAPIEXSAS_06_003: [** The parameter keyName for HTTPAPIEX_SAS_Create is optional and can be NULL. **]** |
| 47 |
|
| 48 |
**SRS_HTTPAPIEXSAS_06_004: [** If there are any other errors in the instantiation of this handle then HTTPAPIEX_SAS_Create shall return NULL. **]** |
| 49 |
|
| 50 |
### HTTPAPIEX_SAS_Create_From_String |
| 51 |
|
| 52 |
```c |
| 53 |
extern HTTPAPIEX_SAS_HANDLE HTTPAPIEX_SAS_Create_From_String(const char* key, const char* uriResource, const char* keyName); |
| 54 |
``` |
| 55 |
|
| 56 |
**SRS_HTTPAPIEXSAS_07_001: [** If the parameter `key` or `uriResource` is NULL then `HTTPAPIEX_SAS_Create_From_String` shall return NULL. **]** |
| 57 |
|
| 58 |
**SRS_HTTPAPIEXSAS_07_002: [** If there are any other errors in the instantiation of this handle then `HTTPAPIEX_SAS_Create_From_String` shall return NULL. **]** |
| 59 |
|
| 60 |
**SRS_HTTPAPIEXSAS_07_003: [** `HTTPAPIEX_SAS_Create_From_String` shall create a new instance of `HTTPAPIEX_SAS` and return a non-NULL handle to it **]** |
| 61 |
|
| 62 |
### HTTPAPIEX_SAS_Destroy |
| 63 |
|
| 64 |
```c |
| 65 |
extern void HTTPAPIEX_SAS_Destroy(HTTPAPIEX_SAS_HANDLE handle); |
| 66 |
``` |
| 67 |
|
| 68 |
**SRS_HTTPAPIEXSAS_06_005: [** If the parameter handle is NULL then HTTAPIEX_SAS_Destroy shall do nothing and return. **]** |
| 69 |
|
| 70 |
Otherwise, **SRS_HTTPAPIEXSAS_06_006: [** HTTAPIEX_SAS_Destroy shall deallocate any structures denoted by the parameter handle. **]** |
| 71 |
|
| 72 |
### HTTPAPIEX_SAS_ExecuteRequest |
| 73 |
|
| 74 |
```c |
| 75 |
extern HTTPAPIEX_RESULT HTTPAPIEX_SAS_ExecuteRequest(HTTPAPIEX_SAS_HANDLE sasHandle, HTTPAPIEX_HANDLE handle, HTTPAPI_REQUEST_TYPE requestType, const char* relativePath, HTTP_HEADERS_HANDLE requestHttpHeadersHandle, BUFFER_HANDLE requestContent, unsigned int* statusCode, HTTP_HEADERS_HANDLE responseHeadersHandle, BUFFER_HANDLE responseContent); |
| 76 |
``` |
| 77 |
|
| 78 |
**SRS_HTTPAPIEXSAS_06_007: [** If the parameter sasHandle is NULL then HTTPAPIEX_SAS_ExecuteRequest shall simply invoke HTTPAPIEX_ExecuteRequest with the remaining parameters (following sasHandle) as its arguments and shall return immediately with the result of that call as the result of HTTPAPIEX_SAS_ExecuteRequest. **]** |
| 79 |
|
| 80 |
This invocation of HTTPAPIEX_ExecuteRequest and returning its result as the result of HTTPAPIEX_SAS_ExecuteRequest shall be henceforth known as fallthrough. |
| 81 |
|
| 82 |
Otherwise,**SRS_HTTPAPIEXSAS_06_008: [** if the parameter requestHttpHeadersHandle is NULL then fallthrough. **]** |
| 83 |
|
| 84 |
**SRS_HTTPAPIEXSAS_06_009: [** HTTPHeaders_FindHeaderValue shall be invoked with the requestHttpHeadersHandle as its first argument and the string "Authorization" as its second argument. **]** |
| 85 |
|
| 86 |
**SRS_HTTPAPIEXSAS_06_010: [** If the return result of the invocation of HTTPHeaders_FindHeaderValue is NULL then fallthrough. **]** |
| 87 |
The caller of HTTPAPIEX_SAS_ExecuteRequest may know that there is no "Authorization" header. HTTPAPIEX_SAS_ExecuteRequest does not try to enforce policy. |
| 88 |
|
| 89 |
**SRS_HTTPAPIEXSAS_06_018: [** A value of type time_t that shall be known as currentTime is obtained from calling get_time. **]** |
| 90 |
|
| 91 |
**SRS_HTTPAPIEXSAS_06_019: [** If the value of currentTime is (time_t)-1 is then fallthrough. **]** |
| 92 |
|
| 93 |
The size_t value ((size_t) (difftime(currentTime,0) + 3600)) is obtained an shall be known as expiry. |
| 94 |
|
| 95 |
**SRS_HTTPAPIEXSAS_06_017: [** If state->key is prefixed with "sas=", SharedAccessSignature will be used rather than created. STRING_construct will be invoked. **]** |
| 96 |
|
| 97 |
**SRS_HTTPAPIEXSAS_06_011: [** SASToken_Create shall be invoked. **]** |
| 98 |
|
| 99 |
**SRS_HTTPAPIEXSAS_06_012: [** If the return result of SASToken_Create is NULL then fallthrough. **]** |
| 100 |
The call to HTTPAPIEX_ExecuteRequest is attempted because there certainly could still be a valid SAS Token as the value the Authorization header. Note also that an error will be logged that the token could not be created. |
| 101 |
The result of the SASToken_Create shall be known as newSASToken. |
| 102 |
|
| 103 |
**SRS_HTTPAPIEXSAS_06_013: [** HTTPHeaders_ReplaceHeaderNameValuePair shall be invoked with "Authorization" as its second argument and STRING_c_str (newSASToken) as its third argument. **]** |
| 104 |
|
| 105 |
**SRS_HTTPAPIEXSAS_06_015: [** STRING_delete(newSASToken) will be invoked. **]** |
| 106 |
|
| 107 |
**SRS_HTTPAPIEXSAS_06_014: [** If the result of the invocation of HTTPHeaders_ReplaceHeaderNameValuePair is NOT HTTP_HEADERS_OK then fallthrough. **]** |
| 108 |
Note that an error will be logged that the "Authorization" header could not be replaced. |
| 109 |
|
| 110 |
Finally, **SRS_HTTPAPIEXSAS_06_016: [** HTTPAPIEX_ExecuteRequest with the remaining parameters (following sasHandle) as its arguments will be invoked and the result of that call is the result of HTTPAPIEX_SAS_ExecuteRequest. **]** |