TLSSocket.h

00001 /** @file TLSSocket.h TLSSocket */
00002 /*
00003  * Copyright (c) 2018 ARM Limited
00004  * SPDX-License-Identifier: Apache-2.0
00005  *
00006  * Licensed under the Apache License, Version 2.0 (the "License");
00007  * you may not use this file except in compliance with the License.
00008  * You may obtain a copy of the License at
00009  *
00010  *     http://www.apache.org/licenses/LICENSE-2.0
00011  *
00012  * Unless required by applicable law or agreed to in writing, software
00013  * distributed under the License is distributed on an "AS IS" BASIS,
00014  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015  * See the License for the specific language governing permissions and
00016  * limitations under the License.
00017  */
00018 /** @addtogroup netsocket
00019 * @{
00020 */
00021 
00022 #ifndef _MBED_HTTPS_TLS_TCP_SOCKET_H_
00023 #define _MBED_HTTPS_TLS_TCP_SOCKET_H_
00024 
00025 #include "netsocket/TCPSocket.h"
00026 
00027 #include "mbedtls/platform.h"
00028 #include "mbedtls/ssl.h"
00029 #include "mbedtls/entropy.h"
00030 #include "mbedtls/ctr_drbg.h"
00031 #include "mbedtls/error.h"
00032 
00033 #if !defined(MBED_CONF_NSAPI_OFFLOAD_TLSSOCKET) || !(MBED_CONF_NSAPI_OFFLOAD_TLSSOCKET)
00034 
00035 // This class requires Mbed TLS SSL/TLS client code
00036 #if defined(MBEDTLS_SSL_CLI_C) || defined(DOXYGEN_ONLY)
00037 
00038 #include "TLSSocketWrapper.h"
00039 
00040 /**
00041  * \brief TLSSocket is a wrapper around TCPSocket for interacting with TLS servers.
00042  *
00043  * TLSSocket uses the TLSSocketWrapper with internal TCP socket.
00044  * This is a helper for creating commonly used TLS connections over TCP.
00045  *
00046  */
00047 class TLSSocket : public TLSSocketWrapper {
00048 public:
00049     /** Create an uninitialized socket.
00050      *
00051      *  Must call open to initialize the socket on a network stack.
00052      */
00053     TLSSocket() : TLSSocketWrapper(&tcp_socket) {}
00054 
00055     /** Destroy the TLSSocket and closes the transport.
00056      */
00057     virtual ~TLSSocket();
00058 
00059     /** Opens a socket.
00060      *
00061      *  Creates a network socket on the network stack of the given
00062      *  network interface.
00063      *
00064      *  @note TLSSocket cannot be reopened after closing. It should be destructed to
00065      *        clear internal TLS memory structures.
00066      *
00067      *  @param stack    Network stack as target for socket.
00068      *  @return         NSAPI_ERROR_OK on success. See @ref TCPSocket::open
00069      */
00070     virtual nsapi_error_t open(NetworkStack *stack)
00071     {
00072         return tcp_socket.open(stack);
00073     }
00074 
00075     template <typename S>
00076     nsapi_error_t open(S *stack)
00077     {
00078         return open(nsapi_create_stack(stack));
00079     }
00080 
00081     using TLSSocketWrapper::connect;
00082 
00083     /** Connects TCP socket to a remote host.
00084      *
00085      *  Initiates a connection to a remote server specified by either
00086      *  a domain name or an IP address and port.
00087      *
00088      *  @note: In case connect() returns NSAPI_ERROR_AUTH_FAILURE,
00089      *  the socket must be freed either by calling close() or destroying it.
00090      *
00091      *  @param host     Hostname of the remote host.
00092      *  @param port     Port of the remote host.
00093      *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
00094      *                  See @ref TLSSocketWrapper::connect.
00095      */
00096     MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
00097     nsapi_error_t connect(const char *host, uint16_t port);
00098 
00099 private:
00100     TCPSocket tcp_socket;
00101 };
00102 #endif // MBEDTLS_SSL_CLI_C
00103 
00104 #else // MBED_CONF_NSAPI_OFFLOAD_TLSSOCKET
00105 
00106 class TLSSocket : public TCPSocket {
00107 public:
00108     TLSSocket();
00109     virtual ~TLSSocket();
00110 
00111     /** Set hostname.
00112      *
00113      * TLSSocket requires hostname used to verify the certificate.
00114      * If hostname is not given in constructor, this function must be used before
00115      * starting the TLS handshake.
00116      *
00117      * @param hostname     Hostname of the remote host, used for certificate checking.
00118      */
00119     nsapi_error_t set_hostname(const char *hostname);
00120 
00121     /** Sets the certification of Root CA.
00122      *
00123      * @note Must be called after open() before calling connect()
00124      *
00125      * @param root_ca Root CA Certificate in any Mbed TLS-supported format.
00126      * @param len     Length of certificate (including terminating 0 for PEM).
00127      * @return        NSAPI_ERROR_OK on success, negative error code on failure.
00128      */
00129     virtual nsapi_error_t set_root_ca_cert(const void *root_ca, size_t len);
00130 
00131     /** Sets the certification of Root CA.
00132      *
00133      * @note Must be called after open() before calling connect()
00134      *
00135      * @param root_ca_pem Root CA Certificate in PEM format.
00136      */
00137     virtual nsapi_error_t set_root_ca_cert(const char *root_ca_pem);
00138 
00139 
00140     /** Sets client certificate, and client private key.
00141      *
00142      * @param client_cert Client certification in PEM or DER format.
00143      * @param client_cert_len Certificate size including the terminating null byte for PEM data.
00144      * @param client_private_key_pem Client private key in PEM or DER format.
00145      * @param client_private_key_len Key size including the terminating null byte for PEM data
00146      * @return   NSAPI_ERROR_OK on success, negative error code on failure.
00147      */
00148     virtual nsapi_error_t set_client_cert_key(const void *client_cert, size_t client_cert_len,
00149                                               const void *client_private_key_pem, size_t client_private_key_len);
00150 
00151     /** Sets client certificate, and client private key.
00152      *
00153      * @param client_cert_pem Client certification in PEM format.
00154      * @param client_private_key_pem Client private key in PEM format.
00155      * @return   NSAPI_ERROR_OK on success, negative error code on failure.
00156      */
00157     virtual nsapi_error_t set_client_cert_key(const char *client_cert_pem, const char *client_private_key_pem);
00158 
00159     // From TCPSocket
00160     virtual nsapi_error_t connect(const char *host, uint16_t port);
00161     virtual nsapi_error_t connect(const SocketAddress &address);
00162 
00163 protected:
00164     virtual nsapi_error_t enable_tlssocket();
00165 };
00166 
00167 #endif // MBED_CONF_NSAPI_OFFLOAD_TLSSOCKET
00168 
00169 #endif // _MBED_HTTPS_TLS_TCP_SOCKET_H_
00170 
00171 /** @} */