| 1 |
tlsio_cyclonessl |
| 2 |
============= |
| 3 |
|
| 4 |
## Overview |
| 5 |
|
| 6 |
tlsio_cyclonessl implements a tls adapter for the CycloneSSL TLS library. |
| 7 |
This adapter only works in blocking mode. |
| 8 |
|
| 9 |
## References |
| 10 |
|
| 11 |
[CycloneSSL official page](http://www.oryx-embedded.com/cyclone_ssl.html) |
| 12 |
|
| 13 |
[TLS Protocol (generic information)](https://en.wikipedia.org/wiki/Transport_Layer_Security) |
| 14 |
|
| 15 |
## Exposed API |
| 16 |
|
| 17 |
```c |
| 18 |
MOCKABLE_FUNCTION(, const IO_INTERFACE_DESCRIPTION*, tlsio_cyclonessl_get_interface_description); |
| 19 |
``` |
| 20 |
|
| 21 |
|
| 22 |
### tlsio_cyclonessl_create |
| 23 |
|
| 24 |
tlsio_cyclonessl_create is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_create member. |
| 25 |
|
| 26 |
```c |
| 27 |
CONCRETE_IO_HANDLE tlsio_cyclonessl_create(void* io_create_parameters); |
| 28 |
``` |
| 29 |
|
| 30 |
**SRS_TLSIO_CYCLONESSL_01_001: [** tlsio_cyclonessl_create shall create a new instance of the tlsio for Cyclone SSL. **]** |
| 31 |
|
| 32 |
**SRS_TLSIO_CYCLONESSL_01_002: [** If io_create_parameters is NULL, tlsio_cyclonessl_create shall fail and return NULL. **]** |
| 33 |
|
| 34 |
**SRS_TLSIO_CYCLONESSL_01_003: [** io_create_parameters shall be used as a TLSIO_CONFIG\*. **]** |
| 35 |
|
| 36 |
**SRS_TLSIO_CYCLONESSL_01_004: [** If the hostname member is NULL, then tlsio_cyclonessl_create shall fail and return NULL. **]** |
| 37 |
|
| 38 |
**SRS_TLSIO_CYCLONESSL_01_005: [** tlsio_cyclonessl_create shall copy the hostname and port values for later use when the open of the underlying socket is needed. **]** |
| 39 |
|
| 40 |
**SRS_TLSIO_CYCLONESSL_01_006: [** hostname shall be copied by calling mallocAndStrcpy_s. **]** |
| 41 |
|
| 42 |
**SRS_TLSIO_CYCLONESSL_01_076: [** If allocating memory for the TLS IO instance fails then tlsio_cyclonessl_create shall fail and return NULL. **]** |
| 43 |
|
| 44 |
**SRS_TLSIO_CYCLONESSL_01_007: [** If mallocAndStrcpy_s fails then tlsio_cyclonessl_create shall fail and return NULL. **]** |
| 45 |
|
| 46 |
**SRS_TLSIO_CYCLONESSL_01_008: [** tlsio_cyclonessl_create shall initialize the yarrow context by calling yarrowInit. **]** |
| 47 |
|
| 48 |
**SRS_TLSIO_CYCLONESSL_01_009: [** If yarrowInit fails then tlsio_cyclonessl_create shall return NULL. **]** |
| 49 |
|
| 50 |
**SRS_TLSIO_CYCLONESSL_01_010: [** The yarrow context shall be seeded with 32 bytes of randomly chosen data by calling yarrowSeed. **]** |
| 51 |
|
| 52 |
**SRS_TLSIO_CYCLONESSL_01_011: [** If yarrowSeed fails then tlsio_cyclonessl_create shall return NULL. **]** |
| 53 |
|
| 54 |
**SRS_TLSIO_CYCLONESSL_01_012: [** tlsio_cyclonessl_create shall create a TLS context by calling tlsInit. **]** |
| 55 |
|
| 56 |
**SRS_TLSIO_CYCLONESSL_01_013: [** If tlsInit fails then tlsio_cyclonessl_create shall return NULL. **]** |
| 57 |
|
| 58 |
**SRS_TLSIO_CYCLONESSL_01_014: [** The TLS context shall be setup to operate as a client by calling tlsSetConnectionEnd with TLS_CONNECTION_END_CLIENT. **]** |
| 59 |
|
| 60 |
**SRS_TLSIO_CYCLONESSL_01_015: [** If tlsSetConnectionEnd fails then tlsio_cyclonessl_create shall return NULL. **]** |
| 61 |
|
| 62 |
**SRS_TLSIO_CYCLONESSL_01_016: [** The pseudo random number generator to be used shall be set by calling tlsSetPrng with the yarrow instance as argument. **]** |
| 63 |
|
| 64 |
**SRS_TLSIO_CYCLONESSL_01_017: [** If tlsSetPrng fails then tlsio_cyclonessl_create shall return NULL. **]** |
| 65 |
|
| 66 |
**SRS_TLSIO_CYCLONESSL_01_018: [** When tlsio_cyclonessl_create fails, all allocated resources up to that point shall be freed. **]** |
| 67 |
|
| 68 |
### tlsio_cyclonessl_destroy |
| 69 |
|
| 70 |
tlsio_cyclonessl_destroy is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_destroy member. |
| 71 |
|
| 72 |
```c |
| 73 |
void tlsio_cyclonessl_destroy(CONCRETE_IO_HANDLE tls_io); |
| 74 |
``` |
| 75 |
|
| 76 |
**SRS_TLSIO_CYCLONESSL_01_019: [** tlsio_cyclonessl_destroy shall free the tlsio CycloneSSL instance. **]** |
| 77 |
|
| 78 |
**SRS_TLSIO_CYCLONESSL_01_020: [** If tls_io is NULL, tlsio_cyclonessl_destroy shall do nothing. **]** |
| 79 |
|
| 80 |
**SRS_TLSIO_CYCLONESSL_01_021: [** tlsio_cyclonessl_destroy shall deinitialize the yarrow context by calling yarrowRelease. **]** |
| 81 |
|
| 82 |
**SRS_TLSIO_CYCLONESSL_01_022: [** The TLS context shall be freed by calling tlsFree. **]** |
| 83 |
|
| 84 |
**SRS_TLSIO_CYCLONESSL_01_077: [** All options cached via tlsio_cyclonessl_set_option shall also be freed. **]** |
| 85 |
|
| 86 |
**SRS_TLSIO_CYCLONESSL_01_081: [** tlsio_cyclonessl_destroy should close the IO if it was open before freeing all the resources. **]** |
| 87 |
|
| 88 |
### tlsio_cyclonessl_open |
| 89 |
|
| 90 |
tlsio_cyclonessl_open is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_open member. |
| 91 |
|
| 92 |
```c |
| 93 |
int tlsio_cyclonessl_open(CONCRETE_IO_HANDLE tls_io, ON_IO_OPEN_COMPLETE on_io_open_complete, void* on_io_open_complete_context, ON_BYTES_RECEIVED on_bytes_received, void* on_bytes_received_context, ON_IO_ERROR on_io_error, void* on_io_error_context) |
| 94 |
``` |
| 95 |
|
| 96 |
**SRS_TLSIO_CYCLONESSL_01_023: [** tlsio_cyclonessl_open shall open the TLS io and on success it shall return 0. **]** |
| 97 |
|
| 98 |
**SRS_TLSIO_CYCLONESSL_01_024: [** If any of the arguments tls_io, on_io_open_complete, on_bytes_received or on_io_error are NULL then tlsio_cyclonessl_open shall return a non-zero value. **]** |
| 99 |
|
| 100 |
**SRS_TLSIO_CYCLONESSL_01_025: [** tlsio_cyclonessl_open shall create a socket by calling tlsio_cyclonessl_socket_create, while passing to it the hostname and port that were saved in the tlsio_cyclonessl_create. **]** |
| 101 |
|
| 102 |
**SRS_TLSIO_CYCLONESSL_01_026: [** If tlsio_cyclonessl_socket_create fails, then tlsio_cyclonessl_open shall return a non-zero value. **]** |
| 103 |
|
| 104 |
**SRS_TLSIO_CYCLONESSL_01_027: [** The socket created by tlsio_cyclonessl_socket_create shall be assigned to the TLS context by calling tlsSetSocket. **]** |
| 105 |
|
| 106 |
**SRS_TLSIO_CYCLONESSL_01_028: [** If tlsSetSocket fails then tlsio_cyclonessl_open shall return a non-zero value. **]** |
| 107 |
|
| 108 |
**SRS_TLSIO_CYCLONESSL_01_078: [** If certificates have been set by using tlsio_cyclonessl_set_option then a call to tlsSetTrustedCaList shall be made to pass the certificates to CycloneSSL. **]** |
| 109 |
|
| 110 |
**SRS_TLSIO_CYCLONESSL_01_079: [** If tlsSetTrustedCaList fails then tlsio_cyclonessl_open shall return a non-zero value. **]** |
| 111 |
|
| 112 |
**SRS_TLSIO_CYCLONESSL_01_031: [** tlsio_cyclonessl_open shall start the TLS handshake by calling tlsConnect. **]** |
| 113 |
|
| 114 |
**SRS_TLSIO_CYCLONESSL_01_032: [** If tlsConnect fails then tlsio_cyclonessl_open shall return a non-zero value. **]** |
| 115 |
|
| 116 |
**SRS_TLSIO_CYCLONESSL_01_033: [** If tlsConnect succeeds, the callback on_io_open_complete shall be called, while passing on_io_open_complete_context and IO_OPEN_OK as arguments. **]** |
| 117 |
|
| 118 |
**SRS_TLSIO_CYCLONESSL_01_034: [** If tlsio_cyclonessl_open is called while the IO is open, tlsio_cyclonessl_open shall fail and return a non-zero value without performing any work to open the IO. **]** |
| 119 |
|
| 120 |
### tlsio_cyclonessl_close |
| 121 |
|
| 122 |
tlsio_cyclonessl_close is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_close member. |
| 123 |
|
| 124 |
```c |
| 125 |
int tlsio_cyclonessl_close(CONCRETE_IO_HANDLE tls_io, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* on_io_close_complete_context) |
| 126 |
``` |
| 127 |
|
| 128 |
**SRS_TLSIO_CYCLONESSL_01_035: [** tlsio_cyclonessl_close shall close the TLS IO and on success it shall return 0. **]** |
| 129 |
|
| 130 |
**SRS_TLSIO_CYCLONESSL_01_036: [** If the argument tls_io is NULL, tlsio_cyclonessl_close shall fail and return a non-zero value. **]** |
| 131 |
|
| 132 |
**SRS_TLSIO_CYCLONESSL_01_037: [** tlsio_cyclonessl_close shall close the TLS connection by calling tlsShutdown. **]** |
| 133 |
|
| 134 |
**SRS_TLSIO_CYCLONESSL_01_038: [** If tlsShutdown fails, tlsio_cyclonessl_close shall fail and return a non-zero value. **]** |
| 135 |
|
| 136 |
**SRS_TLSIO_CYCLONESSL_01_039: [** tlsio_cyclonessl_destroy shall destroy the underlying socket by calling tlsio_cyclonessl_socket_destroy. **]** |
| 137 |
|
| 138 |
**SRS_TLSIO_CYCLONESSL_01_040: [** On success, on_io_close_complete shall be called while passing as argument on_io_close_complete_context. **]** |
| 139 |
|
| 140 |
**SRS_TLSIO_CYCLONESSL_01_041: [** If tlsio_cyclonessl_close is called when not open, tlsio_cyclonessl_close shall fail and return a non-zero value. **]** |
| 141 |
|
| 142 |
### tlsio_cyclonessl_send |
| 143 |
|
| 144 |
tlsio_cyclonessl_send is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_send member. |
| 145 |
|
| 146 |
```c |
| 147 |
int tlsio_cyclonessl_send(CONCRETE_IO_HANDLE tls_io, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* on_send_complete_context) |
| 148 |
``` |
| 149 |
|
| 150 |
**SRS_TLSIO_CYCLONESSL_01_042: [** tlsio_cyclonessl_send shall send the `size` bytes pointed to by `buffer` and on success it shall return 0. **]** |
| 151 |
|
| 152 |
**SRS_TLSIO_CYCLONESSL_01_043: [** If any of the arguments tls_io or buffer is NULL, tlsio_cyclonessl_send shall fail and return a non-zero value. **]** |
| 153 |
|
| 154 |
**SRS_TLSIO_CYCLONESSL_01_044: [** If size is 0, tlsio_cyclonessl_send shall fail and return a non-zero value. **]** |
| 155 |
|
| 156 |
**SRS_TLSIO_CYCLONESSL_01_045: [** on_send_complete shall be allowed to be NULL. **]** |
| 157 |
|
| 158 |
**SRS_TLSIO_CYCLONESSL_01_046: [** On success, if a non-NULL value was passed for on_send_complete, then on_send_complete shall be called while passing to it the on_send_complete_context value. **]** |
| 159 |
|
| 160 |
**SRS_TLSIO_CYCLONESSL_01_047: [** tlsio_cyclonessl_send shall send the bytes by calling tlsWrite and passing buffer and size as arguments. 0 shall be passed for the flags argument. **]** |
| 161 |
|
| 162 |
**SRS_TLSIO_CYCLONESSL_01_048: [** If tlsio_cyclonessl_send is called when the IO is not open, tlsio_cyclonessl_send shall fail and return a non-zero value. **]** |
| 163 |
|
| 164 |
**SRS_TLSIO_CYCLONESSL_01_049: [** If the IO is in an error state (an error was reported through the on_io_error callback), tlsio_cyclonessl_send shall fail and return a non-zero value. **]** |
| 165 |
|
| 166 |
### tlsio_cyclonessl_dowork |
| 167 |
|
| 168 |
tlsio_cyclonessl_dowork is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_dowork member. |
| 169 |
|
| 170 |
```c |
| 171 |
void tlsio_cyclonessl_dowork(CONCRETE_IO_HANDLE tls_io) |
| 172 |
``` |
| 173 |
|
| 174 |
**SRS_TLSIO_CYCLONESSL_01_050: [** tlsio_cyclonessl_dowork shall check if any bytes are available to be read from the CycloneSSL library and indicate those bytes as received. **]** |
| 175 |
|
| 176 |
**SRS_TLSIO_CYCLONESSL_01_051: [** If the tls_io argument is NULL, tlsio_cyclonessl_dowork shall do nothing. **]** |
| 177 |
|
| 178 |
**SRS_TLSIO_CYCLONESSL_01_052: [** If the IO is not open (no open has been called or the IO has been closed) then tlsio_cyclonessl_dowork shall do nothing. **]** |
| 179 |
|
| 180 |
**SRS_TLSIO_CYCLONESSL_01_053: [** If the IO is open, tlsio_cyclonessl_dowork shall attempt to read 64 bytes from the TLS library by calling tlsRead. **]** |
| 181 |
|
| 182 |
**SRS_TLSIO_CYCLONESSL_01_080: [** If any bytes are read from CycloneSSL they should be indicated via the on_bytes_received callback passed to tlsio_cyclonessl_open. **]** |
| 183 |
|
| 184 |
**SRS_TLSIO_CYCLONESSL_01_054: [** The flags argument for tlsRead shall be 0. **]** |
| 185 |
|
| 186 |
**SRS_TLSIO_CYCLONESSL_01_055: [** If tlsRead fails, the error shall be indicated by calling the on_io_error callback passed in tlsio_cyclonessl_open, while passing the on_io_error_context to the callback. **]** |
| 187 |
|
| 188 |
**SRS_TLSIO_CYCLONESSL_01_056: [** Also the IO shall be considered in error and any subsequent calls to tlsio_cyclonessl_send shall fail. **]** |
| 189 |
|
| 190 |
### tlsio_cyclonessl_setoption |
| 191 |
|
| 192 |
tlsio_cyclonessl_setoption is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_setoption member. |
| 193 |
|
| 194 |
```c |
| 195 |
int tlsio_cyclonessl_setoption(CONCRETE_IO_HANDLE tls_io, const char* optionName, const void* value) |
| 196 |
``` |
| 197 |
|
| 198 |
**SRS_TLSIO_CYCLONESSL_01_057: [** If any of the arguments tls_io or option_name is NULL tlsio_cyclonessl_setoption shall return a non-zero value. **]** |
| 199 |
|
| 200 |
**SRS_TLSIO_CYCLONESSL_01_058: [** If the option_name argument indicates an option that is not handled by tlsio_cyclonessl, then tlsio_cyclonessl_setoption shall return a non-zero value. **]** |
| 201 |
|
| 202 |
**SRS_TLSIO_CYCLONESSL_01_059: [** If the option was handled by tlsio_cyclonessl, then tlsio_cyclonessl_setoption shall return 0. **]** |
| 203 |
|
| 204 |
Options that shall be handled by tlsio_cyclonessl: |
| 205 |
|
| 206 |
**SRS_TLSIO_CYCLONESSL_01_060: [** - "TrustedCerts" - a char\* that shall be saved by tlsio_cyclonessl as it shall be given to the underlying CycloneSSL TLS context when the IO is open. **]** |
| 207 |
|
| 208 |
**SRS_TLSIO_CYCLONESSL_01_061: [** If copying the char\* passed in value fails then tlsio_cyclonessl_setoption shall return a non-zero value. **]** |
| 209 |
|
| 210 |
**SRS_TLSIO_CYCLONESSL_01_062: [** If a previous TrustedCerts option was saved, then the previous value shall be freed. **]** |
| 211 |
|
| 212 |
**SRS_TLSIO_CYCLONESSL_01_063: [** A NULL value shall be allowed for TrustedCerts, in which case the previously stored TrustedCerts option value shall be cleared. **]** |
| 213 |
|
| 214 |
### tlsio_cyclonessl_retrieve_options |
| 215 |
|
| 216 |
tlsio_cyclonessl_retrieve_options is the implementation provided via tlsio_cyclonessl_get_interface_description for the concrete_io_retrieveoptions member. |
| 217 |
|
| 218 |
```c |
| 219 |
static OPTIONHANDLER_HANDLE tlsio_cyclonessl_retrieve_options(CONCRETE_IO_HANDLE handle) |
| 220 |
``` |
| 221 |
|
| 222 |
tlsio_cyclonessl_retrieveoptions produces an OPTIONHANDLER_HANDLE. |
| 223 |
|
| 224 |
**SRS_TLSIO_CYCLONESSL_01_064: [** If parameter handle is `NULL` then `tlsio_cyclonessl_retrieve_options` shall fail and return NULL. **]** |
| 225 |
|
| 226 |
**SRS_TLSIO_CYCLONESSL_01_065: [** `tlsio_cyclonessl_retrieve_options` shall produce an OPTIONHANDLER_HANDLE. **]** |
| 227 |
|
| 228 |
**SRS_TLSIO_CYCLONESSL_01_066: [** `tlsio_cyclonessl_retrieve_options` shall add to it the options: **]** |
| 229 |
|
| 230 |
**SRS_TLSIO_CYCLONESSL_01_067: [** - TrustedCerts **]** |
| 231 |
|
| 232 |
**SRS_TLSIO_CYCLONESSL_01_068: [** If producing the OPTIONHANDLER_HANDLE fails then tlsio_cyclonessl_retrieve_options shall fail and return NULL. **]** |
| 233 |
|
| 234 |
### tlsio_cyclonessl_get_interface_description |
| 235 |
|
| 236 |
```c |
| 237 |
extern const IO_INTERFACE_DESCRIPTION* tlsio_cyclonessl_get_interface_description(void); |
| 238 |
``` |
| 239 |
|
| 240 |
**SRS_TLSIO_CYCLONESSL_01_069: [** tlsio_cyclonessl_get_interface_description shall return a pointer to an IO_INTERFACE_DESCRIPTION structure that contains pointers to the functions: tlsio_cyclonessl_retrieve_options, tlsio_cyclonessl_create, tlsio_cyclonessl_destroy, tlsio_cyclonessl_open, tlsio_cyclonessl_close, tlsio_cyclonessl_send and tlsio_cyclonessl_dowork. **]** |
| 241 |
|
| 242 |
### tlsio_cyclonessl_clone_option |
| 243 |
|
| 244 |
tlsio_cyclonessl_clone_option is the implementation provided to the option handler instance created as part of tlsio_cyclonessl_retrieve_options. |
| 245 |
|
| 246 |
```c |
| 247 |
void* tlsio_cyclonessl_clone_option(const char* name, const void* value) |
| 248 |
``` |
| 249 |
|
| 250 |
**SRS_TLSIO_CYCLONESSL_01_070: [** If the name or value arguments are NULL, tlsio_cyclonessl_clone_option shall return NULL. **]** |
| 251 |
|
| 252 |
**SRS_TLSIO_CYCLONESSL_01_071: [** tlsio_cyclonessl_clone_option shall clone the option named `TrustedCerts` by calling mallocAndStrcpy_s. **]** **SRS_TLSIO_CYCLONESSL_01_072: [** On success it shall return a non-NULL pointer to the cloned option. **]** |
| 253 |
|
| 254 |
**SRS_TLSIO_CYCLONESSL_01_073: [** If mallocAndStrcpy_s for `TrustedCerts` fails, tlsio_cyclonessl_clone_option shall return NULL. **]** |
| 255 |
|
| 256 |
### tlsio_cyclonessl_destroy_option |
| 257 |
|
| 258 |
tlsio_cyclonessl_destroy_option is the implementation provided to the option handler instance created as part of tlsio_cyclonessl_retrieve_options. |
| 259 |
|
| 260 |
```c |
| 261 |
void tlsio_cyclonessl_destroy_option(const char* name, const void* value) |
| 262 |
``` |
| 263 |
|
| 264 |
**SRS_TLSIO_CYCLONESSL_01_074: [** If any of the arguments is NULL, tlsio_cyclonessl_destroy_option shall do nothing. **]** |
| 265 |
|
| 266 |
**SRS_TLSIO_CYCLONESSL_01_075: [** If the option name is `TrustedCerts`, tlsio_cyclonessl_destroy_option shall free the char\* option indicated by value. **]** |