1 /* 2 * FreeRTOS V202212.00 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 * https://www.FreeRTOS.org 23 * https://github.com/FreeRTOS 24 * 25 */ 26 27 /** 28 * @file using_wolfSSL.h 29 * @brief TLS transport interface header. 30 */ 31 32 #ifndef USING_WOLFSSL_H 33 #define USING_WOLFSSL_H 34 35 /**************************************************/ 36 /******* DO NOT CHANGE the following order ********/ 37 /**************************************************/ 38 39 /* Logging related header files are required to be included in the following order: 40 * 1. Include the header file "logging_levels.h". 41 * 2. Define LIBRARY_LOG_NAME and LIBRARY_LOG_LEVEL. 42 * 3. Include the header file "logging_stack.h". 43 */ 44 45 /* Include header that defines log levels. */ 46 #include "logging_levels.h" 47 48 /* Logging configuration for the Sockets. */ 49 #ifndef LIBRARY_LOG_NAME 50 #define LIBRARY_LOG_NAME "TlsTransport" 51 #endif 52 #ifndef LIBRARY_LOG_LEVEL 53 #define LIBRARY_LOG_LEVEL LOG_INFO 54 #endif 55 56 #include "logging_stack.h" 57 58 /************ End of logging configuration ****************/ 59 60 /* FreeRTOS+TCP include. */ 61 #include "FreeRTOS_Sockets.h" 62 63 /* Transport interface include. */ 64 #include "transport_interface.h" 65 66 /* wolfSSL interface include. */ 67 #include "wolfssl/ssl.h" 68 69 /** 70 * @brief Secured connection context. 71 */ 72 typedef struct SSLContext 73 { 74 WOLFSSL_CTX * ctx; /**< @brief wolfSSL context */ 75 WOLFSSL * ssl; /**< @brief wolfSSL ssl session context */ 76 } SSLContext_t; 77 78 /** 79 * @brief Definition of the network context for the transport interface 80 * implementation that uses mbedTLS and FreeRTOS+TLS sockets. 81 */ 82 struct NetworkContext 83 { 84 Socket_t tcpSocket; 85 SSLContext_t sslContext; 86 }; 87 88 /** 89 * @brief Contains the credentials necessary for tls connection setup. 90 */ 91 typedef struct NetworkCredentials 92 { 93 /** 94 * @brief Set this to a non-NULL value to use ALPN. 95 * 96 * This string must be NULL-terminated. 97 * 98 * See [this link] 99 * (https://aws.amazon.com/blogs/iot/mqtt-with-tls-client-authentication-on-port-443-why-it-is-useful-and-how-it-works/) 100 * for more information. 101 */ 102 const char * pAlpnProtos; 103 104 /** 105 * @brief Disable server name indication (SNI) for a TLS session. 106 */ 107 BaseType_t disableSni; 108 109 const unsigned char * pRootCa; /**< @brief String representing a trusted server root certificate. */ 110 size_t rootCaSize; /**< @brief Size associated with #IotNetworkCredentials.pRootCa. */ 111 const unsigned char * pClientCert; /**< @brief String representing the client certificate. */ 112 size_t clientCertSize; /**< @brief Size associated with #IotNetworkCredentials.pClientCert. */ 113 const unsigned char * pPrivateKey; /**< @brief String representing the client certificate's private key. */ 114 size_t privateKeySize; /**< @brief Size associated with #IotNetworkCredentials.pPrivateKey. */ 115 const unsigned char * pUserName; /**< @brief String representing the username for MQTT. */ 116 size_t userNameSize; /**< @brief Size associated with #IotNetworkCredentials.pUserName. */ 117 const unsigned char * pPassword; /**< @brief String representing the password for MQTT. */ 118 size_t passwordSize; /**< @brief Size associated with #IotNetworkCredentials.pPassword. */ 119 } NetworkCredentials_t; 120 121 /** 122 * @brief TLS Connect / Disconnect return status. 123 */ 124 typedef enum TlsTransportStatus 125 { 126 TLS_TRANSPORT_SUCCESS = 0, /**< Function successfully completed. */ 127 TLS_TRANSPORT_INVALID_PARAMETER, /**< At least one parameter was invalid. */ 128 TLS_TRANSPORT_INSUFFICIENT_MEMORY, /**< Insufficient memory required to establish connection. */ 129 TLS_TRANSPORT_INVALID_CREDENTIALS, /**< Provided credentials were invalid. */ 130 TLS_TRANSPORT_HANDSHAKE_FAILED, /**< Performing TLS handshake with server failed. */ 131 TLS_TRANSPORT_INTERNAL_ERROR, /**< A call to a system API resulted in an internal error. */ 132 TLS_TRANSPORT_CONNECT_FAILURE /**< Initial connection to the server failed. */ 133 } TlsTransportStatus_t; 134 135 /** 136 * @brief Create a TLS connection with FreeRTOS sockets. 137 * 138 * @param[out] pNetworkContext Pointer to a network context to contain the 139 * initialized socket handle. 140 * @param[in] pHostName The hostname of the remote endpoint. 141 * @param[in] port The destination port. 142 * @param[in] pNetworkCredentials Credentials for the TLS connection. 143 * @param[in] receiveTimeoutMs Receive socket timeout. 144 * @param[in] sendTimeoutMs Send socket timeout. 145 * 146 * @return #TLS_TRANSPORT_SUCCESS, #TLS_TRANSPORT_INSUFFICIENT_MEMORY, #TLS_TRANSPORT_INVALID_CREDENTIALS, 147 * #TLS_TRANSPORT_HANDSHAKE_FAILED, #TLS_TRANSPORT_INTERNAL_ERROR, or #TLS_TRANSPORT_CONNECT_FAILURE. 148 */ 149 TlsTransportStatus_t TLS_FreeRTOS_Connect( NetworkContext_t * pNetworkContext, 150 const char * pHostName, 151 uint16_t port, 152 const NetworkCredentials_t * pNetworkCredentials, 153 uint32_t receiveTimeoutMs, 154 uint32_t sendTimeoutMs ); 155 156 /** 157 * @brief Gracefully disconnect an established TLS connection. 158 * 159 * @param[in] pNetworkContext Network context. 160 */ 161 void TLS_FreeRTOS_Disconnect( NetworkContext_t * pNetworkContext ); 162 163 /** 164 * @brief Receives data from an established TLS connection. 165 * 166 * This is the TLS version of the transport interface's 167 * #TransportRecv_t function. 168 * 169 * @param[in] pNetworkContext The Network context. 170 * @param[out] pBuffer Buffer to receive bytes into. 171 * @param[in] bytesToRecv Number of bytes to receive from the network. 172 * 173 * @return Number of bytes (> 0) received if successful; 174 * 0 if the socket times out without reading any bytes; 175 * negative value on error. 176 */ 177 int32_t TLS_FreeRTOS_recv( NetworkContext_t * pNetworkContext, 178 void * pBuffer, 179 size_t bytesToRecv ); 180 181 /** 182 * @brief Sends data over an established TLS connection. 183 * 184 * This is the TLS version of the transport interface's 185 * #TransportSend_t function. 186 * 187 * @param[in] pNetworkContext The network context. 188 * @param[in] pBuffer Buffer containing the bytes to send. 189 * @param[in] bytesToSend Number of bytes to send from the buffer. 190 * 191 * @return Number of bytes (> 0) sent on success; 192 * 0 if the socket times out without sending any bytes; 193 * else a negative value to represent error. 194 */ 195 int32_t TLS_FreeRTOS_send( NetworkContext_t * pNetworkContext, 196 const void * pBuffer, 197 size_t bytesToSend ); 198 199 #endif /* ifndef USING_WOLFSSL_H */ 200