tlsio_ssl_esp8266
=============

## Overview

tlsio_ssl_esp8266 implements a tls adapter for the ESP8266 RTOS platform. This adapter only works in blocking mode. 


## References

[TLS Protocol (RFC2246)](https://www.ietf.org/rfc/rfc2246.txt)

[TLS Protocol (generic information)](https://en.wikipedia.org/wiki/Transport_Layer_Security)

## Exposed API

**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`. 
```c
typedef OPTIONHANDLER_HANDLE (*IO_RETRIEVEOPTIONS)(CONCRETE_IO_HANDLE concrete_io);
typedef CONCRETE_IO_HANDLE(*IO_CREATE)(void* io_create_parameters);
typedef void(*IO_DESTROY)(CONCRETE_IO_HANDLE concrete_io);
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);
typedef int(*IO_CLOSE)(CONCRETE_IO_HANDLE concrete_io, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* callback_context);
typedef int(*IO_SEND)(CONCRETE_IO_HANDLE concrete_io, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context);
typedef void(*IO_DOWORK)(CONCRETE_IO_HANDLE concrete_io);
typedef int(*IO_SETOPTION)(CONCRETE_IO_HANDLE concrete_io, const char* optionName, const void* value);


typedef struct IO_INTERFACE_DESCRIPTION_TAG
{
    IO_RETRIEVEOPTIONS concrete_io_retrieveoptions;
    IO_CREATE concrete_io_create;
    IO_DESTROY concrete_io_destroy;
    IO_OPEN concrete_io_open;
    IO_CLOSE concrete_io_close;
    IO_SEND concrete_io_send;
    IO_DOWORK concrete_io_dowork;
    IO_SETOPTION concrete_io_setoption;
} IO_INTERFACE_DESCRIPTION;
```
**]**

**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`:
```c
typedef enum IO_OPEN_RESULT_TAG
{
    IO_OPEN_OK,
    IO_OPEN_ERROR,
    IO_OPEN_CANCELLED
} IO_OPEN_RESULT;
```
**]**

**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`:
```c
typedef enum IO_SEND_RESULT_TAG
{
    IO_SEND_OK,
    IO_SEND_ERROR,
    IO_SEND_CANCELLED
} IO_SEND_RESULT;
```
**]**

**SRS_TLSIO_SSL_ESP8266_99_004: [** The tlsio_ssl_esp8266 shall call the callbacks functions defined in the `xio.h`:
```c
typedef void(*ON_BYTES_RECEIVED)(void* context, const unsigned char* buffer, size_t size);
typedef void(*ON_SEND_COMPLETE)(void* context, IO_SEND_RESULT send_result);
typedef void(*ON_IO_OPEN_COMPLETE)(void* context, IO_OPEN_RESULT open_result);
typedef void(*ON_IO_CLOSE_COMPLETE)(void* context);
typedef void(*ON_IO_ERROR)(void* context);
```
**]**

**SRS_TLSIO_SSL_ESP8266_99_005: [** The tlsio_ssl_esp8266 shall received the connection information using the TLSIO_CONFIG structure defined in `tlsio.h`:
```c
typedef struct TLSIO_CONFIG_TAG
{
    const char* hostname;
    int port;
} TLSIO_CONFIG;
```
**]**


## Callbacks

**SRS_TLSIO_SSL_ESP8266_99_006: [** The tlsio_ssl_esp8266 shall return the status of all async operations using the callbacks. **]**

**SRS_TLSIO_SSL_ESP8266_99_007: [** If the callback function is set as NULL. The tlsio_ssl_esp8266 shall not call anything. **]**


###  tlsio_openssl_get_interface_description
```c
const IO_INTERFACE_DESCRIPTION* tlsio_openssl_get_interface_description(void);
```

**SRS_TLSIO_SSL_ESP8266_99_008: [** The tlsio_openssl_get_interface_description shall return the VTable IO_INTERFACE_DESCRIPTION. **]**


###  tlsio_openssl_create
Implementation of `IO_CREATE concrete_io_create`
```c
CONCRETE_IO_HANDLE tlsio_openssl_create(void* io_create_parameters);
```

**SRS_TLSIO_SSL_ESP8266_99_009: [** The tlsio_openssl_create shall create a new instance of the tlsio for esp8266. **]**

**SRS_TLSIO_SSL_ESP8266_99_010: [** The tlsio_openssl_create shall return a non-NULL handle on success. **]**

**SRS_TLSIO_SSL_ESP8266_99_011: [** The tlsio_openssl_create shall allocate memory to control the tlsio instance. **]**

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

**SRS_TLSIO_SSL_ESP8266_99_013: [** The tlsio_openssl_create shall return NULL when io_create_parameters is NULL. **]**

**SRS_TLSIO_SSL_ESP8266_99_016: [** The tlsio_openssl_create shall initialize all callback pointers as NULL. **]**

**SRS_TLSIO_SSL_ESP8266_99_017: [** The tlsio_openssl_create shall receive the connection configuration (TLSIO_CONFIG). **]**

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


###  tlsio_openssl_destroy
Implementation of `IO_DESTROY concrete_io_destroy`
```c
void tlsio_openssl_destroy(CONCRETE_IO_HANDLE tls_io);
```

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

**SRS_TLSIO_SSL_ESP8266_99_022: [** The tlsio_openssl_destroy shall free all memory allocated for tlsio_instance. **]**

**SRS_TLSIO_SSL_ESP8266_99_024: [** If the tlsio_handle is NULL, the tlsio_openssl_destroy shall not do anything. **]**

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


###  tlsio_openssl_open
Implementation of `IO_OPEN concrete_io_open`
```c
int tlsio_openssl_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);
```

**SRS_TLSIO_SSL_ESP8266_99_018: [** The tlsio_openssl_open shall convert the provide hostName to an IP address. **]**

**SRS_TLSIO_SSL_ESP8266_99_019: [** If the WiFi cannot find the IP for the hostName, the tlsio_openssl_open shall return __LINE__. **]**

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

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

**SRS_TLSIO_SSL_ESP8266_99_028: [** The tlsio_openssl_open shall store the provided on_io_open_complete callback function address. **]**

**SRS_TLSIO_SSL_ESP8266_99_029: [** The tlsio_openssl_open shall store the provided on_io_open_complete_context handle. **]**

**SRS_TLSIO_SSL_ESP8266_99_030: [** The tlsio_openssl_open shall store the provided on_bytes_received callback function address. **]**

**SRS_TLSIO_SSL_ESP8266_99_031: [** The tlsio_openssl_open shall store the provided on_bytes_received_context handle. **]**

**SRS_TLSIO_SSL_ESP8266_99_032: [** The tlsio_openssl_open shall store the provided on_io_error callback function address. **]**

**SRS_TLSIO_SSL_ESP8266_99_033: [** The tlsio_openssl_open shall store the provided on_io_error_context handle. **]**

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

**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_. **]**

**SRS_TLSIO_SSL_ESP8266_99_036: [** If the tls_io handle is NULL, the tlsio_openssl_open shall not do anything, and return _LINE_. **]**

**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_. **]**

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

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

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

**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__. **]**

**SRS_TLSIO_SSL_ESP8266_99_080: [** If socket failed, the tlsio_openssl_open shall return __LINE__. **]**

**SRS_TLSIO_SSL_ESP8266_99_081: [** If setsockopt failed, the tlsio_openssl_open shall return __LINE__. **]**

**SRS_TLSIO_SSL_ESP8266_99_082: [** If bind failed, the tlsio_openssl_open shall return __LINE__. **]**

**SRS_TLSIO_SSL_ESP8266_99_083: [** If connect and getsockopt failed, the tlsio_openssl_open shall return __LINE__. **]**

**SRS_TLSIO_SSL_ESP8266_99_084: [** If lwip_select failed, the tlsio_openssl_open shall return __LINE__. **]**

**SRS_TLSIO_SSL_ESP8266_99_085: [** If SSL_CTX_new failed, the tlsio_openssl_open shall return __LINE__. **]**

**SRS_TLSIO_SSL_ESP8266_99_087: [** If SSL_new failed, the tlsio_openssl_open shall return __LINE__. **]**

**SRS_TLSIO_SSL_ESP8266_99_088: [** If SSL_set_fd failed, the tlsio_openssl_open shall return __LINE__. **]**

**SRS_TLSIO_SSL_ESP8266_99_089: [** If SSL_connect failed, the tlsio_openssl_open shall return __LINE__. **]**

###  tlsio_openssl_close
Implementation of `IO_CLOSE concrete_io_close`
```c
int tlsio_openssl_close(CONCRETE_IO_HANDLE tls_io, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* callback_context);
```

**SRS_TLSIO_SSL_ESP8266_99_043: [** The tlsio_openssl_close shall start the process to close the ssl connection. **]**

**SRS_TLSIO_SSL_ESP8266_99_045: [** The tlsio_openssl_close shall store the provided on_io_close_complete callback function address. **]**

**SRS_TLSIO_SSL_ESP8266_99_046: [** The tlsio_openssl_close shall store the provided on_io_close_complete_context handle. **]**

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

**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_. **]**

**SRS_TLSIO_SSL_ESP8266_99_049: [** If the tlsio_handle is NULL, the tlsio_openssl_close shall not do anything, and return _LINE_. **]**

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

**SRS_TLSIO_SSL_ESP8266_99_051: [** If tlsio_openssl_close successfully destroys the ssl connection, it shall call on_io_close_complete. **]**

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


###  tlsio_openssl_send
Implementation of `IO_SEND concrete_io_send`
```c
int tlsio_openssl_send(CONCRETE_IO_HANDLE tls_io, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context)
```

**SRS_TLSIO_SSL_ESP8266_99_053: [** The tlsio_openssl_send shall send all bytes in a buffer to the ssl connection. **]**

**SRS_TLSIO_SSL_ESP8266_99_054: [** The tlsio_openssl_send shall use the provided on_io_send_complete callback function address. **]**

**SRS_TLSIO_SSL_ESP8266_99_055: [** The tlsio_openssl_send shall use the provided on_io_send_complete_context handle. **]**

**SRS_TLSIO_SSL_ESP8266_99_056: [** The ssl will continue to send all data in the buffer until all bytes have been sent. **]**

**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_. **]**

**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 **]**

**SRS_TLSIO_SSL_ESP8266_99_059: [** If the tlsio state is not TLSIO_STATE_OPEN, the tlsio_openssl_send shall return _LINE_. **]**

**SRS_TLSIO_SSL_ESP8266_99_060: [** If the tls_io handle is NULL, the tlsio_openssl_send shall not do anything, and return _LINE_. **]**

**SRS_TLSIO_SSL_ESP8266_99_061: [** If the buffer is NULL, the tlsio_openssl_send shall not do anything, and return _LINE_. **]**

**SRS_TLSIO_SSL_ESP8266_99_062: [** If the size is 0, the tlsio_openssl_send shall not do anything, and return _LINE_. **]**


###  tlsio_openssl_dowork
Implementation of `IO_DOWORK concrete_io_dowork`
```c
void tlsio_openssl_dowork(CONCRETE_IO_HANDLE tls_io)
```

**SRS_TLSIO_SSL_ESP8266_99_063: [** The tlsio_openssl_dowork shall execute the async jobs for the tlsio. **]**

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

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

**SRS_TLSIO_SSL_ESP8266_99_071: [** If there are no received data in the ssl client, the tlsio_openssl_dowork shall do nothing. **]**

**SRS_TLSIO_SSL_ESP8266_99_074: [** If the tlsio handle is NULL, the tlsio_openssl_dowork shall not do anything. **]**

**SRS_TLSIO_SSL_ESP8266_99_075: [** The tlsio_openssl_dowork shall create a buffer to store the data received from the ssl client. **]**

**SRS_TLSIO_SSL_ESP8266_99_076: [** The tlsio_openssl_dowork shall delete the buffer to store the data received from the ssl client. **]**


###  tlsio_openssl_setoption
Implementation of `IO_SETOPTION concrete_io_setoption`
```c
int tlsio_openssl_setoption(CONCRETE_IO_HANDLE tls_io, const char* optionName, const void* value)
```

**SRS_TLSIO_SSL_ESP8266_99_077: [** The tlsio_openssl_setoption shall not do anything, and return 0. **]**


###  tlsio_openssl_retrieveoptions
Implementation of `IO_RETRIEVEOPTIONS concrete_io_retrieveoptions`
```c
OPTIONHANDLER_HANDLE tlsio_openssl_retrieveoptions(CONCRETE_IO_HANDLE tlsio_handle)
```

**SRS_TLSIO_SSL_ESP8266_99_078: [** The tlsio_openssl_retrieveoptions shall not do anything, and return NULL. **]**