Debian Codegraph @

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

raw
1 ssl_socket_compact
2 =================
3
4 ## Overview
5
6 **ssl_socket_compact** creates and destroys a non-blocking TCP socket suitable for use
7 with SSL implementations that require a TCP socket. The compact (for microcontrollers) implementation of OpenSSL
8 is one example. The socket handling code in `ssl_socket_compact.c` is common to many environments, and
9 preprocessor switches enable the proper headers for a particular environment.
10
11 Socket creation, configuration,binding, and connection are all performed
12 in the `SSL_Socket_Create` call defined in `ssl_socket.h`.
13
14 ## References
15
16 [ssl_socket.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/ssl_socket.h)
17 [sys/socket.h, a typical linux socket implementation](http://pubs.opengroup.org/onlinepubs/7908799/xns/syssocket.h.html)
18
19 ### Exposed API
20
21 **SRS_SSL_SOCKET_COMPACT_30_001: [** The ssl_socket_compact shall use the constants defined in `ssl_socket.h`.
22 ```c
23 #define AZURE_SSL_SOCKET_SO_KEEPALIVE 1 /* enable keepalive */
24 #define AZURE_SSL_SOCKET_TCP_KEEPIDLE 20 /* seconds */
25 #define AZURE_SSL_SOCKET_TCP_KEEPINTVL 2 /* seconds */
26 #define AZURE_SSL_SOCKET_TCP_KEEPCNT 3 /* retry count */
27 ```
28 **]**
29
30 **SRS_SSL_SOCKET_COMPACT_30_001: [** The ssl_socket_compact shall implement the methods defined in `ssl_socket.h`.
31 ```c
32 int SSL_Socket_Create(const char* hostname, int port);
33 void SSL_Socket_Close(int sock);
34 ```
35 **]**
36
37
38 ### SSL_Socket_Create
39 `SSL_Socket_Create` creates a socket and sets its configuration, including setting the socket to non-blocking. It then binds the socket to the supplied `hostname` and `port`, and finally connects the socket to the bound address.
40
41 If successful, it returns a non-negative integer to represent the socket's file descriptor. On failure, it returns -1.
42
43 ```c
44 int SSL_Socket_Create(const char* hostname, int port);
45 ```
46
47 **SRS_SSL_SOCKET_COMPACT_30_002: [** The `hostname` parameter shall be the fully-qualified domain name (FQDN) of the target server. Example: azure-iot-team.azure-devices.net **]**
48
49 **SRS_SSL_SOCKET_COMPACT_30_003: [** The `port` shall be the TCP port number for the target server. **]**
50
51 **SRS_SSL_SOCKET_COMPACT_30_004: [** The `SO_KEEPALIVE` option value of the returned socket shall be `AZURE_SSL_SOCKET_SO_KEEPALIVE`. **]**
52
53 **SRS_SSL_SOCKET_COMPACT_30_005: [** The `TCP_KEEPIDLE` option value of the returned socket shall be `AZURE_SSL_SOCKET_TCP_KEEPIDLE`. **]**
54
55 **SRS_SSL_SOCKET_COMPACT_30_006: [** The `TCP_KEEPINTVL` option value of the returned socket shall be `AZURE_SSL_SOCKET_TCP_KEEPINTVL`. **]**
56
57 **SRS_SSL_SOCKET_COMPACT_30_007: [** The `TCP_KEEPCNT` option value of the returned socket shall be `AZURE_SSL_SOCKET_TCP_KEEPCNT`. **]**
58
59 **SRS_SSL_SOCKET_COMPACT_30_008: [** The returned socket shall be set to `O_NONBLOCK`. **]**
60
61 **SRS_SSL_SOCKET_COMPACT_30_009: [** If the `hostname` cannot be resolved by DNS lookup, `SSL_Socket_Create` shall return -1. **]**
62
63 **SRS_SSL_SOCKET_COMPACT_30_010: [** If socket binding fails, `SSL_Socket_Create` shall return -1. **]**
64
65 **SRS_SSL_SOCKET_COMPACT_30_011: [** If socket connection fails, `SSL_Socket_Create` shall return -1. **]**
66
67
68 ### SSL_Socket_Close
69 `SSL_Socket_Close` calls the underlying socket `close()` on the supplied socket. Parameter validation is deferred to the underlying call, so no validation is performed by `SSL_Socket_Close`.
70
71 ```c
72 void SSL_Socket_Close(int sock);
73 ```
74
75 **SRS_SSL_SOCKET_COMPACT_30_012: [** The `sock` parameter shall be the integer file descriptor of the socket to be closed. **]**
76
77 **SRS_SSL_SOCKET_COMPACT_30_013: [** `SSL_Socket_Close` shall call the underlying `close` method on the supplied socket. **]**