git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-Plus-IoT-SDK/abstractions/secure_sockets/include/iot_secure_sockets.h

   1 /*\r
   2  * Amazon FreeRTOS Secure Sockets V1.1.5\r
   3  * Copyright (C) 2018 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  21  *\r
  22  * http://aws.amazon.com/freertos\r
  23  * http://www.FreeRTOS.org\r
  24  */\r
  25 \r
  26 /**\r
  27  * @file iot_secure_sockets.h\r
  28  * @brief Secure Sockets Interface.\r
  29  *\r
  30  * Secure sockets is a portable layer for establishing a TCP/IP\r
  31  * connection, with the option of using TLS.\r
  32  *\r
  33  * Secure sockets is based on the Berkeley sockets API.\r
  34  * A few difference general differences between Berkeley and SOCKETS are:\r
  35  * - SOCKETS has additional socket options to enable TLS, server name\r
  36  * indication, and per-socket root of trust server certificates.  See\r
  37  * SOCKETS_SetSockOpt() for more information.\r
  38  * - SOCKETS API return an error code, rather than returning -1 and setting\r
  39  * a global errno value.\r
  40  *\r
  41  */\r
  42 \r
  43 #ifndef _AWS_SECURE_SOCKETS_H_\r
  44 #define _AWS_SECURE_SOCKETS_H_\r
  45 \r
  46 /*\r
  47  #ifdef __cplusplus\r
  48  *  extern "C" {\r
  49  #endif\r
  50  */\r
  51 #include <stdint.h>\r
  52 #include <stddef.h>\r
  53 #include "iot_secure_sockets_config.h"\r
  54 #include "iot_secure_sockets_config_defaults.h"\r
  55 #include "iot_secure_sockets_wrapper_metrics.h"\r
  56 #include "iot_lib_init.h"\r
  57 \r
  58 /**\r
  59  * @ingroup SecureSockets_datatypes_handles\r
  60  * @brief The socket handle data type.\r
  61  *\r
  62  * For detail of socket, refer to [Network Sockets]\r
  63  * (https://www.freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/socket.html)\r
  64  *\r
  65  * Data contained by the Socket_t type is port specific.\r
  66  */\r
  67 typedef void * Socket_t;\r
  68 \r
  69 /**\r
  70  * @brief The "size_t" of secure sockets.\r
  71  *\r
  72  * This type is used for compatibility with the expected Berkeley sockets\r
  73  * naming.\r
  74  */\r
  75 #define Socklen_t    uint32_t\r
  76 \r
  77 /**\r
  78  * @anchor SocketsErrors\r
  79  * @name SocketsErrors\r
  80  * @brief Error codes returned by the SOCKETS API.\r
  81  *\r
  82  * Note that SOCKETS API may also propagate port-specific\r
  83  * error codes when they are more descriptive. See your\r
  84  * port's error codes for more details.\r
  85  * PORT_SPECIFIC_LINK\r
  86  */\r
  87 /**@{ */\r
  88 \r
  89 #define SOCKETS_ERROR_NONE               ( 0 )     /*!< No error. */\r
  90 #define SOCKETS_SOCKET_ERROR             ( -1 )    /*!< Catch-all sockets error code. */\r
  91 #define SOCKETS_EWOULDBLOCK              ( -11 )   /*!< A resource is temporarily unavailable. */\r
  92 #define SOCKETS_ENOMEM                   ( -12 )   /*!< Memory allocation failed. */\r
  93 #define SOCKETS_EINVAL                   ( -22 )   /*!< Invalid argument. */\r
  94 #define SOCKETS_ENOPROTOOPT              ( -109 )  /*!< A bad option was specified . */\r
  95 #define SOCKETS_ENOTCONN                 ( -126 )  /*!< The supplied socket is not connected. */\r
  96 #define SOCKETS_EISCONN                  ( -127 )  /*!< The supplied socket is already connected. */\r
  97 #define SOCKETS_ECLOSED                  ( -128 )  /*!< The supplied socket has already been closed. */\r
  98 #define SOCKETS_TLS_INIT_ERROR           ( -1001 ) /*!< TLS initialization failed. */\r
  99 #define SOCKETS_TLS_HANDSHAKE_ERROR      ( -1002 ) /*!< TLS handshake failed. */\r
 100 #define SOCKETS_TLS_SERVER_UNVERIFIED    ( -1003 ) /*!< A connection was made but the server could not be verified.  It is recommended that the socket be closed. */\r
 101 #define SOCKETS_TLS_RECV_ERROR           ( -1004 ) /*!< TLS receive operation failed. */\r
 102 #define SOCKETS_TLS_SEND_ERROR           ( -1005 ) /*!< TLS send operation failed. */\r
 103 #define SOCKETS_PERIPHERAL_RESET         ( -1006 ) /*!< Communications peripheral has been reset. */\r
 104 /**@} */\r
 105 \r
 106 /**\r
 107  * @brief Assigned to an Socket_t variable when the socket is not valid.\r
 108  */\r
 109 #define SOCKETS_INVALID_SOCKET    ( ( Socket_t ) ~0U )\r
 110 \r
 111 /**\r
 112  * @anchor SocketDomains\r
 113  * @name SocketDomains\r
 114  *\r
 115  * @brief Options for the lDomain parameter of SOCKETS_Socket()\r
 116  * function.\r
 117  *\r
 118  * These select the protocol family to be used for communication.\r
 119  */\r
 120 /**@{ */\r
 121 #define SOCKETS_AF_INET     ( 2 )           /*!< IPv4 Internet Protocols. */\r
 122 #define SOCKETS_PF_INET     SOCKETS_AF_INET /*!< IPv4 Internet Protocol. */\r
 123 #define SOCKETS_AF_INET6    ( 10 )          /*!< IPv6 Internet Protocols. This option is currently not supported. */\r
 124 /**@} */\r
 125 \r
 126 /**\r
 127  * @anchor SocketTypes\r
 128  * @name SocketTypes\r
 129  *\r
 130  * @brief Options for the lType parameter of SOCKETS_Socket()\r
 131  * function.\r
 132  *\r
 133  * These specify the communication semantics.\r
 134  */\r
 135 /**@{ */\r
 136 #define SOCKETS_SOCK_DGRAM     ( 2 )    /*!< Datagram. */\r
 137 #define SOCKETS_SOCK_STREAM    ( 1 )    /*!< Byte-stream. */\r
 138 /**@} */\r
 139 \r
 140 /**\r
 141  * @anchor Protocols\r
 142  * @name Protocols\r
 143  *\r
 144  * @brief Options for the lProtocol parameter of SOCKETS_Socket() function.\r
 145  *\r
 146  */\r
 147 /**@{ */\r
 148 #define SOCKETS_IPPROTO_UDP    ( 17 )   /*!< UDP. This option is currently not supported. */\r
 149 #define SOCKETS_IPPROTO_TCP    ( 6 )    /*!< TCP. */\r
 150 /**@} */\r
 151 \r
 152 /**\r
 153  * @anchor SetSockOptOptions\r
 154  * @name SetSockOptOptions\r
 155  *\r
 156  * @brief Options for lOptionName in SOCKETS_SetSockOpt().\r
 157  *\r
 158  */\r
 159 /**@{ */\r
 160 #define SOCKETS_SO_RCVTIMEO                      ( 0 )  /**< Set the receive timeout. */\r
 161 #define SOCKETS_SO_SNDTIMEO                      ( 1 )  /**< Set the send timeout. */\r
 162 #define SOCKETS_SO_SNDBUF                        ( 4 )  /**< Set the size of the send buffer (TCP only). */\r
 163 #define SOCKETS_SO_RCVBUF                        ( 5 )  /**< Set the size of the receive buffer (TCP only). */\r
 164 #define SOCKETS_SO_SERVER_NAME_INDICATION        ( 6 )  /**< Toggle client use of TLS SNI. */\r
 165 #define SOCKETS_SO_TRUSTED_SERVER_CERTIFICATE    ( 7 )  /**< Override default TLS server certificate trust. Must be PEM encoded and length must include null terminator. */\r
 166 #define SOCKETS_SO_REQUIRE_TLS                   ( 8 )  /**< Toggle client enforcement of TLS. */\r
 167 #define SOCKETS_SO_NONBLOCK                      ( 9 )  /**< Socket is nonblocking. */\r
 168 #define SOCKETS_SO_ALPN_PROTOCOLS                ( 10 ) /**< Application protocol list to be included in TLS ClientHello. */\r
 169 #define SOCKETS_SO_WAKEUP_CALLBACK               ( 17 ) /**< Set the callback to be called whenever there is data available on the socket for reading. */\r
 170 \r
 171 /**@} */\r
 172 \r
 173 /**\r
 174  * @anchor ShutdownFlags <br>\r
 175  * @name ShutdownFlags\r
 176  *\r
 177  * @brief Options for the ulHow parameter in SOCKETS_Shutdown().\r
 178  */\r
 179 /**@{ */\r
 180 #define SOCKETS_SHUT_RD      ( 0 )  /**< No further receives. */\r
 181 #define SOCKETS_SHUT_WR      ( 1 )  /**< No further sends. */\r
 182 #define SOCKETS_SHUT_RDWR    ( 2 )  /**< No further send or receive. */\r
 183 /**@} */\r
 184 \r
 185 /**\r
 186  * @brief Maximum length of an ASCII DNS name.\r
 187  */\r
 188 #define securesocketsMAX_DNS_NAME_LENGTH    ( 253 )\r
 189 \r
 190 /**\r
 191  * @ingroup SecureSockets_datatypes_paramstructs\r
 192  * @brief Socket address.\r
 193  *\r
 194  * \sa PORT_SPECIFIC_LINK\r
 195  */\r
 196 typedef struct SocketsSockaddr\r
 197 {\r
 198     uint8_t ucLength;       /**< Length of SocketsSockaddr structure. */\r
 199     uint8_t ucSocketDomain; /**< Only SOCKETS_AF_INET is supported. */\r
 200     uint16_t usPort;        /**< Port number. Convention is to call this sin_port. */\r
 201     uint32_t ulAddress;     /**< IP Address. Convention is to call this sin_addr. */\r
 202 } SocketsSockaddr_t;\r
 203 \r
 204 /**\r
 205  * @brief Well-known port numbers.\r
 206  */\r
 207 #define securesocketsDEFAULT_TLS_DESTINATION_PORT    443\r
 208 \r
 209 /**\r
 210  * @brief Secure Sockets library initialization function.\r
 211  *\r
 212  * This function does general initialization and setup. It must be called once\r
 213  * and only once before calling any other function.\r
 214  *\r
 215  * @return\r
 216  * * `pdPASS` if everything succeeds\r
 217  * * `pdFAIL` otherwise.\r
 218  */\r
 219 lib_initDECLARE_LIB_INIT( SOCKETS_Init );\r
 220 \r
 221 /**\r
 222  * @brief Creates a TCP socket.\r
 223  *\r
 224  * See the [FreeRTOS+TCP networking tutorial]\r
 225  * (https://freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/TCP_Networking_Tutorial.html)\r
 226  * for more information on TCP sockets.\r
 227  *\r
 228  * See the [Berkeley Sockets API]\r
 229  * (https://en.wikipedia.org/wiki/Berkeley_sockets#Socket_API_functions)\r
 230  * in wikipedia\r
 231  *\r
 232  * @sa SOCKETS_Close()\r
 233  *\r
 234  * @param[in] lDomain Must be set to SOCKETS_AF_INET. See @ref SocketDomains.\r
 235  * @param[in] lType Set to SOCKETS_SOCK_STREAM to create a TCP socket.\r
 236  * No other value is valid.  See @ref SocketTypes.\r
 237  * @param[in] lProtocol Set to SOCKETS_IPPROTO_TCP to create a TCP socket.\r
 238  * No other value is valid. See @ref Protocols.\r
 239  *\r
 240  * @return\r
 241  * * If a socket is created successfully, then the socket handle is\r
 242  * returned\r
 243  * * @ref SOCKETS_INVALID_SOCKET is returned if an error occurred.\r
 244  */\r
 245 \r
 246 /*\r
 247  * This call allocates memory and claims a socket resource.\r
 248  */\r
 249 /* @[declare_secure_sockets_socket] */\r
 250 Socket_t SOCKETS_Socket( int32_t lDomain,\r
 251                          int32_t lType,\r
 252                          int32_t lProtocol );\r
 253 /* @[declare_secure_sockets_socket] */\r
 254 \r
 255 \r
 256 /**\r
 257  * @brief Connects the socket to the specified IP address and port.\r
 258  *\r
 259  * The socket must first have been successfully created by a call to SOCKETS_Socket().\r
 260  *\r
 261  * \note To create a secure socket, SOCKETS_SetSockOpt() should be called with the\r
 262  * SOCKETS_SO_REQUIRE_TLS option \a before SOCKETS_Connect() is called.\r
 263  *\r
 264  * If this function returns an error the socket is considered invalid.\r
 265  *\r
 266  * \warning SOCKETS_Connect() is not safe to be called on the same socket\r
 267  * from multiple threads simultaneously with SOCKETS_Connect(),\r
 268  * SOCKETS_SetSockOpt(), SOCKETS_Shutdown(), SOCKETS_Close().\r
 269  *\r
 270  * See the [Berkeley Sockets API]\r
 271  * (https://en.wikipedia.org/wiki/Berkeley_sockets#Socket_API_functions)\r
 272  * in wikipedia\r
 273  *\r
 274  * @param[in] xSocket The handle of the socket to be connected.\r
 275  * @param[in] pxAddress A pointer to a SocketsSockaddr_t structure that contains the\r
 276  * the address to connect the socket to.\r
 277  * @param[in] xAddressLength Should be set to sizeof( @ref SocketsSockaddr_t ).\r
 278  *\r
 279  * @return\r
 280  * * @ref SOCKETS_ERROR_NONE if a connection is established.\r
 281  * * If an error occurred, a negative value is returned. @ref SocketsErrors\r
 282  */\r
 283 /* @[declare_secure_sockets_connect] */\r
 284 int32_t SOCKETS_Connect( Socket_t xSocket,\r
 285                          SocketsSockaddr_t * pxAddress,\r
 286                          Socklen_t xAddressLength );\r
 287 /* @[declare_secure_sockets_connect] */\r
 288 \r
 289 /**\r
 290  * @brief Receive data from a TCP socket.\r
 291  *\r
 292  * The socket must have already been created using a call to SOCKETS_Socket()\r
 293  * and connected to a remote socket using SOCKETS_Connect().\r
 294  *\r
 295  * See the [Berkeley Sockets API]\r
 296  * (https://en.wikipedia.org/wiki/Berkeley_sockets#Socket_API_functions)\r
 297  * in wikipedia\r
 298  *\r
 299  * @param[in] xSocket The handle of the socket from which data is being received.\r
 300  * @param[out] pvBuffer The buffer into which the received data will be placed.\r
 301  * @param[in] xBufferLength The maximum number of bytes which can be received.\r
 302  * pvBuffer must be at least xBufferLength bytes long.\r
 303  * @param[in] ulFlags Not currently used. Should be set to 0.\r
 304  *\r
 305  * @return\r
 306  * * If the receive was successful then the number of bytes received (placed in the\r
 307  *   buffer pointed to by pvBuffer) is returned.\r
 308  * * If a timeout occurred before data could be received then 0 is returned (timeout\r
 309  *   is set using @ref SOCKETS_SO_RCVTIMEO).\r
 310  * * If an error occurred, a negative value is returned. @ref SocketsErrors\r
 311  */\r
 312 /* @[declare_secure_sockets_recv] */\r
 313 int32_t SOCKETS_Recv( Socket_t xSocket,\r
 314                       void * pvBuffer,\r
 315                       size_t xBufferLength,\r
 316                       uint32_t ulFlags );\r
 317 /* @[declare_secure_sockets_recv] */\r
 318 \r
 319 /**\r
 320  * @brief Transmit data to the remote socket.\r
 321  *\r
 322  * The socket must have already been created using a call to SOCKETS_Socket() and\r
 323  * connected to a remote socket using SOCKETS_Connect().\r
 324  *\r
 325  * See the [Berkeley Sockets API]\r
 326  * (https://en.wikipedia.org/wiki/Berkeley_sockets#Socket_API_functions)\r
 327  * in wikipedia\r
 328  *\r
 329  * @param[in] xSocket The handle of the sending socket.\r
 330  * @param[in] pvBuffer The buffer containing the data to be sent.\r
 331  * @param[in] xDataLength The length of the data to be sent.\r
 332  * @param[in] ulFlags Not currently used. Should be set to 0.\r
 333  *\r
 334  * @return\r
 335  * * On success, the number of bytes actually sent is returned.\r
 336  * * If an error occurred, a negative value is returned. @ref SocketsErrors\r
 337  */\r
 338 /* @[declare_secure_sockets_send] */\r
 339 int32_t SOCKETS_Send( Socket_t xSocket,\r
 340                       const void * pvBuffer,\r
 341                       size_t xDataLength,\r
 342                       uint32_t ulFlags );\r
 343 /* @[declare_secure_sockets_send] */\r
 344 \r
 345 /**\r
 346  * @brief Closes all or part of a full-duplex connection on the socket.\r
 347  *\r
 348  * Disable reads and writes on a connected TCP socket. A connected TCP socket must be gracefully\r
 349  * shut down before it can be closed.\r
 350  *\r
 351  * See the [Berkeley Sockets API]\r
 352  * (https://en.wikipedia.org/wiki/Berkeley_sockets#Socket_API_functions)\r
 353  * in wikipedia\r
 354  *\r
 355  * \warning SOCKETS_Shutdown() is not safe to be called on the same socket\r
 356  * from multiple threads simultaneously with SOCKETS_Connect(),\r
 357  * SOCKETS_SetSockOpt(), SOCKETS_Shutdown(), SOCKETS_Close().\r
 358  *\r
 359  * @param[in] xSocket The handle of the socket to shutdown.\r
 360  * @param[in] ulHow SOCKETS_SHUT_RD, SOCKETS_SHUT_WR or SOCKETS_SHUT_RDWR.\r
 361  * @ref ShutdownFlags\r
 362  *\r
 363  * @return\r
 364  * * If the operation was successful, 0 is returned.\r
 365  * * If an error occurred, a negative value is returned. @ref SocketsErrors\r
 366  */\r
 367 /* @[declare_secure_sockets_shutdown] */\r
 368 int32_t SOCKETS_Shutdown( Socket_t xSocket,\r
 369                           uint32_t ulHow );\r
 370 /* @[declare_secure_sockets_shutdown] */\r
 371 \r
 372 /**\r
 373  * @brief Closes the socket and frees the related resources.\r
 374  *\r
 375  * A socket should be shutdown gracefully before it is closed, and cannot be used after it has been closed.\r
 376  *\r
 377  * See the [Berkeley Sockets API]\r
 378  * (https://en.wikipedia.org/wiki/Berkeley_sockets#Socket_API_functions)\r
 379  * in wikipedia\r
 380  *\r
 381  * \warning SOCKETS_Close() is not safe to be called on the same socket\r
 382  * from multiple threads simultaneously with SOCKETS_Connect(),\r
 383  * SOCKETS_SetSockOpt(), SOCKETS_Shutdown(), SOCKETS_Close().\r
 384  *\r
 385  * @param[in] xSocket The handle of the socket to close.\r
 386  *\r
 387  * @return\r
 388  * * On success, 0 is returned.\r
 389  * * If an error occurred, a negative value is returned. @ref SocketsErrors\r
 390  */\r
 391 /* @[declare_secure_sockets_close] */\r
 392 int32_t SOCKETS_Close( Socket_t xSocket );\r
 393 /* @[declare_secure_sockets_close] */\r
 394 \r
 395 /**\r
 396  * @brief AWS IoT ALPN protocol name for MQTT over TLS on server port 443.\r
 397  */\r
 398 #define socketsAWS_IOT_ALPN_MQTT    "x-amzn-mqtt-ca"\r
 399 \r
 400 /**\r
 401  * @brief Manipulates the options for the socket.\r
 402  *\r
 403  * See the [Berkeley Sockets API]\r
 404  * (https://en.wikipedia.org/wiki/Berkeley_sockets#Socket_API_functions)\r
 405  * in wikipedia\r
 406  *\r
 407  * @param[in] xSocket The handle of the socket to set the option for.\r
 408  * @param[in] lLevel Not currently used. Should be set to 0.\r
 409  * @param[in] lOptionName See @ref SetSockOptOptions.\r
 410  * @param[in] pvOptionValue A buffer containing the value of the option to set.\r
 411  * @param[in] xOptionLength The length of the buffer pointed to by pvOptionValue.\r
 412  *\r
 413  * \warning SOCKETS_Close() is not safe to be called on the same socket\r
 414  * from multiple threads simultaneously with SOCKETS_Connect(),\r
 415  * SOCKETS_SetSockOpt(), SOCKETS_Shutdown(), SOCKETS_Close().\r
 416  *\r
 417  * @note Socket option support and possible values vary by port. Please see\r
 418  * PORT_SPECIFIC_LINK to check the valid options and limitations of your device.\r
 419  *\r
 420  *  - Berkeley Socket Options\r
 421  *    - @ref SOCKETS_SO_RCVTIMEO\r
 422  *      - Sets the receive timeout\r
 423  *      - pvOptionValue (TickType_t) is the number of milliseconds that the\r
 424  *      receive function should wait before timing out.\r
 425  *      - Setting pvOptionValue = 0 causes receive to wait forever.\r
 426  *      - See PORT_SPECIFIC_LINK for device limitations.\r
 427  *    - @ref SOCKETS_SO_SNDTIMEO\r
 428  *      - Sets the send timeout\r
 429  *      - pvOptionValue (TickType_t) is the number of milliseconds that the\r
 430  *      send function should wait before timing out.\r
 431  *      - Setting pvOptionValue = 0 causes send to wait forever.\r
 432  *      - See PORT_SPECIFIC_LINK for device limitations.\r
 433  *  - Non-Standard Options\r
 434  *    - @ref SOCKETS_SO_NONBLOCK\r
 435  *      - Makes a socket non-blocking.\r
 436  *      - Non-blocking connect is not supported - socket option should be\r
 437  *        called after connect.\r
 438  *      - pvOptionValue is ignored for this option.\r
 439  *    - @ref SOCKETS_SO_WAKEUP_CALLBACK\r
 440  *      - Set the callback to be called whenever there is data available on\r
 441  *      the socket for reading\r
 442  *      - This option provides an asynchronous way to handle received data\r
 443  *      - pvOptionValue is a pointer to the callback function\r
 444  *      - See PORT_SPECIFIC_LINK for device limitations.\r
 445  *  - Security Sockets Options\r
 446  *    - @ref SOCKETS_SO_REQUIRE_TLS\r
 447  *      - Use TLS for all connect, send, and receive on this socket.\r
 448  *      - This socket options MUST be set for TLS to be used, even\r
 449  *        if other secure socket options are set.\r
 450  *      - This socket option should be set before SOCKETS_Connect() is\r
 451  *        called.\r
 452  *      - pvOptionValue is ignored for this option.\r
 453  *    - @ref SOCKETS_SO_TRUSTED_SERVER_CERTIFICATE\r
 454  *      - Set the root of trust server certificate for the socket.\r
 455  *      - This socket option only takes effect if @ref SOCKETS_SO_REQUIRE_TLS\r
 456  *        is also set.  If @ref SOCKETS_SO_REQUIRE_TLS is not set,\r
 457  *        this option will be ignored.\r
 458  *      - pvOptionValue is a pointer to the formatted server certificate.\r
 459  *        TODO: Link to description of how to format certificates with \n\r
 460  *      - xOptionLength (BaseType_t) is the length of the certificate\r
 461  *        in bytes.\r
 462  *    - @ref SOCKETS_SO_SERVER_NAME_INDICATION\r
 463  *      - Use Server Name Indication (SNI)\r
 464  *      - This socket option only takes effect if @ref SOCKETS_SO_REQUIRE_TLS\r
 465  *        is also set.  If @ref SOCKETS_SO_REQUIRE_TLS is not set,\r
 466  *        this option will be ignored.\r
 467  *      - pvOptionValue is a pointer to a string containing the hostname\r
 468  *      - xOptionLength is the length of the hostname string in bytes.\r
 469  *    - @ref SOCKETS_SO_ALPN_PROTOCOLS\r
 470  *      - Negotiate an application protocol along with TLS.\r
 471  *      - The ALPN list is expressed as an array of NULL-terminated ANSI\r
 472  *        strings.\r
 473  *      - xOptionLength is the number of items in the array.\r
 474  *\r
 475  * @return\r
 476  * * On success, 0 is returned.\r
 477  * * If an error occurred, a negative value is returned. @ref SocketsErrors\r
 478  */\r
 479 /* @[declare_secure_sockets_setsockopt] */\r
 480 int32_t SOCKETS_SetSockOpt( Socket_t xSocket,\r
 481                             int32_t lLevel,\r
 482                             int32_t lOptionName,\r
 483                             const void * pvOptionValue,\r
 484                             size_t xOptionLength );\r
 485 /* @[declare_secure_sockets_setsockopt] */\r
 486 \r
 487 /**\r
 488  * @brief Resolve a host name using Domain Name Service.\r
 489  *\r
 490  * See the [Berkeley Sockets API]\r
 491  * (https://en.wikipedia.org/wiki/Berkeley_sockets#Socket_API_functions)\r
 492  * in wikipedia\r
 493  *\r
 494  * @param[in] pcHostName The host name to resolve.\r
 495  * @return\r
 496  * * The IPv4 address of the specified host.\r
 497  * * If an error has occurred, 0 is returned.\r
 498  */\r
 499 /* @[declare_secure_sockets_gethostbyname] */\r
 500 uint32_t SOCKETS_GetHostByName( const char * pcHostName );\r
 501 /* @[declare_secure_sockets_gethostbyname] */\r
 502 \r
 503 \r
 504 \r
 505 /**\r
 506  * @brief Convert an unsigned thirty-two-bit value from host endianness to network\r
 507  * endianness.\r
 508  *\r
 509  * @param[in] usIn The unsigned thirty-two-bit value to convert.\r
 510  */\r
 511 #if defined( socketsconfigBYTE_ORDER ) && ( socketsconfigBYTE_ORDER == pdLITTLE_ENDIAN )\r
 512     #define SOCKETS_htonl( ulIn )    ( ( uint32_t ) ( ( ( ulIn & 0xFF ) << 24 ) | ( ( ulIn & 0xFF00 ) << 8 ) | ( ( ulIn & 0xFF0000 ) >> 8 ) | ( ( ulIn & 0xFF000000 ) >> 24 ) ) )\r
 513 #else\r
 514     #define SOCKETS_htonl( usIn )    ( ( uint32_t ) ( usIn ) )\r
 515 #endif\r
 516 \r
 517 /**\r
 518  * @brief Convert an unsigned thirty-two-bit value from network endianness to host\r
 519  * endianness.\r
 520  *\r
 521  * @param[in] usIn The unsigned thirty-two-bit value to convert.\r
 522  */\r
 523 #define SOCKETS_ntohl( usIn )    SOCKETS_htonl( usIn )\r
 524 \r
 525 \r
 526 /**\r
 527  * @brief Convert an unsigned sixteen-bit value from host endianness to network\r
 528  * endianness.\r
 529  *\r
 530  * @param[in] usIn The unsigned sixteen-bit value to convert.\r
 531  */\r
 532 \r
 533 #if defined( socketsconfigBYTE_ORDER ) && ( socketsconfigBYTE_ORDER == pdLITTLE_ENDIAN )\r
 534     #define SOCKETS_htons( usIn )    ( ( uint16_t ) ( ( ( usIn ) << 8U ) | ( ( usIn ) >> 8U ) ) )\r
 535 #else\r
 536     #define SOCKETS_htons( usIn )    ( ( uint16_t ) ( usIn ) )\r
 537 #endif\r
 538 \r
 539 \r
 540 /**\r
 541  * @brief Convert an unsigned sixteen-bit value from network endianness to host\r
 542  * endianness.\r
 543  *\r
 544  * @param[in] usIn The unsigned sixteen-bit value to convert.\r
 545  */\r
 546 #define SOCKETS_ntohs( usIn )    SOCKETS_htons( usIn )\r
 547 \r
 548 /**\r
 549  * @brief Convert an IP address expressed as four separate numeric octets into a an IP address expressed as a 32-bit number in network byte order\r
 550  * (for example 192, 168, 0, 100)\r
 551  *\r
 552  * @param[in] ucOctet0 0th IP Octet\r
 553  * @param[in] ucOctet1 1st IP Octet\r
 554  * @param[in] ucOctet2 2nd IP Octet\r
 555  * @param[in] ucOctet3 3rd IP Octet\r
 556  */\r
 557 #if defined( socketsconfigBYTE_ORDER ) && ( socketsconfigBYTE_ORDER == pdLITTLE_ENDIAN )\r
 558 \r
 559     #define SOCKETS_inet_addr_quick( ucOctet0, ucOctet1, ucOctet2, ucOctet3 ) \\r
 560     ( ( ( ( uint32_t ) ( ucOctet3 ) ) << 24UL ) |                             \\r
 561       ( ( ( uint32_t ) ( ucOctet2 ) ) << 16UL ) |                             \\r
 562       ( ( ( uint32_t ) ( ucOctet1 ) ) << 8UL ) |                              \\r
 563       ( ( uint32_t ) ( ucOctet0 ) ) )\r
 564 \r
 565 /**\r
 566  * @brief Convert an IP address expressed as a 32-bit number in network byte order to a string in decimal dot notation.\r
 567  * (for example "192.168.0.100")\r
 568  *\r
 569  * @param[in] ulIPAddress An IP address expressed as a 32-bit value in network byte order.\r
 570  * @param[in] pucBuffer A pointer to a buffer into which the IP address will be written in decimal dot notation.\r
 571  */\r
 572     #define SOCKETS_inet_ntoa( ulIPAddress, pucBuffer )               \\r
 573     sprintf( ( char * ) ( pucBuffer ), "%u.%u.%u.%u",                 \\r
 574              ( ( unsigned ) ( ( ulIPAddress ) & 0xffUL ) ),           \\r
 575              ( ( unsigned ) ( ( ( ulIPAddress ) >> 8 ) & 0xffUL ) ),  \\r
 576              ( ( unsigned ) ( ( ( ulIPAddress ) >> 16 ) & 0xffUL ) ), \\r
 577              ( ( unsigned ) ( ( ulIPAddress ) >> 24 ) ) )\r
 578 \r
 579 #else /* socketsconfigBYTE_ORDER. */\r
 580 \r
 581     #define SOCKETS_inet_addr_quick( ucOctet0, ucOctet1, ucOctet2, ucOctet3 ) \\r
 582     ( ( ( ( uint32_t ) ( ucOctet0 ) ) << 24UL ) |                             \\r
 583       ( ( ( uint32_t ) ( ucOctet1 ) ) << 16UL ) |                             \\r
 584       ( ( ( uint32_t ) ( ucOctet2 ) ) << 8UL ) |                              \\r
 585       ( ( uint32_t ) ( ucOctet3 ) ) )\r
 586 \r
 587 /**\r
 588  * @brief Convert an IP address expressed as a 32-bit number in network byte order to a string in decimal dot notation.\r
 589  * (for example "192.168.0.100")\r
 590  *\r
 591  * @param[in] ulIPAddress An IP address expressed as a 32-bit value in network byte order.\r
 592  * @param[in] pucBuffer A pointer to a buffer into which the IP address will be written in decimal dot notation.\r
 593  */\r
 594     #define SOCKETS_inet_ntoa( ulIPAddress, pucBuffer )               \\r
 595     sprintf( ( char * ) ( pucBuffer ), "%u.%u.%u.%u",                 \\r
 596              ( ( unsigned ) ( ( ulIPAddress ) >> 24 ) ),              \\r
 597              ( ( unsigned ) ( ( ( ulIPAddress ) >> 16 ) & 0xffUL ) ), \\r
 598              ( ( unsigned ) ( ( ( ulIPAddress ) >> 8 ) & 0xffUL ) ),  \\r
 599              ( ( unsigned ) ( ( ulIPAddress ) & 0xffUL ) ) )\r
 600 \r
 601 #endif /* socketsconfigBYTE_ORDER. */\r
 602 \r
 603 /*\r
 604  #ifdef __cplusplus\r
 605  *  }\r
 606  #endif\r
 607  */\r
 608 \r
 609 #endif /* _AWS_SECURE_SOCKETS_H_ */\r