Debian Codegraph @

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

raw
1 # tlsio
2
3 ## Overview
4
5 This specification defines generic behavior for tlsio adapters, which operate primarily through the `xio`
6 interface and provide communication to remote systems over a TLS-conformant secure channel.
7
8 ## References
9
10 [TLS Protocol (RFC2246)](https://www.ietf.org/rfc/rfc2246.txt)
11
12 [TLS Protocol (generic information)](https://en.wikipedia.org/wiki/Transport_Layer_Security)
13
14 [xio.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/xio.h)
15
16
17 ## Exposed API
18
19 **SRS_TLSIO_30_001: [** The tlsio shall implement and export all the Concrete functions in the VTable IO_INTERFACE_DESCRIPTION defined in the `xio.h`.
20 ```c
21 typedef OPTIONHANDLER_HANDLE (*IO_RETRIEVEOPTIONS)(CONCRETE_IO_HANDLE concrete_io);
22 typedef CONCRETE_IO_HANDLE(*IO_CREATE)(void* io_create_parameters);
23 typedef void(*IO_DESTROY)(CONCRETE_IO_HANDLE concrete_io);
24 typedef int(*IO_OPEN)(CONCRETE_IO_HANDLE concrete_io, ON_IO_OPEN_COMPLETE on_io_open_complete,
25 void* on_io_open_complete_context, ON_BYTES_RECEIVED on_bytes_received,
26 void* on_bytes_received_context, ON_IO_ERROR on_io_error, void* on_io_error_context);
27 typedef int(*IO_CLOSE)(CONCRETE_IO_HANDLE concrete_io, ON_IO_CLOSE_COMPLETE on_io_close_complete,
28 void* callback_context);
29 typedef int(*IO_SEND)(CONCRETE_IO_HANDLE concrete_io, const void* buffer, size_t size,
30 ON_SEND_COMPLETE on_send_complete, void* callback_context);
31 typedef void(*IO_DOWORK)(CONCRETE_IO_HANDLE concrete_io);
32 typedef int(*IO_SETOPTION)(CONCRETE_IO_HANDLE concrete_io, const char* optionName,
33 const void* value);
34
35
36 typedef struct IO_INTERFACE_DESCRIPTION_TAG
37 {
38 IO_RETRIEVEOPTIONS concrete_io_retrieveoptions;
39 IO_CREATE concrete_io_create;
40 IO_DESTROY concrete_io_destroy;
41 IO_OPEN concrete_io_open;
42 IO_CLOSE concrete_io_close;
43 IO_SEND concrete_io_send;
44 IO_DOWORK concrete_io_dowork;
45 IO_SETOPTION concrete_io_setoption;
46 } IO_INTERFACE_DESCRIPTION;
47 ```
48 **]**
49
50 The following types from `xio.h` are also referenced in individual requirements.
51 ```c
52
53 typedef enum IO_OPEN_RESULT_TAG
54 {
55 IO_OPEN_OK,
56 IO_OPEN_ERROR,
57 IO_OPEN_CANCELLED
58 } IO_OPEN_RESULT;
59
60 typedef enum IO_SEND_RESULT_TAG
61 {
62 IO_SEND_OK,
63 IO_SEND_ERROR,
64 IO_SEND_CANCELLED
65 } IO_SEND_RESULT;
66
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 typedef struct TLSIO_CONFIG_TAG
74 {
75 const char* hostname;
76 int port;
77 const IO_INTERFACE_DESCRIPTION* underlying_io_interface;
78 void* underlying_io_parameters;
79 } TLSIO_CONFIG;
80 ```
81
82 ## External State
83 The external state of the tlsio adapter is determined by which of the adapter's interface functions have been called and which callbacks have been performed. The adapter's internal state should map cleanly to its external state, but the mapping is not necessarily 1:1. The external states are defined as follows:
84
85 * TLSIO_STATE_EXT_CLOSED means either that the module is newly constructed by `tlsio_create`, that the `tlsio_close_async` complete callback has been received, or that the `on_tlsio_open_complete` callback has returned with `IO_OPEN_ERROR`.
86 * TLSIO_STATE_EXT_OPENING means that the `tlsio_open_async` call has completed successfully but the `on_tlsio_open_complete` callback has not been performed.
87 * TLSIO_STATE_EXT_OPEN means that the `on_tlsio_open_complete` callback has returned with `IO_OPEN_OK`.
88 * TLSIO_STATE_EXT_CLOSING means that either the `tlsio_close_async` call has completed successfully but the `on_tlsio_close_complete` callback has not yet been performed, or that the `on_tlsio_open_complete` callback has returned with `IO_OPEN_CANCELLED`.
89 * TLSIO_STATE_EXT_ERROR means that `on_io_error` has been called from `tlsio_dowork`.
90
91 ## State Transitions
92 This list shows the effect of the calls as a function of state with happy internal functionality. Unhappy functionality is not shown. The `tlsio_setoption` and `tlsio_getoptions` calls are not shown because they have no effect on state and are always allowed. Calls to `tlsio_send_async` also do not affect state, and are allowed only during TLSIO_STATE_EXT_OPEN.
93
94 All transitions into TLSIO_STATE_EXT_CLOSED are understood to pass through TLSIO_STATE_EXT_CLOSING.
95
96
97 <table>
98 <tr>From state <b>TLSIO_STATE_EXT_CLOSED</b></tr>
99 <tr>
100 <td>tlsio_destroy</td>
101 <td>ok (destroyed)</td>
102 </tr>
103 <tr>
104 <td>tlsio_open_async</td>
105 <td>ok, enter TLSIO_STATE_EXT_OPENING</td>
106 </tr>
107 <tr>
108 <td>tlsio_close_async</td>
109 <td>ok, remain in TLSIO_STATE_EXT_CLOSED</td>
110 </tr>
111 <tr>
112 <td>tlsio_dowork</td>
113 <td>ok (does nothing), remain in TLSIO_STATE_EXT_CLOSED</td>
114 </tr>
115 </table>
116
117 <table>
118 <tr>From state <b>TLSIO_STATE_EXT_OPENING</b></tr>
119 <tr>
120 <td>tlsio_destroy</td>
121 <td>log error, force immediate close, destroy (destroyed)</td>
122 </tr>
123 <tr>
124 <td>tlsio_open_async</td>
125 <td>fail, log error, remain in TLSIO_STATE_EXT_OPENING (usage error)</td>
126 </tr>
127 <tr>
128 <td>tlsio_close_async</td>
129 <td>ok, force immediate close, enter TLSIO_STATE_EXT_CLOSED</td>
130 </tr>
131 <tr>
132 <td>tlsio_dowork</td>
133 <td>ok (continue opening), remain in TLSIO_STATE_EXT_OPENING or enter TLSIO_STATE_EXT_OPEN</td>
134 </tr>
135 </table>
136
137 <table>
138 <tr>From state <b>TLSIO_STATE_EXT_OPEN</b></tr>
139 <tr>
140 <td>tlsio_destroy</td>
141 <td>(a possible normal SDK behavior) force immediate close, destroy (destroyed)</td>
142 </tr>
143 <tr>
144 <td>tlsio_open_async</td>
145 <td>fail, log error, remain in TLSIO_STATE_EXT_OPEN (usage error)</td>
146 </tr>
147 <tr>
148 <td>tlsio_close_async</td>
149 <td>adapters with internal async close: ok, enter TLSIO_STATE_EXT_CLOSING<br/>adatpers without internal async close: ok, enter TLSIO_STATE_EXT_CLOSING, then <br/>immediately enter TLSIO_STATE_EXT_CLOSED</td>
150 </tr>
151 <tr>
152 <td>tlsio_dowork</td>
153 <td>ok (send and receive as necessary), remain in TLSIO_STATE_EXT_OPEN</td>
154 </tr>
155 </table>
156
157 <table>
158 <tr>From state <b>TLSIO_STATE_EXT_CLOSING</b></tr>
159 <tr>
160 <td>tlsio_destroy</td>
161 <td>log error, force immediate close, destroy (destroyed)</td>
162 </tr>
163 <tr>
164 <td>tlsio_open_async</td>
165 <td>fail, log error, remain in TLSIO_STATE_EXT_CLOSING (usage error)</td>
166 </tr>
167 <tr>
168 <td>tlsio_close_async</td>
169 <td>ok, force immediate close, enter TLSIO_STATE_EXT_CLOSED</td>
170 </tr>
171 <tr>
172 <td>tlsio_dowork</td>
173 <td>ok (continue graceful closing) , remain in TLSIO_STATE_EXT_CLOSING or <br/>enter TLSIO_STATE_EXT_CLOSED</td>
174 </tr>
175 </table>
176
177 <table>
178 <tr>From state <b>TLSIO_STATE_EXT_ERROR</b></tr>
179 <tr>
180 <td>tlsio_destroy</td>
181 <td>log error, force immediate close, destroy (destroyed)</td>
182 </tr>
183 <tr>
184 <td>tlsio_open_async</td>
185 <td>fail, log error, remain in TLSIO_STATE_EXT_ERROR (usage error)</td>
186 </tr>
187 <tr>
188 <td>tlsio_close_async</td>
189 <td>ok, force immediate close, enter TLSIO_STATE_EXT_CLOSED</td>
190 </tr>
191 <tr>
192 <td>tlsio_dowork</td>
193 <td>ok (does nothing), remain in TLSIO_STATE_EXT_ERROR</td>
194 </tr>
195 </table>
196
197 ![State transition diagram](img/tlsio_state_diagram.png)
198
199 ## Definitions
200
201 #### Explicit state transitions
202
203 Throughout this document, state transitions only occur as explicitly specified. If no state transition is called out, then none is allowed. (So "do nothing" is always understood as the default.)
204
205 #### Specified state transitions
206
207 Requirements in this document use the phrase "shall enter TLSIO_STATE_EXT_XXXX" to specify behavior. Here are the definitions of the state transition phrases:
208
209 ##### "enter TLSIO_STATE_EXT_ERROR"
210 **SRS_TLSIO_30_005: [** The phrase "enter TLSIO_STATE_EXT_ERROR" means the adapter shall call the `on_io_error` function and pass the `on_io_error_context` that was supplied in `tlsio_open_async`. **]**
211
212 ##### "enter TLSIO_STATE_EXT_CLOSING"
213 **SRS_TLSIO_30_009: [** The phrase "enter TLSIO_STATE_EXT_CLOSING" means the adapter shall iterate through any unsent messages in the queue and shall delete each message after calling its `on_send_complete` with the associated `callback_context` and `IO_SEND_CANCELLED`. **]**
214
215 ##### "enter TLSIO_STATE_EXT_CLOSED"
216 **SRS_TLSIO_30_006: [** The phrase "enter TLSIO_STATE_EXT_CLOSED" means the adapter shall forcibly close any existing connections then call the `on_io_close_complete` function and pass the `on_io_close_complete_context` that was supplied in `tlsio_close_async`. **]**
217
218 ##### "enter TLSIO_STATE_EXT_OPENING"
219 The phrase "enter TLSIO_STATE_EXT_OPENING" means the adapter will continute the process of opening the TSL connection to the host on the next `tlsio_dowork` call, but no other externally visible action is being specified.
220
221 ##### "enter TLSIO_STATE_EXT_OPEN"
222 **SRS_TLSIO_30_007: [** The phrase "enter TLSIO_STATE_EXT_OPEN" means the adapter shall call the `on_io_open_complete` function and pass IO_OPEN_OK and the `on_io_open_complete_context` that was supplied in `tlsio_open_async`. **]**
223
224 ##### "destroy the failed message"
225 **SRS_TLSIO_30_002: [** The phrase "destroy the failed message" means that the adapter shall remove the message from the queue and destroy it after calling the message's `on_send_complete` along with its associated `callback_context` and `IO_SEND_ERROR`. **]**
226
227
228
229
230 ## API Calls
231
232 ### tlsio_get_interface_description
233 ```c
234 const IO_INTERFACE_DESCRIPTION* tlsio_get_interface_description(void);
235 ```
236
237 **SRS_TLSIO_30_008: [** The tlsio_get_interface_description shall return the VTable IO_INTERFACE_DESCRIPTION. **]**
238
239
240 ### tlsio_create
241 Implementation of `concrete_io_create`.
242 ```c
243 CONCRETE_IO_HANDLE tlsio_create(void* io_create_parameters);
244 ```
245
246 ##### _Direct_ versus _chained_ tlsio adapters
247
248 Tlsio adapters have two different styles of implementation: _direct_, and _chained_. A _direct_
249 tlsio adapter communicates directly with the remote host using a TCP port that the tlsio adapter
250 owns. A _chained_ tlsio adapter does not own a TCP port, and instead owns another xio adapter --
251 typically a `socketio` as explained
252 [here](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/porting_guide.md#socketio-adapter-overview)
253 which it uses to communicate with the remote host.
254
255 For the purposes of this spec, an _owned xio resource_ is an xio adapter created by the tlsio
256 adapter to communicate with the remote host, and whose lifetime is managed by the tlsio
257 adapter according to standard programming practices. Its lifetime management is covered by the
258 "all necessary resources" clauses of the `tlsio_create` and `tlsio_destroy` requirements.
259
260 For _chained_ tlsio adapters, the _owned xio resource_ type may be specifed in the
261 `underlying_io_interface` member of `io_create_parameters`. If it is not, then it is
262 understood that the tlsio adapter will need to create a `socketio`
263 using the supplied `hostname` and `port` via the global
264 `socketio_get_interface_description` function defined in
265 [socketio.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/socketio.h).
266 This practical necessity is not specified in this document as a requirement because it is
267 considered an internal implementation detail.
268
269
270 **SRS_TLSIO_30_010: [** The `tlsio_create` shall allocate and initialize all necessary resources and return an instance of the `tlsio` in TLSIO_STATE_EXT_CLOSED. **]**
271
272 **SRS_TLSIO_30_011: [** If any resource allocation fails, `tlsio_create` shall return NULL. **]**
273
274 **SRS_TLSIO_30_012: [** The `tlsio_create` shall receive the connection configuration as a `TLSIO_CONFIG*` in `io_create_parameters`. **]**
275
276 **SRS_TLSIO_30_013: [** If the `io_create_parameters` value is NULL, `tlsio_create` shall log an error and return NULL. **]**
277
278 **SRS_TLSIO_30_014: [** If the `hostname` member of `io_create_parameters` value is NULL, `tlsio_create` shall log an error and return NULL. **]**
279
280 **SRS_TLSIO_30_015: [** If the `port` member of `io_create_parameters` value is less than 0 or greater than 0xffff, `tlsio_create` shall log an error and return NULL. **]**
281
282 **SRS_TLSIO_30_016: [** `tlsio_create` shall make a copy of the `hostname` member of `io_create_parameters` to allow deletion of `hostname` immediately after the call. This copy may be delegated to an underlying `xio`. **]**
283
284 **SRS_TLSIO_30_017: [** For _direct_ designs, if either the `underlying_io_interface` or `underlying_io_parameters` of `io_create_parameters` is non-NULL, `tlsio_create` shall log an error and return NULL. **]**
285
286 **SRS_TLSIO_30_018: [** For _chained_ designs, if the `underlying_io_interface` member of `io_create_parameters` is non-NULL, `tlsio_create` shall use `underlying_io_interface` to create an _owned xio resource_ for remote host communication. **]**
287
288 **SRS_TLSIO_30_019: [** For _chained_ designs with a non-NULL `underlying_io_interface` parameter, `tlsio_create` shall pass the `underlying_io_parameters` to `underlying_io_interface->xio_create` when creating the _owned xio resource_. **]**
289
290
291 ### tlsio_destroy
292 Implementation of `concrete_io_destroy`
293 ```c
294 void tlsio_destroy(CONCRETE_IO_HANDLE tlsio_handle);
295 ```
296
297 **SRS_TLSIO_30_020: [** If `tlsio_handle` is NULL, `tlsio_destroy` shall do nothing. **]**
298
299 **SRS_TLSIO_30_021: [** The `tlsio_destroy` shall release all allocated resources and then release `tlsio_handle`. **]**
300
301 **SRS_TLSIO_30_022: [** If the adapter is in any state other than TLSIO_STATE_EXT_CLOSED when `tlsio_destroy` is called, the adapter shall [enter TLSIO_STATE_EXT_CLOSING](#enter-TLSIO_STATE_EXT_CLOSING "Iterate through any unsent messages in the queue and delete each message after calling its `on_send_complete` with the associated `callback_context` and `IO_SEND_CANCELLED`.") and then [enter TLSIO_STATE_EXT_CLOSED](#enter-TLSIO_STATE_EXT_CLOSED "Forcibly close any existing connections then call the `on_io_close_complete` function and pass the `on_io_close_complete_context` that was supplied in `tlsio_close_async`.") before completing the destroy process. **]**
302
303
304 ### tlsio_open_async
305 Implementation of `concrete_io_open`
306
307 ```c
308 int tlsio_open_async(
309 CONCRETE_IO_HANDLE tlsio_handle,
310 ON_IO_OPEN_COMPLETE on_io_open_complete,
311 void* on_io_open_complete_context,
312 ON_BYTES_RECEIVED on_bytes_received,
313 void* on_bytes_received_context,
314 ON_IO_ERROR on_io_error,
315 void* on_io_error_context);
316 ```
317
318 **SRS_TLSIO_30_030: [** If the `tlsio_handle` parameter is NULL, `tlsio_open_async` shall log an error and return `_FAILURE_`. **]**
319
320 **SRS_TLSIO_30_031: [** If the on_io_open_complete parameter is NULL, `tlsio_open_async` shall log an error and return `_FAILURE_`. **]**
321
322 **SRS_TLSIO_30_032: [** If the on_bytes_received parameter is NULL, `tlsio_open_async` shall log an error and return `_FAILURE_`. **]**
323
324 **SRS_TLSIO_30_033: [** If the on_io_error parameter is NULL, `tlsio_open_async` shall log an error and return `_FAILURE_`. **]**
325
326 **SRS_TLSIO_30_037: [** If the adapter is in any state other than TLSIO_STATE_EXT_CLOSED when `tlsio_open_async` is called, it shall log an error, and return `_FAILURE_`. **]**
327
328 **SRS_TLSIO_30_038: [** If `tlsio_open_async` fails to [enter TLSIO_STATE_EXT_OPENING](#enter-TLSIO_STATE_EXT_OPENING "Continute the process of opening the TSL connection to the host on the next `tlsio_dowork` call") it shall return `_FAILURE_`. **]**
329
330 **SRS_TLSIO_30_039: [** On failure, `tlsio_open_async` shall not call `on_io_open_complete`. **]**
331
332 **SRS_TLSIO_30_034: [** On success, `tlsio_open_async` shall store the provided `on_bytes_received`, `on_bytes_received_context`, `on_io_error`, `on_io_error_context`, `on_io_open_complete`, and `on_io_open_complete_context` parameters for later use as specified and tested per other line entries in this document. **]**
333
334 **SRS_TLSIO_30_035: [** On success, `tlsio_open_async` shall cause the adapter to [enter TLSIO_STATE_EXT_OPENING](#enter-TLSIO_STATE_EXT_OPENING "Continute the process of opening the TSL connection to the host on the next `tlsio_dowork` call") and return 0. **]**
335
336
337 ### tlsio_close_async
338 Implementation of `concrete_io_close`
339 ```c
340 int tlsio_close_async(CONCRETE_IO_HANDLE tlsio_handle,
341 ON_IO_CLOSE_COMPLETE on_io_close_complete, void* callback_context);
342 ```
343
344 **SRS_TLSIO_30_050: [** If the `tlsio_handle` parameter is NULL, `tlsio_close_async` shall log an error and return `_FAILURE_`. **]**
345
346 **SRS_TLSIO_30_055: [** If the `on_io_close_complete` parameter is NULL, `tlsio_close_async` shall log an error and return `_FAILURE_`. **]**
347
348 **SRS_TLSIO_30_054: [** On failure, the adapter shall not call `on_io_close_complete`. **]**
349
350 **SRS_TLSIO_30_053: [** If the adapter is in any state other than TLSIO_STATE_EXT_OPEN or TLSIO_STATE_EXT_ERROR then `tlsio_close_async` shall log that `tlsio_close_async` has been called and then continue normally. **]**
351
352 **SRS_TLSIO_30_057: [** On success, if the adapter is in TLSIO_STATE_EXT_OPENING, it shall call `on_io_open_complete` with the `on_io_open_complete_context` supplied in `tlsio_open_async` and `IO_OPEN_CANCELLED`. This callback shall be made before changing the internal state of the adapter. **]**
353
354 **SRS_TLSIO_30_056: [** On success the adapter shall [enter TLSIO_STATE_EXT_CLOSING](#enter-TLSIO_STATE_EXT_CLOSING "Iterate through any unsent messages in the queue and delete each message after calling its `on_send_complete` with the associated `callback_context` and `IO_SEND_CANCELLED`."). **]**
355
356 **SRS_TLSIO_30_051: [** On success, if the underlying TLS does not support asynchronous closing or if the adapter is not in TLSIO_STATE_EXT_OPEN, then the adapter shall [enter TLSIO_STATE_EXT_CLOSED](#enter-TLSIO_STATE_EXT_CLOSED "Forcibly close any existing connections then call the `on_io_close_complete` function and pass the `on_io_close_complete_context` that was supplied in `tlsio_close_async`.") immediately after entering TLSIO_STATE_EXT_CLOSING. **]**
357
358 **SRS_TLSIO_30_052: [** On success `tlsio_close_async` shall return 0. **]**
359
360
361 ### tlsio_send_async
362 Implementation of `concrete_io_send`
363 ```c
364 int tlsio_send_async(CONCRETE_IO_HANDLE tlsio_handle, const void* buffer,
365 size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context);
366 ```
367
368 **SRS_TLSIO_30_060: [** If the `tlsio_handle` parameter is NULL, `tlsio_send_async` shall log an error and return `_FAILURE_`. **]**
369
370 **SRS_TLSIO_30_061: [** If the `buffer` is NULL, `tlsio_send_async` shall log the error and return `_FAILURE_`. **]**
371
372 **SRS_TLSIO_30_062: [** If the `on_send_complete` is NULL, `tlsio_send_async` shall log the error and return `_FAILURE_`. **]**
373
374 **SRS_TLSIO_30_067: [** If the `size` is 0, `tlsio_send_async` shall log the error and return `_FAILURE_`. **]**
375
376 **SRS_TLSIO_30_065: [** If the adapter state is not TLSIO_STATE_EXT_OPEN, `tlsio_send_async` shall log an error and return `_FAILURE_`. **]**
377
378 **SRS_TLSIO_30_064: [** If the supplied message cannot be enqueued for transmission, `tlsio_send_async` shall log an error and return `_FAILURE_`. **]**
379
380 **SRS_TLSIO_30_066: [** On failure, `on_send_complete` shall not be called. **]**
381
382 **SRS_TLSIO_30_063: [** On success, `tlsio_send_async` shall enqueue for transmission the `on_send_complete`, the `callback_context`, the `size`, and the contents of `buffer` and then return 0. **]**
383
384
385 ### tlsio_dowork
386 Implementation of `concrete_io_dowork`
387 ```c
388 void tlsio_dowork(CONCRETE_IO_HANDLE tlsio_handle);
389 ```
390 The `tlsio_dowork` call executes async jobs for the tlsio. This includes connection completion, sending to the TLS connection, and checking the TLS connection for available bytes to read.
391
392 **SRS_TLSIO_30_070: [** If the `tlsio_handle` parameter is NULL, `tlsio_dowork` shall do nothing except log an error. **]**
393
394
395 #### Behavior selection
396
397 **SRS_TLSIO_30_071: [** If the adapter is in TLSIO_STATE_EXT_ERROR then `tlsio_dowork` shall do nothing. **]**
398
399 **SRS_TLSIO_30_075: [** If the adapter is in TLSIO_STATE_EXT_CLOSED then `tlsio_dowork` shall do nothing. **]**
400
401 **SRS_TLSIO_30_077: [** If the adapter is in TLSIO_STATE_EXT_OPENING then `tlsio_dowork` shall perform only the [TLSIO_STATE_EXT_OPENING behaviors](#TLSIO_STATE_EXT_OPENING-behaviors). **]**
402
403 **SRS_TLSIO_30_077: [** If the adapter is in TLSIO_STATE_EXT_OPEN then `tlsio_dowork` shall perform only the [Data transmission behaviors](#data-transmission-behaviors) and the [Data reception behaviors](#data-reception-behaviors). **]**
404
405 **SRS_TLSIO_30_078: [** If the adapter is in TLSIO_STATE_EXT_CLOSING then `tlsio_dowork` shall perform only the [TLSIO_STATE_EXT_CLOSING behaviors](#TLSIO_STATE_EXT_CLOSING-behaviors). **]**
406
407 #### TLSIO_STATE_EXT_OPENING behaviors
408
409 Transitioning from TLSIO_STATE_EXT_OPENING to TLSIO_STATE_EXT_OPEN may require multiple calls to `tlsio_dowork`. The number of calls required is not specified.
410
411 **SRS_TLSIO_30_080: [** The `tlsio_dowork` shall establish a TLS connection using the `hostName` and `port` provided during `tlsio_open_async`. **]**
412
413 **SRS_TLSIO_30_082: [** If the connection process fails for any reason, `tlsio_dowork` shall log an error, call `on_io_open_complete` with the `on_io_open_complete_context` parameter provided in `tlsio_open_async` and `IO_OPEN_ERROR`, and [enter TLSIO_STATE_EXT_CLOSED](#enter-TLSIO_STATE_EXT_CLOSED "Forcibly close any existing connections then call the `on_io_close_complete` function and pass the `on_io_close_complete_context` that was supplied in `tlsio_close_async`."). **]**
414
415 **SRS_TLSIO_30_083: [** If `tlsio_dowork` successfully opens the TLS connection it shall [enter TLSIO_STATE_EXT_OPEN](#enter-TLSIO_STATE_EXT_OPEN "Call the `on_io_open_complete` function and pass IO_OPEN_OK and the `on_io_open_complete_context` that was supplied in `tlsio_open_async`."). **]**
416
417 #### Data transmission behaviors
418
419
420 **SRS_TLSIO_30_091: [** If `tlsio_dowork` is able to send all the bytes in an enqueued message, it shall first dequeue the message then call the messages's `on_send_complete` along with its associated `callback_context` and `IO_SEND_OK`. **]**<br/>
421 The message needs to be dequeued before calling the callback because the callback may trigger a re-entrant
422 `tlsio_close` call which will need a consistent message queue.
423
424 **SRS_TLSIO_30_093: [** If the TLS connection was not able to send an entire enqueued message at once, subsequent calls to `tlsio_dowork` shall continue to send the remaining bytes. **]**
425
426 **SRS_TLSIO_30_095: [** If the send process fails before sending all of the bytes in an enqueued message, `tlsio_dowork` shall [destroy the failed message](#destroy-the-failed-message "Remove the message from the queue and destroy it after calling the message's `on_send_complete` along with its associated `callback_context` and `IO_SEND_ERROR`.") and [enter TLSIO_STATE_EXT_ERROR](#enter-TLSIO_STATE_EXT_ERROR "Call the `on_io_error` function and pass the `on_io_error_context` that was supplied in `tlsio_open_async`."). **]**
427
428 **SRS_TLSIO_30_096: [** If there are no enqueued messages available, `tlsio_dowork` shall do nothing. **]**
429
430 #### Data reception behaviors
431
432 **SRS_TLSIO_30_100: [** As long as the TLS connection is able to provide received data, `tlsio_dowork` shall repeatedly read this data and call `on_bytes_received` with the pointer to the buffer containing the data, the number of bytes received, and the `on_bytes_received_context`. **]**
433
434 **SRS_TLSIO_30_102: [** If the TLS connection receives no data then `tlsio_dowork` shall not call the `on_bytes_received` callback. **]**
435
436 #### TLSIO_STATE_EXT_CLOSING behaviors
437
438 Adapters whose underlying TLS connection does not have an asynchronous 'closing' state will not have an externally visible TLSIO_STATE_EXT_CLOSING state and so their `tlsio_dowork` will not perform these behaviors.
439
440 **SRS_TLSIO_30_106: [** If the closing process fails to end gracefully, `tlsio_dowork` shall log an error and [enter TLSIO_STATE_EXT_CLOSED](#enter-TLSIO_STATE_EXT_CLOSED "Forcibly close any existing connections then call the `on_io_close_complete` function and pass the `on_io_close_complete_context` that was supplied in `tlsio_close_async`."). **]**
441
442 **SRS_TLSIO_30_107: [** If the closing process ends gracefully, `tlsio_dowork` shall [enter TLSIO_STATE_EXT_CLOSED](#enter-TLSIO_STATE_EXT_CLOSED "Forcibly close any existing connections then call the `on_io_close_complete` function and pass the `on_io_close_complete_context` that was supplied in `tlsio_close_async`."). **]**
443
444 ### tlsio_setoption
445 Implementation of `concrete_io_setoption`. Specific tlsio implementations must define the behavior of successful `tlsio_setoption` calls.
446
447 The options are conceptually part of `tlsio_create` in that options which are set persist until the instance is destroyed.
448 ```c
449 int tlsio_setoption(CONCRETE_IO_HANDLE tlsio_handle, const char* optionName, const void* value);
450 ```
451 **SRS_TLSIO_30_120: [** If the `tlsio_handle` parameter is NULL, `tlsio_setoption` shall do nothing except log an error and return `_FAILURE_`. **]**
452
453 **SRS_TLSIO_30_121: [** If the `optionName` parameter is NULL, `tlsio_setoption` shall do nothing except log an error and return `_FAILURE_`. **]**
454
455 **SRS_TLSIO_30_122: [** If the `value` parameter is NULL, `tlsio_setoption` shall do nothing except log an error and return `_FAILURE_`. **]**
456
457 **SRS_TLSIO_30_124 [** Adapters which implement options shall store the option value until `tlsio_destroy` is called. **]**
458
459
460 ### tlsio_retrieveoptions
461 Implementation of `concrete_io_retrieveoptions` Specific tlsio implementations must define the behavior of successful `tlsio_retrieveoptions` calls.
462
463 ```c
464 OPTIONHANDLER_HANDLE tlsio_retrieveoptions(CONCRETE_IO_HANDLE tlsio_handle);
465 ```
466
467 **SRS_TLSIO_30_160: [** If the `tlsio_handle` parameter is NULL, `tlsio_retrieveoptions` shall do nothing except log an error and return `_FAILURE_`. **]**
468
469 ### Error Recovery Testing
470 Error recovery for tlsio adapters is performed by the higher level modules that own the tlsio. There are a very large
471 number of error recovery sequences which might be performed, and performing all of the possible retry sequences
472 is out-of-scope for this document. However, the two tests here represent a minimal test suite to mimic the retry
473 sequences that the higher level modules might perform.
474
475 The test conditions in this section are deliberately underspecified and left to the judgement of the implementer, and code commenting
476 in the unit tests themselves will be considered sufficient documentation for any further detail. Any of a number of possible
477 specific call sequences is acceptable as long as the unit test meets the criteria of the test requirement.
478
479 The words "high-level retry sequence" as used in this section means that:
480 1. A failure has been injected at some specified point
481 2. `tlsio_close_async` has been called and the `on_io_close_complete` callback has been received.
482 3. `tlsio_open_async` has been called successfully.
483 4. `tlsio_dowork` has been called as necessary to permit this sequence of events.
484 5. The `on_io_open_complete` callback has been received with `IO_OPEN_OK`.
485
486 Note that the requirements in this section have corresponding entries in the unit test files, but do not
487 appear in the implementation code.
488
489 **SRS_TLSIO_30_200: [** The "high-level retry sequence" shall succeed after an injected fault which causes `on_io_open_complete` to return with `IO_OPEN_ERROR`. **]**
490
491 **SRS_TLSIO_30_201: [** The "high-level retry sequence" shall succeed after an injected fault which causes
492 `on_io_error` to be called. **]**
493
494 ## API Call Sequence Examples
495
496 ### Connect example
497
498 First `IoTHubDeviceClient_LL_SetOption` will call:
499 1. `tlsio_openssl_create`
500 1. `tlsio_openssl_setoption`
501
502 Each subsequent `IoTHubDeviceClient_LL_SetOption`
503 1. `tlsio_openssl_setoption`
504
505 First IoTHubDeviceClient_LL_DoWork:
506 1. `tlsio_openssl_open`
507
508 ### Telemetry Send example
509
510 Looping over:
511 1. `tlsio_openssl_dowork`
512 1. `tlsio_openssl_send`
513
514 ### Close example
515
516 Application calls `IoTHubDeviceClient_LL_Destroy` (`DisconnectFromClient` in MQTT):
517 1. `tlsio_openssl_close`
518 1. `tlsio_openssl_destroy`
519
520 ### Retry example
521
522 I/O failure leads to retry (`ResetConnectionIfNecessary` for MQTT):
523 1. `tlsio_openssl_retrieveoptions`
524 1. `tlsio_openssl_destroy`
525 1. `tlsio_openssl_create`
526 1. `tlsio_openssl_setoption` - Repeats multiple times as it clones all configuration options.
527 1. `tlsio_openssl_open`