Mistake on this page?
Report an issue in GitHub or email us
TLSSocket.h
Go to the documentation of this file.
1 /** @file TLSSocket.h TLSSocket */
2 /*
3  * Copyright (c) 2018 ARM Limited
4  * SPDX-License-Identifier: Apache-2.0
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 /** @addtogroup netsocket
19 * @{
20 */
21 
22 #ifndef _MBED_HTTPS_TLS_TCP_SOCKET_H_
23 #define _MBED_HTTPS_TLS_TCP_SOCKET_H_
24 
25 #include "netsocket/TCPSocket.h"
26 
27 #include "mbedtls/platform.h"
28 #include "mbedtls/ssl.h"
29 #include "mbedtls/entropy.h"
30 #include "mbedtls/ctr_drbg.h"
31 #include "mbedtls/error.h"
32 
33 #if !defined(MBED_CONF_NSAPI_OFFLOAD_TLSSOCKET) || !(MBED_CONF_NSAPI_OFFLOAD_TLSSOCKET)
34 
35 // This class requires Mbed TLS SSL/TLS client code
36 #if defined(MBEDTLS_SSL_CLI_C) || defined(DOXYGEN_ONLY)
37 
38 #include "TLSSocketWrapper.h"
39 
40 /**
41  * \brief TLSSocket is a wrapper around TCPSocket for interacting with TLS servers.
42  *
43  * TLSSocket uses the TLSSocketWrapper with internal TCP socket.
44  * This is a helper for creating commonly used TLS connections over TCP.
45  *
46  */
47 class TLSSocket : public TLSSocketWrapper {
48 public:
49  /** Create an uninitialized socket.
50  *
51  * Must call open to initialize the socket on a network stack.
52  */
53  TLSSocket() : TLSSocketWrapper(&tcp_socket) {}
54 
55  /** Destroy the TLSSocket and closes the transport.
56  */
57  virtual ~TLSSocket();
58 
59  /** Opens a socket.
60  *
61  * Creates a network socket on the network stack of the given
62  * network interface.
63  *
64  * @note TLSSocket cannot be reopened after closing. It should be destructed to
65  * clear internal TLS memory structures.
66  *
67  * @param stack Network stack as target for socket.
68  * @return NSAPI_ERROR_OK on success. See @ref TCPSocket::open
69  */
71  {
72  return tcp_socket.open(stack);
73  }
74 
75  template <typename S>
76  nsapi_error_t open(S *stack)
77  {
78  return open(nsapi_create_stack(stack));
79  }
80 
82 
83  /** Connects TCP socket to a remote host.
84  *
85  * Initiates a connection to a remote server specified by either
86  * a domain name or an IP address and port.
87  *
88  * @note: In case connect() returns NSAPI_ERROR_AUTH_FAILURE,
89  * the socket must be freed either by calling close() or destroying it.
90  *
91  * @param host Hostname of the remote host.
92  * @param port Port of the remote host.
93  * @return NSAPI_ERROR_OK on success, negative error code on failure.
94  * See @ref TLSSocketWrapper::connect.
95  */
96  MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
97  nsapi_error_t connect(const char *host, uint16_t port);
98 
99 private:
100  TCPSocket tcp_socket;
101 };
102 #endif // MBEDTLS_SSL_CLI_C
103 
104 #else // MBED_CONF_NSAPI_OFFLOAD_TLSSOCKET
105 
106 class TLSSocket : public TCPSocket {
107 public:
108  TLSSocket();
109  virtual ~TLSSocket();
110 
111  /** Set hostname.
112  *
113  * TLSSocket requires hostname used to verify the certificate.
114  * If hostname is not given in constructor, this function must be used before
115  * starting the TLS handshake.
116  *
117  * @param hostname Hostname of the remote host, used for certificate checking.
118  */
119  nsapi_error_t set_hostname(const char *hostname);
120 
121  /** Sets the certification of Root CA.
122  *
123  * @note Must be called after open() before calling connect()
124  *
125  * @param root_ca Root CA Certificate in any Mbed TLS-supported format.
126  * @param len Length of certificate (including terminating 0 for PEM).
127  * @return NSAPI_ERROR_OK on success, negative error code on failure.
128  */
129  virtual nsapi_error_t set_root_ca_cert(const void *root_ca, size_t len);
130 
131  /** Sets the certification of Root CA.
132  *
133  * @note Must be called after open() before calling connect()
134  *
135  * @param root_ca_pem Root CA Certificate in PEM format.
136  */
137  virtual nsapi_error_t set_root_ca_cert(const char *root_ca_pem);
138 
139 
140  /** Sets client certificate, and client private key.
141  *
142  * @param client_cert Client certification in PEM or DER format.
143  * @param client_cert_len Certificate size including the terminating null byte for PEM data.
144  * @param client_private_key_pem Client private key in PEM or DER format.
145  * @param client_private_key_len Key size including the terminating null byte for PEM data
146  * @return NSAPI_ERROR_OK on success, negative error code on failure.
147  */
148  virtual nsapi_error_t set_client_cert_key(const void *client_cert, size_t client_cert_len,
149  const void *client_private_key_pem, size_t client_private_key_len);
150 
151  /** Sets client certificate, and client private key.
152  *
153  * @param client_cert_pem Client certification in PEM format.
154  * @param client_private_key_pem Client private key in PEM format.
155  * @return NSAPI_ERROR_OK on success, negative error code on failure.
156  */
157  virtual nsapi_error_t set_client_cert_key(const char *client_cert_pem, const char *client_private_key_pem);
158 
159  // From TCPSocket
160  virtual nsapi_error_t connect(const char *host, uint16_t port);
161  virtual nsapi_error_t connect(const SocketAddress &address);
162 
163 protected:
164  virtual nsapi_error_t enable_tlssocket();
165 };
166 
167 #endif // MBED_CONF_NSAPI_OFFLOAD_TLSSOCKET
168 
169 #endif // _MBED_HTTPS_TLS_TCP_SOCKET_H_
170 
171 /** @} */
nsapi_error_t open(NetworkStack *stack)
Open a network socket on the network stack of the given network interface.
NetworkStack * nsapi_create_stack(nsapi_stack_t *stack)
Convert a raw nsapi_stack_t object into a C++ NetworkStack object.
NetworkStack class.
Definition: NetworkStack.h:40
TLSSocket is a wrapper around Socket for interacting with TLS servers.
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
virtual nsapi_error_t connect(const SocketAddress &address=SocketAddress())
Connect the transport socket and start handshake.
virtual ~TLSSocket()
Destroy the TLSSocket and closes the transport.
virtual nsapi_error_t open(NetworkStack *stack)
Opens a socket.
Definition: TLSSocket.h:70
TLSSocket is a wrapper around TCPSocket for interacting with TLS servers.
Definition: TLSSocket.h:47
nsapi_error_t set_root_ca_cert(const void *root_ca, size_t len)
Sets the certification of Root CA.
nsapi_error_t set_client_cert_key(const void *client_cert, size_t client_cert_len, const void *client_private_key_pem, size_t client_private_key_len)
Sets client certificate, and client private key.
SocketAddress class.
Definition: SocketAddress.h:35
TCP socket connection.
Definition: TCPSocket.h:32
TLSSocket()
Create an uninitialized socket.
Definition: TLSSocket.h:53
void set_hostname(const char *hostname)
Set hostname.
TLSSocketWrapper.
TCPSocket class.
nsapi_error_t connect(const char *host, uint16_t port)
Connects TCP socket to a remote host.
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.