Debian Codegraph @

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

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