FreeRTOS: Secure Sockets
Return to main page ↑
iot_secure_sockets.h
Go to the documentation of this file.
1 /*
2  * FreeRTOS Secure Sockets V1.2.0
3  * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4  *
5  * Permission is hereby granted, free of charge, to any person obtaining a copy of
6  * this software and associated documentation files (the "Software"), to deal in
7  * the Software without restriction, including without limitation the rights to
8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9  * the Software, and to permit persons to whom the Software is furnished to do so,
10  * subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included in all
13  * copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21  *
22  * http://aws.amazon.com/freertos
23  * http://www.FreeRTOS.org
24  */
25 
43 #ifndef _AWS_SECURE_SOCKETS_H_
44 #define _AWS_SECURE_SOCKETS_H_
45 
46 /*
47  #ifdef __cplusplus
48  * extern "C" {
49  #endif
50  */
51 #include <stdint.h>
52 #include <stddef.h>
53 #include "aws_secure_sockets_config.h"
54 #include "iot_secure_sockets_config_defaults.h"
55 #include "iot_secure_sockets_wrapper_metrics.h"
56 #include "iot_lib_init.h"
57 
67 struct xSOCKET;
68 typedef struct xSOCKET * Socket_t;
76 #define Socklen_t uint32_t
77 
90 #define SOCKETS_ERROR_NONE ( 0 )
91 #define SOCKETS_SOCKET_ERROR ( -1 )
92 #define SOCKETS_EWOULDBLOCK ( -11 )
93 #define SOCKETS_ENOMEM ( -12 )
94 #define SOCKETS_EINVAL ( -22 )
95 #define SOCKETS_ENOPROTOOPT ( -109 )
96 #define SOCKETS_ENOTCONN ( -126 )
97 #define SOCKETS_EISCONN ( -127 )
98 #define SOCKETS_ECLOSED ( -128 )
99 #define SOCKETS_TLS_INIT_ERROR ( -1001 )
100 #define SOCKETS_TLS_HANDSHAKE_ERROR ( -1002 )
101 #define SOCKETS_TLS_SERVER_UNVERIFIED ( -1003 )
102 #define SOCKETS_TLS_RECV_ERROR ( -1004 )
103 #define SOCKETS_TLS_SEND_ERROR ( -1005 )
104 #define SOCKETS_PERIPHERAL_RESET ( -1006 )
110 #define SOCKETS_INVALID_SOCKET ( ( Socket_t ) ~0U )
111 
122 #define SOCKETS_AF_INET ( 2 )
123 #define SOCKETS_PF_INET SOCKETS_AF_INET
124 #define SOCKETS_AF_INET6 ( 10 )
137 #define SOCKETS_SOCK_DGRAM ( 2 )
138 #define SOCKETS_SOCK_STREAM ( 1 )
149 #define SOCKETS_IPPROTO_UDP ( 17 )
150 #define SOCKETS_IPPROTO_TCP ( 6 )
161 #define SOCKETS_SO_RCVTIMEO ( 0 )
162 #define SOCKETS_SO_SNDTIMEO ( 1 )
163 #define SOCKETS_SO_SNDBUF ( 4 )
164 #define SOCKETS_SO_RCVBUF ( 5 )
165 #define SOCKETS_SO_SERVER_NAME_INDICATION ( 6 )
166 #define SOCKETS_SO_TRUSTED_SERVER_CERTIFICATE ( 7 )
167 #define SOCKETS_SO_REQUIRE_TLS ( 8 )
168 #define SOCKETS_SO_NONBLOCK ( 9 )
169 #define SOCKETS_SO_ALPN_PROTOCOLS ( 10 )
170 #define SOCKETS_SO_WAKEUP_CALLBACK ( 17 )
181 #define SOCKETS_SHUT_RD ( 0 )
182 #define SOCKETS_SHUT_WR ( 1 )
183 #define SOCKETS_SHUT_RDWR ( 2 )
189 #define securesocketsMAX_DNS_NAME_LENGTH ( 253 )
190 
197 typedef struct SocketsSockaddr
198 {
199  uint8_t ucLength;
200  uint8_t ucSocketDomain;
201  uint16_t usPort;
202  uint32_t ulAddress;
203 } SocketsSockaddr_t;
204 
208 #define securesocketsDEFAULT_TLS_DESTINATION_PORT 443
209 
220 lib_initDECLARE_LIB_INIT( SOCKETS_Init );
221 
247 /*
248  * This call allocates memory and claims a socket resource.
249  */
250 /* @[declare_secure_sockets_socket] */
251 Socket_t SOCKETS_Socket( int32_t lDomain,
252  int32_t lType,
253  int32_t lProtocol );
254 /* @[declare_secure_sockets_socket] */
255 
256 
284 /* @[declare_secure_sockets_connect] */
285 int32_t SOCKETS_Connect( Socket_t xSocket,
286  SocketsSockaddr_t * pxAddress,
287  Socklen_t xAddressLength );
288 /* @[declare_secure_sockets_connect] */
289 
313 /* @[declare_secure_sockets_recv] */
314 int32_t SOCKETS_Recv( Socket_t xSocket,
315  void * pvBuffer,
316  size_t xBufferLength,
317  uint32_t ulFlags );
318 /* @[declare_secure_sockets_recv] */
319 
339 /* @[declare_secure_sockets_send] */
340 int32_t SOCKETS_Send( Socket_t xSocket,
341  const void * pvBuffer,
342  size_t xDataLength,
343  uint32_t ulFlags );
344 /* @[declare_secure_sockets_send] */
345 
368 /* @[declare_secure_sockets_shutdown] */
369 int32_t SOCKETS_Shutdown( Socket_t xSocket,
370  uint32_t ulHow );
371 /* @[declare_secure_sockets_shutdown] */
372 
392 /* @[declare_secure_sockets_close] */
393 int32_t SOCKETS_Close( Socket_t xSocket );
394 /* @[declare_secure_sockets_close] */
395 
399 #define socketsAWS_IOT_ALPN_MQTT "x-amzn-mqtt-ca"
400 
480 /* @[declare_secure_sockets_setsockopt] */
481 int32_t SOCKETS_SetSockOpt( Socket_t xSocket,
482  int32_t lLevel,
483  int32_t lOptionName,
484  const void * pvOptionValue,
485  size_t xOptionLength );
486 /* @[declare_secure_sockets_setsockopt] */
487 
500 /* @[declare_secure_sockets_gethostbyname] */
501 uint32_t SOCKETS_GetHostByName( const char * pcHostName );
502 /* @[declare_secure_sockets_gethostbyname] */
503 
504 
505 
512 #if defined( socketsconfigBYTE_ORDER ) && ( socketsconfigBYTE_ORDER == pdLITTLE_ENDIAN )
513  #define SOCKETS_htonl( ulIn ) ( ( uint32_t ) ( ( ( ulIn & 0xFF ) << 24 ) | ( ( ulIn & 0xFF00 ) << 8 ) | ( ( ulIn & 0xFF0000 ) >> 8 ) | ( ( ulIn & 0xFF000000 ) >> 24 ) ) )
514 #else
515  #define SOCKETS_htonl( usIn ) ( ( uint32_t ) ( usIn ) )
516 #endif
517 
524 #define SOCKETS_ntohl( usIn ) SOCKETS_htonl( usIn )
525 
526 
534 #if defined( socketsconfigBYTE_ORDER ) && ( socketsconfigBYTE_ORDER == pdLITTLE_ENDIAN )
535  #define SOCKETS_htons( usIn ) ( ( uint16_t ) ( ( ( usIn ) << 8U ) | ( ( usIn ) >> 8U ) ) )
536 #else
537  #define SOCKETS_htons( usIn ) ( ( uint16_t ) ( usIn ) )
538 #endif
539 
540 
547 #define SOCKETS_ntohs( usIn ) SOCKETS_htons( usIn )
548 
558 #if defined( socketsconfigBYTE_ORDER ) && ( socketsconfigBYTE_ORDER == pdLITTLE_ENDIAN )
559 
560  #define SOCKETS_inet_addr_quick( ucOctet0, ucOctet1, ucOctet2, ucOctet3 ) \
561  ( ( ( ( uint32_t ) ( ucOctet3 ) ) << 24UL ) | \
562  ( ( ( uint32_t ) ( ucOctet2 ) ) << 16UL ) | \
563  ( ( ( uint32_t ) ( ucOctet1 ) ) << 8UL ) | \
564  ( ( uint32_t ) ( ucOctet0 ) ) )
565 
573  #define SOCKETS_inet_ntoa( ulIPAddress, pucBuffer ) \
574  sprintf( ( char * ) ( pucBuffer ), "%u.%u.%u.%u", \
575  ( ( unsigned ) ( ( ulIPAddress ) & 0xffUL ) ), \
576  ( ( unsigned ) ( ( ( ulIPAddress ) >> 8 ) & 0xffUL ) ), \
577  ( ( unsigned ) ( ( ( ulIPAddress ) >> 16 ) & 0xffUL ) ), \
578  ( ( unsigned ) ( ( ulIPAddress ) >> 24 ) ) )
579 
580 #else /* socketsconfigBYTE_ORDER. */
581 
582  #define SOCKETS_inet_addr_quick( ucOctet0, ucOctet1, ucOctet2, ucOctet3 ) \
583  ( ( ( ( uint32_t ) ( ucOctet0 ) ) << 24UL ) | \
584  ( ( ( uint32_t ) ( ucOctet1 ) ) << 16UL ) | \
585  ( ( ( uint32_t ) ( ucOctet2 ) ) << 8UL ) | \
586  ( ( uint32_t ) ( ucOctet3 ) ) )
587 
595  #define SOCKETS_inet_ntoa( ulIPAddress, pucBuffer ) \
596  sprintf( ( char * ) ( pucBuffer ), "%u.%u.%u.%u", \
597  ( ( unsigned ) ( ( ulIPAddress ) >> 24 ) ), \
598  ( ( unsigned ) ( ( ( ulIPAddress ) >> 16 ) & 0xffUL ) ), \
599  ( ( unsigned ) ( ( ( ulIPAddress ) >> 8 ) & 0xffUL ) ), \
600  ( ( unsigned ) ( ( ulIPAddress ) & 0xffUL ) ) )
601 
602 #endif /* socketsconfigBYTE_ORDER. */
603 
604 /*
605  #ifdef __cplusplus
606  * }
607  #endif
608  */
609 
610 #endif /* _AWS_SECURE_SOCKETS_H_ */
SocketsSockaddr_t
Socket address.
Definition: iot_secure_sockets.h:198
iot_secure_sockets_config_defaults.h
Ensures that the required sockets configuration options are supplied and the optional ones are set to...
SocketsSockaddr_t::ucLength
uint8_t ucLength
Definition: iot_secure_sockets.h:199
SOCKETS_Close
int32_t SOCKETS_Close(Socket_t xSocket)
Closes the socket and frees the related resources.
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.
SocketsSockaddr_t::usPort
uint16_t usPort
Definition: iot_secure_sockets.h:201
SOCKETS_Shutdown
int32_t SOCKETS_Shutdown(Socket_t xSocket, uint32_t ulHow)
Closes all or part of a full-duplex connection on the socket.
lib_initDECLARE_LIB_INIT
lib_initDECLARE_LIB_INIT(SOCKETS_Init)
Secure Sockets library initialization function.
SOCKETS_Socket
Socket_t SOCKETS_Socket(int32_t lDomain, int32_t lType, int32_t lProtocol)
Creates a TCP socket.
Socklen_t
#define Socklen_t
The "size_t" of secure sockets.
Definition: iot_secure_sockets.h:76
Socket_t
struct xSOCKET * Socket_t
Socket handle data type.
Definition: iot_secure_sockets.h:68
SocketsSockaddr_t::ucSocketDomain
uint8_t ucSocketDomain
Definition: iot_secure_sockets.h:200
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.
SOCKETS_GetHostByName
uint32_t SOCKETS_GetHostByName(const char *pcHostName)
Resolve a host name using Domain Name Service.
SOCKETS_Send
int32_t SOCKETS_Send(Socket_t xSocket, const void *pvBuffer, size_t xDataLength, uint32_t ulFlags)
Transmit data to the remote socket.
SocketsSockaddr_t::ulAddress
uint32_t ulAddress
Definition: iot_secure_sockets.h:202
SOCKETS_Recv
int32_t SOCKETS_Recv(Socket_t xSocket, void *pvBuffer, size_t xBufferLength, uint32_t ulFlags)
Receive data from a TCP socket.