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, negative error code on failure.
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  */
95  nsapi_error_t connect(const char *host, uint16_t port);
96 
97 private:
98  TCPSocket tcp_socket;
99 };
100 #endif // MBEDTLS_SSL_CLI_C
101 
102 #else // MBED_CONF_NSAPI_OFFLOAD_TLSSOCKET
103 
104 class TLSSocket : public TCPSocket {
105 public:
106  TLSSocket();
107  virtual ~TLSSocket();
108 
109  /** Set hostname.
110  *
111  * TLSSocket requires hostname used to verify the certificate.
112  * If hostname is not given in constructor, this function must be used before
113  * starting the TLS handshake.
114  *
115  * @param hostname Hostname of the remote host, used for certificate checking.
116  */
117  nsapi_error_t set_hostname(const char *hostname);
118 
119  /** Sets the certification of Root CA.
120  *
121  * @note Must be called after open() before calling connect()
122  *
123  * @param root_ca Root CA Certificate in any Mbed TLS-supported format.
124  * @param len Length of certificate (including terminating 0 for PEM).
125  * @return NSAPI_ERROR_OK on success, negative error code on failure.
126  */
127  virtual nsapi_error_t set_root_ca_cert(const void *root_ca, size_t len);
128 
129  /** Sets the certification of Root CA.
130  *
131  * @note Must be called after open() before calling connect()
132  *
133  * @param root_ca_pem Root CA Certificate in PEM format.
134  */
135  virtual nsapi_error_t set_root_ca_cert(const char *root_ca_pem);
136 
137 
138  /** Sets client certificate, and client private key.
139  *
140  * @param client_cert Client certification in PEM or DER format.
141  * @param client_cert_len Certificate size including the terminating null byte for PEM data.
142  * @param client_private_key_pem Client private key in PEM or DER format.
143  * @param client_private_key_len Key size including the terminating null byte for PEM data
144  * @return NSAPI_ERROR_OK on success, negative error code on failure.
145  */
146  virtual nsapi_error_t set_client_cert_key(const void *client_cert, size_t client_cert_len,
147  const void *client_private_key_pem, size_t client_private_key_len);
148 
149  /** Sets client certificate, and client private key.
150  *
151  * @param client_cert_pem Client certification in PEM format.
152  * @param client_private_key_pem Client private key in PEM format.
153  * @return NSAPI_ERROR_OK on success, negative error code on failure.
154  */
155  virtual nsapi_error_t set_client_cert_key(const char *client_cert_pem, const char *client_private_key_pem);
156 
157  // From TCPSocket
158  virtual nsapi_error_t connect(const char *host, uint16_t port);
159  virtual nsapi_error_t connect(const SocketAddress &address);
160 
161 protected:
162  virtual nsapi_error_t enable_tlssocket();
163 };
164 
165 #endif // MBED_CONF_NSAPI_OFFLOAD_TLSSOCKET
166 
167 #endif // _MBED_HTTPS_TLS_TCP_SOCKET_H_
168 
169 /** @} */
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())
Connects socket to a remote address.
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.
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.