1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
/*
* FreeRTOS V202107.00
* Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of
* this software and associated documentation files (the "Software"), to deal in
* the Software without restriction, including without limitation the rights to
* use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
* the Software, and to permit persons to whom the Software is furnished to do so,
* subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
* IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*
* https://www.FreeRTOS.org
* https://github.com/FreeRTOS
*
*/
/**
* @file using_wolfSSL.h
* @brief TLS transport interface header.
*/
#ifndef USING_WOLFSSL_H
#define USING_WOLFSSL_H
/**************************************************/
/******* DO NOT CHANGE the following order ********/
/**************************************************/
/* Logging related header files are required to be included in the following order:
* 1. Include the header file "logging_levels.h".
* 2. Define LIBRARY_LOG_NAME and LIBRARY_LOG_LEVEL.
* 3. Include the header file "logging_stack.h".
*/
/* Include header that defines log levels. */
#include "logging_levels.h"
/* Logging configuration for the Sockets. */
#ifndef LIBRARY_LOG_NAME
#define LIBRARY_LOG_NAME "TlsTransport"
#endif
#ifndef LIBRARY_LOG_LEVEL
#define LIBRARY_LOG_LEVEL LOG_INFO
#endif
#include "logging_stack.h"
/************ End of logging configuration ****************/
/* FreeRTOS+TCP include. */
#include "FreeRTOS_Sockets.h"
/* Transport interface include. */
#include "transport_interface.h"
/* wolfSSL interface include. */
#include "wolfssl/ssl.h"
/**
* @brief Secured connection context.
*/
typedef struct SSLContext
{
WOLFSSL_CTX* ctx; /**< @brief wolfSSL context */
WOLFSSL* ssl; /**< @brief wolfSSL ssl session context */
} SSLContext_t;
/**
* @brief Definition of the network context for the transport interface
* implementation that uses mbedTLS and FreeRTOS+TLS sockets.
*/
struct NetworkContext
{
Socket_t tcpSocket;
SSLContext_t sslContext;
};
/**
* @brief Contains the credentials necessary for tls connection setup.
*/
typedef struct NetworkCredentials
{
/**
* @brief Set this to a non-NULL value to use ALPN.
*
* This string must be NULL-terminated.
*
* See [this link]
* (https://aws.amazon.com/blogs/iot/mqtt-with-tls-client-authentication-on-port-443-why-it-is-useful-and-how-it-works/)
* for more information.
*/
const char * pAlpnProtos;
/**
* @brief Disable server name indication (SNI) for a TLS session.
*/
BaseType_t disableSni;
const unsigned char * pRootCa; /**< @brief String representing a trusted server root certificate. */
size_t rootCaSize; /**< @brief Size associated with #IotNetworkCredentials.pRootCa. */
const unsigned char * pClientCert; /**< @brief String representing the client certificate. */
size_t clientCertSize; /**< @brief Size associated with #IotNetworkCredentials.pClientCert. */
const unsigned char * pPrivateKey; /**< @brief String representing the client certificate's private key. */
size_t privateKeySize; /**< @brief Size associated with #IotNetworkCredentials.pPrivateKey. */
const unsigned char * pUserName; /**< @brief String representing the username for MQTT. */
size_t userNameSize; /**< @brief Size associated with #IotNetworkCredentials.pUserName. */
const unsigned char * pPassword; /**< @brief String representing the password for MQTT. */
size_t passwordSize; /**< @brief Size associated with #IotNetworkCredentials.pPassword. */
} NetworkCredentials_t;
/**
* @brief TLS Connect / Disconnect return status.
*/
typedef enum TlsTransportStatus
{
TLS_TRANSPORT_SUCCESS = 0, /**< Function successfully completed. */
TLS_TRANSPORT_INVALID_PARAMETER, /**< At least one parameter was invalid. */
TLS_TRANSPORT_INSUFFICIENT_MEMORY, /**< Insufficient memory required to establish connection. */
TLS_TRANSPORT_INVALID_CREDENTIALS, /**< Provided credentials were invalid. */
TLS_TRANSPORT_HANDSHAKE_FAILED, /**< Performing TLS handshake with server failed. */
TLS_TRANSPORT_INTERNAL_ERROR, /**< A call to a system API resulted in an internal error. */
TLS_TRANSPORT_CONNECT_FAILURE /**< Initial connection to the server failed. */
} TlsTransportStatus_t;
/**
* @brief Create a TLS connection with FreeRTOS sockets.
*
* @param[out] pNetworkContext Pointer to a network context to contain the
* initialized socket handle.
* @param[in] pHostName The hostname of the remote endpoint.
* @param[in] port The destination port.
* @param[in] pNetworkCredentials Credentials for the TLS connection.
* @param[in] receiveTimeoutMs Receive socket timeout.
* @param[in] sendTimeoutMs Send socket timeout.
*
* @return #TLS_TRANSPORT_SUCCESS, #TLS_TRANSPORT_INSUFFICIENT_MEMORY, #TLS_TRANSPORT_INVALID_CREDENTIALS,
* #TLS_TRANSPORT_HANDSHAKE_FAILED, #TLS_TRANSPORT_INTERNAL_ERROR, or #TLS_TRANSPORT_CONNECT_FAILURE.
*/
TlsTransportStatus_t TLS_FreeRTOS_Connect( NetworkContext_t * pNetworkContext,
const char * pHostName,
uint16_t port,
const NetworkCredentials_t * pNetworkCredentials,
uint32_t receiveTimeoutMs,
uint32_t sendTimeoutMs );
/**
* @brief Gracefully disconnect an established TLS connection.
*
* @param[in] pNetworkContext Network context.
*/
void TLS_FreeRTOS_Disconnect( NetworkContext_t * pNetworkContext );
/**
* @brief Receives data from an established TLS connection.
*
* This is the TLS version of the transport interface's
* #TransportRecv_t function.
*
* @param[in] pNetworkContext The Network context.
* @param[out] pBuffer Buffer to receive bytes into.
* @param[in] bytesToRecv Number of bytes to receive from the network.
*
* @return Number of bytes (> 0) received if successful;
* 0 if the socket times out without reading any bytes;
* negative value on error.
*/
int32_t TLS_FreeRTOS_recv( NetworkContext_t * pNetworkContext,
void * pBuffer,
size_t bytesToRecv );
/**
* @brief Sends data over an established TLS connection.
*
* This is the TLS version of the transport interface's
* #TransportSend_t function.
*
* @param[in] pNetworkContext The network context.
* @param[in] pBuffer Buffer containing the bytes to send.
* @param[in] bytesToSend Number of bytes to send from the buffer.
*
* @return Number of bytes (> 0) sent on success;
* 0 if the socket times out without sending any bytes;
* else a negative value to represent error.
*/
int32_t TLS_FreeRTOS_send( NetworkContext_t * pNetworkContext,
const void * pBuffer,
size_t bytesToSend );
#endif /* ifndef USING_WOLFSSL_H */
|
