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  ~TLSSocket() override;
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 private:
84  TCPSocket tcp_socket;
85 };
86 #endif // MBEDTLS_SSL_CLI_C
87 
88 #else // MBED_CONF_NSAPI_OFFLOAD_TLSSOCKET
89 
90 class TLSSocket : public TCPSocket {
91 public:
92  TLSSocket() = default;
93 
94  /** Set hostname.
95  *
96  * TLSSocket requires hostname used to verify the certificate.
97  * If hostname is not given in constructor, this function must be used before
98  * starting the TLS handshake.
99  *
100  * @param hostname Hostname of the remote host, used for certificate checking.
101  */
102  nsapi_error_t set_hostname(const char *hostname);
103 
104  /** Sets the certification of Root CA.
105  *
106  * @note Must be called after open() before calling connect()
107  *
108  * @param root_ca Root CA Certificate in any Mbed TLS-supported format.
109  * @param len Length of certificate (including terminating 0 for PEM).
110  * @return NSAPI_ERROR_OK on success, negative error code on failure.
111  */
112  nsapi_error_t set_root_ca_cert(const void *root_ca, size_t len);
113 
114  /** Sets the certification of Root CA.
115  *
116  * @note Must be called after open() before calling connect()
117  *
118  * @param root_ca_pem Root CA Certificate in PEM format.
119  */
120  nsapi_error_t set_root_ca_cert(const char *root_ca_pem);
121 
122 
123  /** Sets client certificate, and client private key.
124  *
125  * @param client_cert Client certification in PEM or DER format.
126  * @param client_cert_len Certificate size including the terminating null byte for PEM data.
127  * @param client_private_key_pem Client private key in PEM or DER format.
128  * @param client_private_key_len Key size including the terminating null byte for PEM data
129  * @return NSAPI_ERROR_OK on success, negative error code on failure.
130  */
131  nsapi_error_t set_client_cert_key(const void *client_cert, size_t client_cert_len,
132  const void *client_private_key_pem, size_t client_private_key_len);
133 
134  /** Sets client certificate, and client private key.
135  *
136  * @param client_cert_pem Client certification in PEM format.
137  * @param client_private_key_pem Client private key in PEM format.
138  * @return NSAPI_ERROR_OK on success, negative error code on failure.
139  */
140  nsapi_error_t set_client_cert_key(const char *client_cert_pem, const char *client_private_key_pem);
141 
142  // From TCPSocket
143  nsapi_error_t connect(const SocketAddress &address) override;
144 
145 protected:
146  nsapi_error_t enable_tlssocket();
147 };
148 
149 #endif // MBED_CONF_NSAPI_OFFLOAD_TLSSOCKET
150 
151 #endif // _MBED_HTTPS_TLS_TCP_SOCKET_H_
152 
153 /** @} */
nsapi_error_t open(NetworkStack *stack)
Open a network socket on the network stack of the given network interface.
nsapi_error_t open(NetworkStack *stack)
Opens a socket.
Definition: TLSSocket.h:70
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:41
~TLSSocket() override
Destroy the TLSSocket and closes the transport.
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
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:36
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.
nsapi_error_t connect(const SocketAddress &address=SocketAddress()) override
Connect the transport socket and start handshake.
TCPSocket class.
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.