| 1 |
tlsio_ssl_esp8266 |
| 2 |
============= |
| 3 |
|
| 4 |
## Overview |
| 5 |
|
| 6 |
tlsio_ssl_esp8266 implements a tls adapter for the ESP8266 RTOS platform. This adapter only works in blocking mode. |
| 7 |
|
| 8 |
|
| 9 |
## References |
| 10 |
|
| 11 |
[TLS Protocol (RFC2246)](https://www.ietf.org/rfc/rfc2246.txt) |
| 12 |
|
| 13 |
[TLS Protocol (generic information)](https://en.wikipedia.org/wiki/Transport_Layer_Security) |
| 14 |
|
| 15 |
## Exposed API |
| 16 |
|
| 17 |
**SRS_TLSIO_SSL_ESP8266_99_001: [** The tlsio_ssl_esp8266 shall implement and export all the Concrete functions in the VTable IO_INTERFACE_DESCRIPTION defined in the `xio.h`. |
| 18 |
```c |
| 19 |
typedef OPTIONHANDLER_HANDLE (*IO_RETRIEVEOPTIONS)(CONCRETE_IO_HANDLE concrete_io); |
| 20 |
typedef CONCRETE_IO_HANDLE(*IO_CREATE)(void* io_create_parameters); |
| 21 |
typedef void(*IO_DESTROY)(CONCRETE_IO_HANDLE concrete_io); |
| 22 |
typedef int(*IO_OPEN)(CONCRETE_IO_HANDLE concrete_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); |
| 23 |
typedef int(*IO_CLOSE)(CONCRETE_IO_HANDLE concrete_io, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* callback_context); |
| 24 |
typedef int(*IO_SEND)(CONCRETE_IO_HANDLE concrete_io, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context); |
| 25 |
typedef void(*IO_DOWORK)(CONCRETE_IO_HANDLE concrete_io); |
| 26 |
typedef int(*IO_SETOPTION)(CONCRETE_IO_HANDLE concrete_io, const char* optionName, const void* value); |
| 27 |
|
| 28 |
|
| 29 |
typedef struct IO_INTERFACE_DESCRIPTION_TAG |
| 30 |
{ |
| 31 |
IO_RETRIEVEOPTIONS concrete_io_retrieveoptions; |
| 32 |
IO_CREATE concrete_io_create; |
| 33 |
IO_DESTROY concrete_io_destroy; |
| 34 |
IO_OPEN concrete_io_open; |
| 35 |
IO_CLOSE concrete_io_close; |
| 36 |
IO_SEND concrete_io_send; |
| 37 |
IO_DOWORK concrete_io_dowork; |
| 38 |
IO_SETOPTION concrete_io_setoption; |
| 39 |
} IO_INTERFACE_DESCRIPTION; |
| 40 |
``` |
| 41 |
**]** |
| 42 |
|
| 43 |
**SRS_TLSIO_SSL_ESP8266_99_002: [** The tlsio_ssl_esp8266 shall report the open operation status using the IO_OPEN_RESULT enumerator defined in the `xio.h`: |
| 44 |
```c |
| 45 |
typedef enum IO_OPEN_RESULT_TAG |
| 46 |
{ |
| 47 |
IO_OPEN_OK, |
| 48 |
IO_OPEN_ERROR, |
| 49 |
IO_OPEN_CANCELLED |
| 50 |
} IO_OPEN_RESULT; |
| 51 |
``` |
| 52 |
**]** |
| 53 |
|
| 54 |
**SRS_TLSIO_SSL_ESP8266_99_003: [** The tlsio_ssl_esp8266 shall report the send operation status using the IO_SEND_RESULT enumerator defined in the `xio.h`: |
| 55 |
```c |
| 56 |
typedef enum IO_SEND_RESULT_TAG |
| 57 |
{ |
| 58 |
IO_SEND_OK, |
| 59 |
IO_SEND_ERROR, |
| 60 |
IO_SEND_CANCELLED |
| 61 |
} IO_SEND_RESULT; |
| 62 |
``` |
| 63 |
**]** |
| 64 |
|
| 65 |
**SRS_TLSIO_SSL_ESP8266_99_004: [** The tlsio_ssl_esp8266 shall call the callbacks functions defined in the `xio.h`: |
| 66 |
```c |
| 67 |
typedef void(*ON_BYTES_RECEIVED)(void* context, const unsigned char* buffer, size_t size); |
| 68 |
typedef void(*ON_SEND_COMPLETE)(void* context, IO_SEND_RESULT send_result); |
| 69 |
typedef void(*ON_IO_OPEN_COMPLETE)(void* context, IO_OPEN_RESULT open_result); |
| 70 |
typedef void(*ON_IO_CLOSE_COMPLETE)(void* context); |
| 71 |
typedef void(*ON_IO_ERROR)(void* context); |
| 72 |
``` |
| 73 |
**]** |
| 74 |
|
| 75 |
**SRS_TLSIO_SSL_ESP8266_99_005: [** The tlsio_ssl_esp8266 shall received the connection information using the TLSIO_CONFIG structure defined in `tlsio.h`: |
| 76 |
```c |
| 77 |
typedef struct TLSIO_CONFIG_TAG |
| 78 |
{ |
| 79 |
const char* hostname; |
| 80 |
int port; |
| 81 |
} TLSIO_CONFIG; |
| 82 |
``` |
| 83 |
**]** |
| 84 |
|
| 85 |
|
| 86 |
## Callbacks |
| 87 |
|
| 88 |
**SRS_TLSIO_SSL_ESP8266_99_006: [** The tlsio_ssl_esp8266 shall return the status of all async operations using the callbacks. **]** |
| 89 |
|
| 90 |
**SRS_TLSIO_SSL_ESP8266_99_007: [** If the callback function is set as NULL. The tlsio_ssl_esp8266 shall not call anything. **]** |
| 91 |
|
| 92 |
|
| 93 |
### tlsio_openssl_get_interface_description |
| 94 |
```c |
| 95 |
const IO_INTERFACE_DESCRIPTION* tlsio_openssl_get_interface_description(void); |
| 96 |
``` |
| 97 |
|
| 98 |
**SRS_TLSIO_SSL_ESP8266_99_008: [** The tlsio_openssl_get_interface_description shall return the VTable IO_INTERFACE_DESCRIPTION. **]** |
| 99 |
|
| 100 |
|
| 101 |
### tlsio_openssl_create |
| 102 |
Implementation of `IO_CREATE concrete_io_create` |
| 103 |
```c |
| 104 |
CONCRETE_IO_HANDLE tlsio_openssl_create(void* io_create_parameters); |
| 105 |
``` |
| 106 |
|
| 107 |
**SRS_TLSIO_SSL_ESP8266_99_009: [** The tlsio_openssl_create shall create a new instance of the tlsio for esp8266. **]** |
| 108 |
|
| 109 |
**SRS_TLSIO_SSL_ESP8266_99_010: [** The tlsio_openssl_create shall return a non-NULL handle on success. **]** |
| 110 |
|
| 111 |
**SRS_TLSIO_SSL_ESP8266_99_011: [** The tlsio_openssl_create shall allocate memory to control the tlsio instance. **]** |
| 112 |
|
| 113 |
**SRS_TLSIO_SSL_ESP8266_99_012: [** If there is not enough memory to create the tlsio, the tlsio_openssl_create shall return NULL as the handle. **]** |
| 114 |
|
| 115 |
**SRS_TLSIO_SSL_ESP8266_99_013: [** The tlsio_openssl_create shall return NULL when io_create_parameters is NULL. **]** |
| 116 |
|
| 117 |
**SRS_TLSIO_SSL_ESP8266_99_016: [** The tlsio_openssl_create shall initialize all callback pointers as NULL. **]** |
| 118 |
|
| 119 |
**SRS_TLSIO_SSL_ESP8266_99_017: [** The tlsio_openssl_create shall receive the connection configuration (TLSIO_CONFIG). **]** |
| 120 |
|
| 121 |
**SRS_TLSIO_SSL_ESP8266_99_020: [** If tlsio_openssl_create get success to create the tlsio instance, it shall set the tlsio state as TLSIO_STATE_NOT_OPEN. **]** |
| 122 |
|
| 123 |
|
| 124 |
### tlsio_openssl_destroy |
| 125 |
Implementation of `IO_DESTROY concrete_io_destroy` |
| 126 |
```c |
| 127 |
void tlsio_openssl_destroy(CONCRETE_IO_HANDLE tls_io); |
| 128 |
``` |
| 129 |
|
| 130 |
**SRS_TLSIO_SSL_ESP8266_99_021: [** The tlsio_openssl_destroy shall destroy a created instance of the tlsio for ESP8266 identified by the CONCRETE_IO_HANDLE. **]** |
| 131 |
|
| 132 |
**SRS_TLSIO_SSL_ESP8266_99_022: [** The tlsio_openssl_destroy shall free all memory allocated for tlsio_instance. **]** |
| 133 |
|
| 134 |
**SRS_TLSIO_SSL_ESP8266_99_024: [** If the tlsio_handle is NULL, the tlsio_openssl_destroy shall not do anything. **]** |
| 135 |
|
| 136 |
**SRS_TLSIO_SSL_ESP8266_99_025: [** If the tlsio state is TLSIO_STATE_OPENING, TLSIO_STATE_OPEN, or TLSIO_STATE_CLOSING, the tlsio_openssl_destroy shall destroy the tlsio, but log an error. **]** |
| 137 |
|
| 138 |
|
| 139 |
### tlsio_openssl_open |
| 140 |
Implementation of `IO_OPEN concrete_io_open` |
| 141 |
```c |
| 142 |
int tlsio_openssl_open( |
| 143 |
CONCRETE_IO_HANDLE tls_io, |
| 144 |
ON_IO_OPEN_COMPLETE on_io_open_complete, |
| 145 |
void* on_io_open_complete_context, |
| 146 |
ON_BYTES_RECEIVED on_bytes_received, |
| 147 |
void* on_bytes_received_context, |
| 148 |
ON_IO_ERROR on_io_error, |
| 149 |
void* on_io_error_context); |
| 150 |
``` |
| 151 |
|
| 152 |
**SRS_TLSIO_SSL_ESP8266_99_018: [** The tlsio_openssl_open shall convert the provide hostName to an IP address. **]** |
| 153 |
|
| 154 |
**SRS_TLSIO_SSL_ESP8266_99_019: [** If the WiFi cannot find the IP for the hostName, the tlsio_openssl_open shall return __LINE__. **]** |
| 155 |
|
| 156 |
**SRS_TLSIO_SSL_ESP8266_99_026: [** The tlsio_openssl_open shall start the process to open the ssl connection with the host provided in the tlsio_openssl_create. **]** |
| 157 |
|
| 158 |
**SRS_TLSIO_SSL_ESP8266_99_027: [** The tlsio_openssl_open shall set the tlsio to try to open the connection for MAX_RETRY times before assuming that connection failed. **]** |
| 159 |
|
| 160 |
**SRS_TLSIO_SSL_ESP8266_99_028: [** The tlsio_openssl_open shall store the provided on_io_open_complete callback function address. **]** |
| 161 |
|
| 162 |
**SRS_TLSIO_SSL_ESP8266_99_029: [** The tlsio_openssl_open shall store the provided on_io_open_complete_context handle. **]** |
| 163 |
|
| 164 |
**SRS_TLSIO_SSL_ESP8266_99_030: [** The tlsio_openssl_open shall store the provided on_bytes_received callback function address. **]** |
| 165 |
|
| 166 |
**SRS_TLSIO_SSL_ESP8266_99_031: [** The tlsio_openssl_open shall store the provided on_bytes_received_context handle. **]** |
| 167 |
|
| 168 |
**SRS_TLSIO_SSL_ESP8266_99_032: [** The tlsio_openssl_open shall store the provided on_io_error callback function address. **]** |
| 169 |
|
| 170 |
**SRS_TLSIO_SSL_ESP8266_99_033: [** The tlsio_openssl_open shall store the provided on_io_error_context handle. **]** |
| 171 |
|
| 172 |
**SRS_TLSIO_SSL_ESP8266_99_034: [** If tlsio_openssl_open get success to open the ssl connection, it shall set the tlsio state as TLSIO_STATE_OPEN, and return 0. **]** |
| 173 |
|
| 174 |
**SRS_TLSIO_SSL_ESP8266_99_035: [** If the tlsio state is not TLSIO_STATE_NOT_OPEN and not TLSIO_STATE_ERROR, then tlsio_openssl_open shall set the tlsio state as TLSIO_STATE_ERROR, and return _LINE_. **]** |
| 175 |
|
| 176 |
**SRS_TLSIO_SSL_ESP8266_99_036: [** If the tls_io handle is NULL, the tlsio_openssl_open shall not do anything, and return _LINE_. **]** |
| 177 |
|
| 178 |
**SRS_TLSIO_SSL_ESP8266_99_037: [** If the ssl client is not connected, the tlsio_openssl_open shall change the state to TLSIO_STATE_ERROR, log the error, and return _LINE_. **]** |
| 179 |
|
| 180 |
**SRS_TLSIO_SSL_ESP8266_99_039: [** If the tlsio_openssl_open failed to open the tls connection, and the on_io_open_complete callback was provided, it shall call the on_io_open_complete with IO_OPEN_ERROR. **]** |
| 181 |
|
| 182 |
**SRS_TLSIO_SSL_ESP8266_99_040: [** If the tlsio_openssl_open failed to open the tls connection, and the on_io_error callback was provided, it shall call the on_io_error. **]** |
| 183 |
|
| 184 |
**SRS_TLSIO_SSL_ESP8266_99_041: [** If the tlsio_openssl_open get success to open the tls connection, and the on_io_open_complete callback was provided, it shall call the on_io_open_complete with IO_OPEN_OK. **]** |
| 185 |
|
| 186 |
**SRS_TLSIO_SSL_ESP8266_99_042: [** If the tlsio_openssl_open retry SSL_connect to open more than MAX_RETRY times without success, it shall return __LINE__. **]** |
| 187 |
|
| 188 |
**SRS_TLSIO_SSL_ESP8266_99_080: [** If socket failed, the tlsio_openssl_open shall return __LINE__. **]** |
| 189 |
|
| 190 |
**SRS_TLSIO_SSL_ESP8266_99_081: [** If setsockopt failed, the tlsio_openssl_open shall return __LINE__. **]** |
| 191 |
|
| 192 |
**SRS_TLSIO_SSL_ESP8266_99_082: [** If bind failed, the tlsio_openssl_open shall return __LINE__. **]** |
| 193 |
|
| 194 |
**SRS_TLSIO_SSL_ESP8266_99_083: [** If connect and getsockopt failed, the tlsio_openssl_open shall return __LINE__. **]** |
| 195 |
|
| 196 |
**SRS_TLSIO_SSL_ESP8266_99_084: [** If lwip_select failed, the tlsio_openssl_open shall return __LINE__. **]** |
| 197 |
|
| 198 |
**SRS_TLSIO_SSL_ESP8266_99_085: [** If SSL_CTX_new failed, the tlsio_openssl_open shall return __LINE__. **]** |
| 199 |
|
| 200 |
**SRS_TLSIO_SSL_ESP8266_99_087: [** If SSL_new failed, the tlsio_openssl_open shall return __LINE__. **]** |
| 201 |
|
| 202 |
**SRS_TLSIO_SSL_ESP8266_99_088: [** If SSL_set_fd failed, the tlsio_openssl_open shall return __LINE__. **]** |
| 203 |
|
| 204 |
**SRS_TLSIO_SSL_ESP8266_99_089: [** If SSL_connect failed, the tlsio_openssl_open shall return __LINE__. **]** |
| 205 |
|
| 206 |
### tlsio_openssl_close |
| 207 |
Implementation of `IO_CLOSE concrete_io_close` |
| 208 |
```c |
| 209 |
int tlsio_openssl_close(CONCRETE_IO_HANDLE tls_io, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* callback_context); |
| 210 |
``` |
| 211 |
|
| 212 |
**SRS_TLSIO_SSL_ESP8266_99_043: [** The tlsio_openssl_close shall start the process to close the ssl connection. **]** |
| 213 |
|
| 214 |
**SRS_TLSIO_SSL_ESP8266_99_045: [** The tlsio_openssl_close shall store the provided on_io_close_complete callback function address. **]** |
| 215 |
|
| 216 |
**SRS_TLSIO_SSL_ESP8266_99_046: [** The tlsio_openssl_close shall store the provided on_io_close_complete_context handle. **]** |
| 217 |
|
| 218 |
**SRS_TLSIO_SSL_ESP8266_99_047: [** If tlsio_openssl_close get success to start the process to close the ssl connection, it shall set the tlsio state as TLSIO_STATE_CLOSING, and return 0. **]** |
| 219 |
|
| 220 |
**SRS_TLSIO_SSL_ESP8266_99_048: [** If the tlsio state is TLSIO_STATE_NOT_OPEN, TLSIO_STATE_OPENING, or TLSIO_STATE_CLOSING, the tlsio_openssl_close shall set the tlsio state as TLSIO_STATE_ERROR, and return _LINE_. **]** |
| 221 |
|
| 222 |
**SRS_TLSIO_SSL_ESP8266_99_049: [** If the tlsio_handle is NULL, the tlsio_openssl_close shall not do anything, and return _LINE_. **]** |
| 223 |
|
| 224 |
**SRS_TLSIO_SSL_ESP8266_99_050: [** If tlsio_openssl_close successfully destroys the ssl connection, it shall set the tlsio state as TLSIO_STATE_NOT_OPEN, and return 0. **]** |
| 225 |
|
| 226 |
**SRS_TLSIO_SSL_ESP8266_99_051: [** If tlsio_openssl_close successfully destroys the ssl connection, it shall call on_io_close_complete. **]** |
| 227 |
|
| 228 |
**SRS_TLSIO_SSL_ESP8266_99_052: [** If tlsio_openssl_close fails to shutdown the ssl connection, it shall set the tlsio state as TLSIO_STATE_ERROR, and return _LINE_, and call on_io_error. **]** |
| 229 |
|
| 230 |
|
| 231 |
### tlsio_openssl_send |
| 232 |
Implementation of `IO_SEND concrete_io_send` |
| 233 |
```c |
| 234 |
int tlsio_openssl_send(CONCRETE_IO_HANDLE tls_io, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context) |
| 235 |
``` |
| 236 |
|
| 237 |
**SRS_TLSIO_SSL_ESP8266_99_053: [** The tlsio_openssl_send shall send all bytes in a buffer to the ssl connection. **]** |
| 238 |
|
| 239 |
**SRS_TLSIO_SSL_ESP8266_99_054: [** The tlsio_openssl_send shall use the provided on_io_send_complete callback function address. **]** |
| 240 |
|
| 241 |
**SRS_TLSIO_SSL_ESP8266_99_055: [** The tlsio_openssl_send shall use the provided on_io_send_complete_context handle. **]** |
| 242 |
|
| 243 |
**SRS_TLSIO_SSL_ESP8266_99_056: [** The ssl will continue to send all data in the buffer until all bytes have been sent. **]** |
| 244 |
|
| 245 |
**SRS_TLSIO_SSL_ESP8266_99_057: [** If the ssl was not able to send all the bytes in the buffer, the tlsio_openssl_send shall call the on_send_complete with IO_SEND_ERROR, and return _LINE_. **]** |
| 246 |
|
| 247 |
**SRS_TLSIO_SSL_ESP8266_99_058: [** If the ssl finish to send all bytes in the buffer, then tlsio_openssl_send shall call the on_send_complete with IO_SEND_OK, and return 0 **]** |
| 248 |
|
| 249 |
**SRS_TLSIO_SSL_ESP8266_99_059: [** If the tlsio state is not TLSIO_STATE_OPEN, the tlsio_openssl_send shall return _LINE_. **]** |
| 250 |
|
| 251 |
**SRS_TLSIO_SSL_ESP8266_99_060: [** If the tls_io handle is NULL, the tlsio_openssl_send shall not do anything, and return _LINE_. **]** |
| 252 |
|
| 253 |
**SRS_TLSIO_SSL_ESP8266_99_061: [** If the buffer is NULL, the tlsio_openssl_send shall not do anything, and return _LINE_. **]** |
| 254 |
|
| 255 |
**SRS_TLSIO_SSL_ESP8266_99_062: [** If the size is 0, the tlsio_openssl_send shall not do anything, and return _LINE_. **]** |
| 256 |
|
| 257 |
|
| 258 |
### tlsio_openssl_dowork |
| 259 |
Implementation of `IO_DOWORK concrete_io_dowork` |
| 260 |
```c |
| 261 |
void tlsio_openssl_dowork(CONCRETE_IO_HANDLE tls_io) |
| 262 |
``` |
| 263 |
|
| 264 |
**SRS_TLSIO_SSL_ESP8266_99_063: [** The tlsio_openssl_dowork shall execute the async jobs for the tlsio. **]** |
| 265 |
|
| 266 |
**SRS_TLSIO_SSL_ESP8266_99_069: [** If the tlsio state is TLSIO_STATE_OPEN, the tlsio_openssl_dowork shall read data from the ssl client. **]** |
| 267 |
|
| 268 |
**SRS_TLSIO_SSL_ESP8266_99_070: [** If there are received data in the ssl client, the tlsio_openssl_dowork shall read this data and call the on_bytes_received with the pointer to the buffer with the data. **]** |
| 269 |
|
| 270 |
**SRS_TLSIO_SSL_ESP8266_99_071: [** If there are no received data in the ssl client, the tlsio_openssl_dowork shall do nothing. **]** |
| 271 |
|
| 272 |
**SRS_TLSIO_SSL_ESP8266_99_074: [** If the tlsio handle is NULL, the tlsio_openssl_dowork shall not do anything. **]** |
| 273 |
|
| 274 |
**SRS_TLSIO_SSL_ESP8266_99_075: [** The tlsio_openssl_dowork shall create a buffer to store the data received from the ssl client. **]** |
| 275 |
|
| 276 |
**SRS_TLSIO_SSL_ESP8266_99_076: [** The tlsio_openssl_dowork shall delete the buffer to store the data received from the ssl client. **]** |
| 277 |
|
| 278 |
|
| 279 |
### tlsio_openssl_setoption |
| 280 |
Implementation of `IO_SETOPTION concrete_io_setoption` |
| 281 |
```c |
| 282 |
int tlsio_openssl_setoption(CONCRETE_IO_HANDLE tls_io, const char* optionName, const void* value) |
| 283 |
``` |
| 284 |
|
| 285 |
**SRS_TLSIO_SSL_ESP8266_99_077: [** The tlsio_openssl_setoption shall not do anything, and return 0. **]** |
| 286 |
|
| 287 |
|
| 288 |
### tlsio_openssl_retrieveoptions |
| 289 |
Implementation of `IO_RETRIEVEOPTIONS concrete_io_retrieveoptions` |
| 290 |
```c |
| 291 |
OPTIONHANDLER_HANDLE tlsio_openssl_retrieveoptions(CONCRETE_IO_HANDLE tlsio_handle) |
| 292 |
``` |
| 293 |
|
| 294 |
**SRS_TLSIO_SSL_ESP8266_99_078: [** The tlsio_openssl_retrieveoptions shall not do anything, and return NULL. **]** |
| 295 |
|
| 296 |
|