ssl_socket_compact
=================

## Overview

**ssl_socket_compact** creates and destroys a non-blocking TCP socket suitable for use
with SSL implementations that require a TCP socket. The compact (for microcontrollers) implementation of OpenSSL
is one example. The socket handling code in `ssl_socket_compact.c` is common to many environments, and
preprocessor switches enable the proper headers for a particular environment.

Socket creation, configuration,binding, and connection are all performed
in the `SSL_Socket_Create` call defined in `ssl_socket.h`.

## References

[ssl_socket.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/ssl_socket.h)  
[sys/socket.h, a typical linux socket implementation](http://pubs.opengroup.org/onlinepubs/7908799/xns/syssocket.h.html)

###   Exposed API

**SRS_SSL_SOCKET_COMPACT_30_001: [** The ssl_socket_compact shall use the constants defined in `ssl_socket.h`.
```c
#define AZURE_SSL_SOCKET_SO_KEEPALIVE 1    /* enable keepalive */
#define AZURE_SSL_SOCKET_TCP_KEEPIDLE 20   /* seconds */
#define AZURE_SSL_SOCKET_TCP_KEEPINTVL 2   /* seconds */
#define AZURE_SSL_SOCKET_TCP_KEEPCNT 3     /* retry count */
```
 **]**

**SRS_SSL_SOCKET_COMPACT_30_001: [** The ssl_socket_compact shall implement the methods defined in `ssl_socket.h`.
```c
int SSL_Socket_Create(const char* hostname, int port);
void SSL_Socket_Close(int sock);
```
 **]**


###   SSL_Socket_Create
`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.

If successful, it returns a non-negative integer to represent the socket's file descriptor. On failure, it returns -1.

```c
int SSL_Socket_Create(const char* hostname, int port);
```

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

**SRS_SSL_SOCKET_COMPACT_30_003: [** The `port` shall be the TCP port number for the target server. **]**

**SRS_SSL_SOCKET_COMPACT_30_004: [** The `SO_KEEPALIVE` option value of the returned socket shall be `AZURE_SSL_SOCKET_SO_KEEPALIVE`. **]**

**SRS_SSL_SOCKET_COMPACT_30_005: [** The `TCP_KEEPIDLE` option value of the returned socket shall be `AZURE_SSL_SOCKET_TCP_KEEPIDLE`. **]**

**SRS_SSL_SOCKET_COMPACT_30_006: [** The `TCP_KEEPINTVL` option value of the returned socket shall be `AZURE_SSL_SOCKET_TCP_KEEPINTVL`. **]**

**SRS_SSL_SOCKET_COMPACT_30_007: [** The `TCP_KEEPCNT` option value of the returned socket shall be `AZURE_SSL_SOCKET_TCP_KEEPCNT`. **]**

**SRS_SSL_SOCKET_COMPACT_30_008: [** The returned socket shall be set to `O_NONBLOCK`. **]**

**SRS_SSL_SOCKET_COMPACT_30_009: [** If the `hostname` cannot be resolved by DNS lookup, `SSL_Socket_Create` shall return -1. **]**

**SRS_SSL_SOCKET_COMPACT_30_010: [** If socket binding fails, `SSL_Socket_Create` shall return -1. **]**

**SRS_SSL_SOCKET_COMPACT_30_011: [** If socket connection fails, `SSL_Socket_Create` shall return -1. **]**


 ###   SSL_Socket_Close
 `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`.

 ```c
 void SSL_Socket_Close(int sock);
 ```

  **SRS_SSL_SOCKET_COMPACT_30_012: [** The `sock` parameter shall be the integer file descriptor of the socket to be closed. **]**  
  
 **SRS_SSL_SOCKET_COMPACT_30_013: [** `SSL_Socket_Close` shall call the underlying `close` method on the supplied socket. **]**