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