Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/tlsio_ssl_esp8266.md

raw
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