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"

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:

SOCKETS has additional socket options to enable TLS, server name indication, and per-socket root of trust server certificates. See SOCKETS_SetSockOpt() for more information.
SOCKETS API return an error code, rather than returning -1 and setting a global errno value.

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] usIn The 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] usIn The 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] usIn The 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] usIn The 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

typedef struct SocketsSockaddr 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] xSocket The handle of the socket to close.

Returns

On success, 0 is returned.
If an error occurred, a negative value is returned. Secure Sockets Error Codes

◆ 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]	xSocket	The handle of the socket to be connected.
[in]	pxAddress	A pointer to a SocketsSockaddr_t structure that contains the the address to connect the socket to.
[in]	xAddressLength	Should be set to sizeof( SocketsSockaddr_t ).

Returns

SOCKETS_ERROR_NONE if a connection is established.
If an error occurred, a negative value is returned. Secure Sockets Error Codes

◆ SOCKETS_GetHostByName()

uint32_t SOCKETS_GetHostByName ( const char * pcHostName )

Resolve a host name using Domain Name Service.

Parameters

[in] pcHostName The 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]	xSocket	The handle of the socket from which data is being received.
[out]	pvBuffer	The buffer into which the received data will be placed.
[in]	xBufferLength	The maximum number of bytes which can be received. pvBuffer must be at least xBufferLength bytes long.
[in]	ulFlags	Not 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]	xSocket	The handle of the sending socket.
[in]	pvBuffer	The buffer containing the data to be sent.
[in]	xDataLength	The length of the data to be sent.
[in]	ulFlags	Not 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]	xSocket	The handle of the socket to set the option for.
[in]	lLevel	Not currently used. Should be set to 0.
[in]	lOptionName	See Secure Socket Options.
[in]	pvOptionValue	A buffer containing the value of the option to set.
[in]	xOptionLength	The 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

On success, 0 is returned.
If an error occured, a negative value is returned. Secure Sockets Error Codes

◆ 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]	xSocket	The handle of the socket to shutdown.
[in]	ulHow	SOCKETS_SHUT_RD, SOCKETS_SHUT_WR or SOCKETS_SHUT_RDWR. Secure Sockets Shutdown Flags

Returns

If the operation was successful, 0 is returned.
If an error occurred, a negative value is returned. Secure Sockets Error Codes

◆ 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]	lDomain	Must be set to SOCKETS_AF_INET. See Secure Socket Domains.
[in]	lType	Set to SOCKETS_SOCK_STREAM to create a TCP socket. No other value is valid. See Secure Socket Types.
[in]	lProtocol	Set 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.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SOCKETS_htonl

◆ SOCKETS_htons

◆ SOCKETS_inet_addr_quick

◆ SOCKETS_inet_ntoa

◆ SOCKETS_ntohl

◆ SOCKETS_ntohs

◆ Socklen_t

Typedef Documentation

◆ Socket_t

◆ SocketsSockaddr_t

Function Documentation

◆ lib_initDECLARE_LIB_INIT()

◆ SOCKETS_Close()

◆ SOCKETS_Connect()

◆ SOCKETS_GetHostByName()

◆ SOCKETS_Recv()

◆ SOCKETS_Send()

◆ SOCKETS_SetSockOpt()

◆ SOCKETS_Shutdown()

◆ SOCKETS_Socket()