FreeRTOS
Data Structures | Macros | Typedefs | Functions
aws_secure_sockets.h File Reference

Secure Sockets Interface. More...

#include <stdint.h>
#include <stddef.h>
#include "aws_secure_sockets_config.h"
#include "aws_secure_sockets_config_defaults.h"
#include "aws_lib_init.h"

Go to the source code of this file.

Data Structures

struct  SocketsSockaddr
 Socket address. More...
 

Macros

#define Socklen_t   uint32_t
 The "size_t" of secure sockets. More...
 
#define SOCKETS_ERROR_NONE   ( 0 )
 
#define SOCKETS_SOCKET_ERROR   ( -1 )
 
#define SOCKETS_EWOULDBLOCK   ( -11 )
 
#define SOCKETS_ENOMEM   ( -12 )
 
#define SOCKETS_EINVAL   ( -22 )
 
#define SOCKETS_ENOPROTOOPT   ( -109 )
 
#define SOCKETS_ENOTCONN   ( -126 )
 
#define SOCKETS_EISCONN   ( -127 )
 
#define SOCKETS_ECLOSED   ( -128 )
 
#define SOCKETS_TLS_INIT_ERROR   ( -1001 )
 
#define SOCKETS_TLS_HANDSHAKE_ERROR   ( -1002 )
 
#define SOCKETS_TLS_SERVER_UNVERIFIED   ( -1003 )
 
#define SOCKETS_TLS_RECV_ERROR   ( -1004 )
 
#define SOCKETS_TLS_SEND_ERROR   ( -1005 )
 
#define SOCKETS_PERIPHERAL_RESET   ( -1006 )
 
#define SOCKETS_INVALID_SOCKET   ( ( Socket_t ) ~0U )
 Assigned to an Socket_t variable when the socket is not valid.
 
#define SOCKETS_AF_INET   ( 2 )
 
#define SOCKETS_PF_INET   SOCKETS_AF_INET
 
#define SOCKETS_AF_INET6   ( 10 )
 
#define SOCKETS_SOCK_DGRAM   ( 2 )
 
#define SOCKETS_SOCK_STREAM   ( 1 )
 
#define SOCKETS_IPPROTO_UDP   ( 17 )
 
#define SOCKETS_IPPROTO_TCP   ( 6 )
 
#define SOCKETS_SO_RCVTIMEO   ( 0 )
 
#define SOCKETS_SO_SNDTIMEO   ( 1 )
 
#define SOCKETS_SO_SNDBUF   ( 4 )
 
#define SOCKETS_SO_RCVBUF   ( 5 )
 
#define SOCKETS_SO_SERVER_NAME_INDICATION   ( 6 )
 
#define SOCKETS_SO_TRUSTED_SERVER_CERTIFICATE   ( 7 )
 
#define SOCKETS_SO_REQUIRE_TLS   ( 8 )
 
#define SOCKETS_SO_NONBLOCK   ( 9 )
 
#define SOCKETS_SO_ALPN_PROTOCOLS   ( 10 )
 
#define SOCKETS_SO_WAKEUP_CALLBACK   ( 17 )
 
#define SOCKETS_SHUT_RD   ( 0 )
 
#define SOCKETS_SHUT_WR   ( 1 )
 
#define SOCKETS_SHUT_RDWR   ( 2 )
 
#define securesocketsMAX_DNS_NAME_LENGTH   ( 253 )
 Maximum length of an ASCII DNS name.
 
#define securesocketsDEFAULT_TLS_DESTINATION_PORT   443
 Well-known port numbers.
 
#define socketsAWS_IOT_ALPN_MQTT   "x-amzn-mqtt-ca"
 AWS IoT ALPN protocol name for MQTT over TLS on server port 443.
 
#define SOCKETS_htonl(usIn)   ( ( uint32_t ) ( usIn ) )
 Convert an unsigned thirty-two-bit value from host endianness to network endianness. More...
 
#define SOCKETS_ntohl(usIn)   SOCKETS_htonl( usIn )
 Convert an unsigned thirty-two-bit value from network endianness to host endianness. More...
 
#define SOCKETS_htons(usIn)   ( ( uint16_t ) ( usIn ) )
 Convert an unsigned sixteen-bit value from host endianness to network endianness. More...
 
#define SOCKETS_ntohs(usIn)   SOCKETS_htons( usIn )
 Convert an unsigned sixteen-bit value from network endianness to host endianness. More...
 
#define SOCKETS_inet_addr_quick(ucOctet0, ucOctet1, ucOctet2, ucOctet3)
 
#define SOCKETS_inet_ntoa(ulIPAddress, pucBuffer)
 

Typedefs

typedef void * Socket_t
 The socket type. More...
 
typedef struct SocketsSockaddr SocketsSockaddr_t
 Socket address. More...
 

Functions

 lib_initDECLARE_LIB_INIT (SOCKETS_Init)
 Secure Sockets library initialization function. More...
 
Socket_t SOCKETS_Socket (int32_t lDomain, int32_t lType, int32_t lProtocol)
 Creates a TCP socket. More...
 
int32_t SOCKETS_Connect (Socket_t xSocket, SocketsSockaddr_t *pxAddress, Socklen_t xAddressLength)
 Connects the socket to the specified IP address and port. More...
 
int32_t SOCKETS_Recv (Socket_t xSocket, void *pvBuffer, size_t xBufferLength, uint32_t ulFlags)
 Receive data from a TCP socket. More...
 
int32_t SOCKETS_Send (Socket_t xSocket, const void *pvBuffer, size_t xDataLength, uint32_t ulFlags)
 Transmit data to the remote socket. More...
 
int32_t SOCKETS_Shutdown (Socket_t xSocket, uint32_t ulHow)
 Closes all or part of a full-duplex connection on the socket. More...
 
int32_t SOCKETS_Close (Socket_t xSocket)
 Closes the socket and frees the related resources. More...
 
int32_t SOCKETS_SetSockOpt (Socket_t xSocket, int32_t lLevel, int32_t lOptionName, const void *pvOptionValue, size_t xOptionLength)
 Manipulates the options for the socket. More...
 
uint32_t SOCKETS_GetHostByName (const char *pcHostName)
 Resolve a host name using Domain Name Service. More...
 

Detailed Description

Secure Sockets Interface.

Secure sockets is a portable layer for establishing a TCP/IP connection, with the option of using TLS.

Secure sockets is based on the Berkeley sockets API. A few difference general differences between Berkeley and SOCKETS are:

Definition in file aws_secure_sockets.h.

Macro Definition Documentation

◆ SOCKETS_htonl

#define SOCKETS_htonl (   usIn)    ( ( uint32_t ) ( usIn ) )

Convert an unsigned thirty-two-bit value from host endianness to network endianness.

Parameters
[in]usInThe unsigned thirty-two-bit value to convert.

Definition at line 437 of file aws_secure_sockets.h.

◆ SOCKETS_htons

#define SOCKETS_htons (   usIn)    ( ( uint16_t ) ( usIn ) )

Convert an unsigned sixteen-bit value from host endianness to network endianness.

Parameters
[in]usInThe unsigned sixteen-bit value to convert.

Definition at line 459 of file aws_secure_sockets.h.

◆ SOCKETS_inet_addr_quick

#define SOCKETS_inet_addr_quick (   ucOctet0,
  ucOctet1,
  ucOctet2,
  ucOctet3 
)
Value:
( ( ( ( uint32_t ) ( ucOctet0 ) ) << 24UL ) | \
( ( ( uint32_t ) ( ucOctet1 ) ) << 16UL ) | \
( ( ( uint32_t ) ( ucOctet2 ) ) << 8UL ) | \
( ( uint32_t ) ( ucOctet3 ) ) )

Definition at line 488 of file aws_secure_sockets.h.

◆ SOCKETS_inet_ntoa

#define SOCKETS_inet_ntoa (   ulIPAddress,
  pucBuffer 
)
Value:
sprintf( ( char * ) ( pucBuffer ), "%u.%u.%u.%u", \
( ( unsigned ) ( ( ulIPAddress ) >> 24 ) ), \
( ( unsigned ) ( ( ( ulIPAddress ) >> 16 ) & 0xffUL ) ), \
( ( unsigned ) ( ( ( ulIPAddress ) >> 8 ) & 0xffUL ) ), \
( ( unsigned ) ( ( ulIPAddress ) & 0xffUL ) ) )

Definition at line 494 of file aws_secure_sockets.h.

◆ SOCKETS_ntohl

#define SOCKETS_ntohl (   usIn)    SOCKETS_htonl( usIn )

Convert an unsigned thirty-two-bit value from network endianness to host endianness.

Parameters
[in]usInThe unsigned thirty-two-bit value to convert.

Definition at line 446 of file aws_secure_sockets.h.

◆ SOCKETS_ntohs

#define SOCKETS_ntohs (   usIn)    SOCKETS_htons( usIn )

Convert an unsigned sixteen-bit value from network endianness to host endianness.

Parameters
[in]usInThe unsigned sixteen-bit value to convert.

Definition at line 469 of file aws_secure_sockets.h.

◆ Socklen_t

#define Socklen_t   uint32_t

The "size_t" of secure sockets.

This type is used for compatibility with the expected Berkeley sockets naming.

Definition at line 70 of file aws_secure_sockets.h.

Typedef Documentation

◆ Socket_t

typedef void* Socket_t

The socket type.

Data contained by the Socket_t type is port specific.

Definition at line 62 of file aws_secure_sockets.h.

◆ SocketsSockaddr_t

Socket address.

See also
PORT_SPECIFIC_LINK

Function Documentation

◆ lib_initDECLARE_LIB_INIT()

lib_initDECLARE_LIB_INIT ( SOCKETS_Init  )

Secure Sockets library initialization function.

This function does general initialization and setup. It must be called once and only once before calling any other function.

Returns
  • pdPASS if everything succeeds
  • pdFAIL otherwise.

◆ SOCKETS_Close()

int32_t SOCKETS_Close ( Socket_t  xSocket)

Closes the socket and frees the related resources.

Warning
SOCKETS_Close() is not safe to be called on the same socket from multiple threads simultaneously with SOCKETS_Connect(), SOCKETS_SetSockOpt(), SOCKETS_Shutdown(), SOCKETS_Close().
Parameters
[in]xSocketThe handle of the socket to close.
Returns

◆ SOCKETS_Connect()

int32_t SOCKETS_Connect ( Socket_t  xSocket,
SocketsSockaddr_t pxAddress,
Socklen_t  xAddressLength 
)

Connects the socket to the specified IP address and port.

The socket must first have been successfully created by a call to SOCKETS_Socket().

Note
To create a secure socket, SOCKETS_SetSockOpt() should be called with the SOCKETS_SO_REQUIRE_TLS option before SOCKETS_Connect() is called.

If this function returns an error the socket is considered invalid.

Warning
SOCKETS_Connect() is not safe to be called on the same socket from multiple threads simultaneously with SOCKETS_Connect(), SOCKETS_SetSockOpt(), SOCKETS_Shutdown(), SOCKETS_Close().
Parameters
[in]xSocketThe handle of the socket to be connected.
[in]pxAddressA pointer to a SocketsSockaddr_t structure that contains the the address to connect the socket to.
[in]xAddressLengthShould be set to sizeof( SocketsSockaddr_t ).
Returns

◆ SOCKETS_GetHostByName()

uint32_t SOCKETS_GetHostByName ( const char *  pcHostName)

Resolve a host name using Domain Name Service.

Parameters
[in]pcHostNameThe host name to resolve.
Returns
  • The IPv4 address of the specified host.
  • If an error has occured, 0 is returned.

◆ SOCKETS_Recv()

int32_t SOCKETS_Recv ( Socket_t  xSocket,
void *  pvBuffer,
size_t  xBufferLength,
uint32_t  ulFlags 
)

Receive data from a TCP socket.

The socket must have already been created using a call to SOCKETS_Socket() and connected to a remote socket using SOCKETS_Connect().

Parameters
[in]xSocketThe handle of the socket from which data is being received.
[out]pvBufferThe buffer into which the received data will be placed.
[in]xBufferLengthThe maximum number of bytes which can be received. pvBuffer must be at least xBufferLength bytes long.
[in]ulFlagsNot currently used. Should be set to 0.
Returns
  • If the receive was successful then the number of bytes received (placed in the buffer pointed to by pvBuffer) is returned.
  • If a timeout occurred before data could be received then 0 is returned (timeout is set using SOCKETS_SO_RCVTIMEO).
  • If an error occurred, a negative value is returned. Secure Sockets Error Codes

◆ SOCKETS_Send()

int32_t SOCKETS_Send ( Socket_t  xSocket,
const void *  pvBuffer,
size_t  xDataLength,
uint32_t  ulFlags 
)

Transmit data to the remote socket.

The socket must have already been created using a call to SOCKETS_Socket() and connected to a remote socket using SOCKETS_Connect().

Parameters
[in]xSocketThe handle of the sending socket.
[in]pvBufferThe buffer containing the data to be sent.
[in]xDataLengthThe length of the data to be sent.
[in]ulFlagsNot currently used. Should be set to 0.
Returns
  • On success, the number of bytes actually sent is returned.
  • If an error occurred, a negative value is returned. Secure Sockets Error Codes

◆ SOCKETS_SetSockOpt()

int32_t SOCKETS_SetSockOpt ( Socket_t  xSocket,
int32_t  lLevel,
int32_t  lOptionName,
const void *  pvOptionValue,
size_t  xOptionLength 
)

Manipulates the options for the socket.

Parameters
[in]xSocketThe handle of the socket to set the option for.
[in]lLevelNot currently used. Should be set to 0.
[in]lOptionNameSee Secure Socket Options.
[in]pvOptionValueA buffer containing the value of the option to set.
[in]xOptionLengthThe length of the buffer pointed to by pvOptionValue.
Warning
SOCKETS_Close() is not safe to be called on the same socket from multiple threads simultaneously with SOCKETS_Connect(), SOCKETS_SetSockOpt(), SOCKETS_Shutdown(), SOCKETS_Close().
Note
Socket option support and possible values vary by port. Please see PORT_SPECIFIC_LINK to check the valid options and limitations of your device.
  • Berkeley Socket Options
    • SOCKETS_SO_RCVTIMEO
      • Sets the receive timeout
      • pvOptionValue (TickType_t) is the number of milliseconds that the receive function should wait before timing out.
      • Setting pvOptionValue = 0 causes receive to wait forever.
      • See PORT_SPECIFIC_LINK for device limitations.
    • SOCKETS_SO_SNDTIMEO
      • Sets the send timeout
      • pvOptionValue (TickType_t) is the number of milliseconds that the send function should wait before timing out.
      • Setting pvOptionValue = 0 causes send to wait forever.
      • See PORT_SPECIFIC_LINK for device limitations.
  • Non-Standard Options
    • SOCKETS_SO_NONBLOCK
      • Makes a socket non-blocking.
      • Non-blocking connect is not supported - socket option should be called after connect.
      • pvOptionValue is ignored for this option.
  • Security Sockets Options
    • SOCKETS_SO_REQUIRE_TLS
      • Use TLS for all connect, send, and receive on this socket.
      • This socket options MUST be set for TLS to be used, even if other secure socket options are set.
      • This socket option should be set before SOCKETS_Connect() is called.
      • pvOptionValue is ignored for this option.
    • SOCKETS_SO_TRUSTED_SERVER_CERTIFICATE
      • Set the root of trust server certificate for the socket.
      • This socket option only takes effect if SOCKETS_SO_REQUIRE_TLS is also set. If SOCKETS_SO_REQUIRE_TLS is not set, this option will be ignored.
      • pvOptionValue is a pointer to the formatted server certificate. TODO: Link to description of how to format certificates with
      • xOptionLength (BaseType_t) is the length of the certificate in bytes.
    • SOCKETS_SO_SERVER_NAME_INDICATION
      • Use Server Name Indication (SNI)
      • This socket option only takes effect if SOCKETS_SO_REQUIRE_TLS is also set. If SOCKETS_SO_REQUIRE_TLS is not set, this option will be ignored.
      • pvOptionValue is a pointer to a string containing the hostname
      • xOptionLength is the length of the hostname string in bytes.
    • SOCKETS_SO_ALPN_PROTOCOLS
      • Negotiate an application protocol along with TLS.
      • The ALPN list is expressed as an array of NULL-terminated ANSI strings.
      • xOptionLength is the number of items in the array.
Returns

◆ SOCKETS_Shutdown()

int32_t SOCKETS_Shutdown ( Socket_t  xSocket,
uint32_t  ulHow 
)

Closes all or part of a full-duplex connection on the socket.

Warning
SOCKETS_Shutdown() is not safe to be called on the same socket from multiple threads simultaneously with SOCKETS_Connect(), SOCKETS_SetSockOpt(), SOCKETS_Shutdown(), SOCKETS_Close().
Parameters
[in]xSocketThe handle of the socket to shutdown.
[in]ulHowSOCKETS_SHUT_RD, SOCKETS_SHUT_WR or SOCKETS_SHUT_RDWR. Secure Sockets Shutdown Flags
Returns

◆ SOCKETS_Socket()

Socket_t SOCKETS_Socket ( int32_t  lDomain,
int32_t  lType,
int32_t  lProtocol 
)

Creates a TCP socket.

This call allocates memory and claims a socket resource.

See also
SOCKETS_Close()
Parameters
[in]lDomainMust be set to SOCKETS_AF_INET. See Secure Socket Domains.
[in]lTypeSet to SOCKETS_SOCK_STREAM to create a TCP socket. No other value is valid. See Secure Socket Types.
[in]lProtocolSet to SOCKETS_IPPROTO_TCP to create a TCP socket. No other value is valid. See Secure Socket Protocols.
Returns
  • If a socket is created successfully, then the socket handle is returned
  • SOCKETS_INVALID_SOCKET is returned if an error occurred.