Mistake on this page?
Report an issue in GitHub or email us


TLSSocket class hierarchy

TLSSocket and TLSSocketWrapper implement TLS stream over the existing Socket transport. You can find design and implementation details in the SecureSocket page.

To use secure TLS connections, the application uses the TLSSocketWrapper through the Socket API, so existing applications and libraries are compatible.

TLSSocket class reference

Public Types
Public Member Functions
 TLSSocket ()
 Create an uninitialized socket. More...
 ~TLSSocket () override
 Destroy the TLSSocket and closes the transport. More...
nsapi_error_t open (NetworkStack *stack)
 Opens a socket. More...
void set_hostname (const char *hostname)
 Set hostname. More...
nsapi_error_t set_root_ca_cert (const void *root_ca, size_t len)
 Sets the certification of Root CA. More...
nsapi_error_t set_root_ca_cert (const char *root_ca_pem)
 Sets the certification of Root CA. More...
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. More...
nsapi_error_t set_client_cert_key (const char *client_cert_pem, const char *client_private_key_pem)
 Sets client certificate, and client private key. More...
nsapi_error_t send (const void *data, nsapi_size_t size) override
 Send data over a TLS socket. More...
nsapi_size_or_error_t recv (void *data, nsapi_size_t size) override
 Receive data over a TLS socket. More...
nsapi_error_t close () override
 Closes the socket. More...
nsapi_error_t connect (const SocketAddress &address=SocketAddress()) override
 Connect the transport socket and start handshake. More...
nsapi_size_or_error_t sendto (const SocketAddress &address, const void *data, nsapi_size_t size) override
 Send a message on a socket. More...
nsapi_size_or_error_t recvfrom (SocketAddress *address, void *data, nsapi_size_t size) override
 Receive a data from a socket. More...
nsapi_size_or_error_t sendto_control (const SocketAddress &address, const void *data, nsapi_size_t size, nsapi_msghdr_t *control, nsapi_size_t control_size) override
 Send a message on a socket. More...
nsapi_size_or_error_t recvfrom_control (SocketAddress *address, void *data, nsapi_size_t size, nsapi_msghdr_t *control, nsapi_size_t control_size) override
 Receive a data from a socket. More...
nsapi_error_t bind (const SocketAddress &address) override
 Bind a specific address to a socket. More...
void set_blocking (bool blocking) override
 Set blocking or non-blocking mode of the socket. More...
void set_timeout (int timeout) override
 Set timeout on blocking socket operations. More...
void sigio (mbed::Callback< void()> func) override
 Register a callback on state change of the socket. More...
nsapi_error_t setsockopt (int level, int optname, const void *optval, unsigned optlen) override
 Set socket options. More...
nsapi_error_t getsockopt (int level, int optname, void *optval, unsigned *optlen) override
 Get socket options. More...
Socketaccept (nsapi_error_t *error=NULL) override
 Accepts a connection on a socket. More...
nsapi_error_t listen (int backlog=1) override
 Listen for incoming connections. More...
nsapi_error_t getpeername (SocketAddress *address) override
 Get the remote-end peer associated with this socket. More...
mbedtls_x509_crt * get_own_cert ()
 Get own certificate directly from Mbed TLS. More...
int set_own_cert (mbedtls_x509_crt *crt)
 Set own certificate directly to Mbed TLS. More...
mbedtls_x509_crt * get_ca_chain ()
 Get CA chain structure. More...
void set_ca_chain (mbedtls_x509_crt *crt)
 Set CA chain directly to Mbed TLS. More...
mbedtls_ssl_config * get_ssl_config ()
 Get internal Mbed TLS configuration structure. More...
void set_ssl_config (mbedtls_ssl_config *conf)
 Override Mbed TLS configuration. More...
mbedtls_ssl_context * get_ssl_context ()
 Get internal Mbed TLS context structure. More...

TLSSocket example

The sockets example creates a TLS connection to the HTTPS server and receives a simple response from the server.

Please make sure to enable TLS by configuring:

"use-tls-socket": {
            "value": true
/* Sockets Example
 * Copyright (c) 2016-2020 ARM Limited
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *     http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * See the License for the specific language governing permissions and
 * limitations under the License.

#include "mbed.h"
#include "wifi_helper.h"
#include "mbed-trace/mbed_trace.h"

#include "root_ca_cert.h"

#error "mbed-os-example-tls-socket requires a device which supports TRNG"

class SocketDemo {
    static constexpr size_t MAX_NUMBER_OF_ACCESS_POINTS = 10;
    static constexpr size_t MAX_MESSAGE_RECEIVED_LENGTH = 100;

    static constexpr size_t REMOTE_PORT = 443; // tls port
    static constexpr size_t REMOTE_PORT = 80; // standard HTTP port

    SocketDemo() : _net(NetworkInterface::get_default_instance())

        if (_net) {

    void run()
        if (!_net) {
            printf("Error! No network interface found.\r\n");

        /* if we're using a wifi interface run a quick scan */
        if (_net->wifiInterface()) {
            /* the scan is not required to connect and only serves to show visible access points */

            /* in this example we use credentials configured at compile time which are used by
             * NetworkInterface::connect() but it's possible to do this at runtime by using the
             * WiFiInterface::connect() which takes these parameters as arguments */

        /* connect will perform the action appropriate to the interface type to connect to the network */

        printf("Connecting to the network...\r\n");

        nsapi_size_or_error_t result = _net->connect();
        if (result != 0) {
            printf("Error! _net->connect() returned: %d\r\n", result);


        /* opening the socket only allocates resources */
        result = _socket.open(_net);
        if (result != 0) {
            printf("Error! _socket.open() returned: %d\r\n", result);

        result = _socket.set_root_ca_cert(root_ca_cert);
        if (result != NSAPI_ERROR_OK) {
            printf("Error: _socket.set_root_ca_cert() returned %d\n", result);

        /* now we have to find where to connect */

        SocketAddress address;

        if (!resolve_hostname(address)) {


        /* we are connected to the network but since we're using a connection oriented
         * protocol we still need to open a connection on the socket */

        printf("Opening connection to remote port %d\r\n", REMOTE_PORT);

        result = _socket.connect(address);
        if (result != 0) {
            printf("Error! _socket.connect() returned: %d\r\n", result);

        /* exchange an HTTP request and response */

        if (!send_http_request()) {

        if (!receive_http_response()) {

        printf("Demo concluded successfully \r\n");

    bool resolve_hostname(SocketAddress &address)
        const char hostname[] = MBED_CONF_APP_HOSTNAME;

        /* get the host address */
        printf("\nResolve hostname %s\r\n", hostname);
        nsapi_size_or_error_t result = _net->gethostbyname(hostname, &address);
        if (result != 0) {
            printf("Error! gethostbyname(%s) returned: %d\r\n", hostname, result);
            return false;

        printf("%s address is %s\r\n", hostname, (address.get_ip_address() ? address.get_ip_address() : "None") );

        return true;

    bool send_http_request()
        /* loop until whole request sent */
        const char buffer[] = "GET / HTTP/1.1\r\n"
                              "Host: ifconfig.io\r\n"
                              "Connection: close\r\n"

        nsapi_size_t bytes_to_send = strlen(buffer);
        nsapi_size_or_error_t bytes_sent = 0;

        printf("\r\nSending message: \r\n%s", buffer);

        while (bytes_to_send) {
            bytes_sent = _socket.send(buffer + bytes_sent, bytes_to_send);
            if (bytes_sent < 0) {
                printf("Error! _socket.send() returned: %d\r\n", bytes_sent);
                return false;
            } else {
                printf("sent %d bytes\r\n", bytes_sent);

            bytes_to_send -= bytes_sent;

        printf("Complete message sent\r\n");

        return true;

    bool receive_http_response()
        char buffer[MAX_MESSAGE_RECEIVED_LENGTH];
        int remaining_bytes = MAX_MESSAGE_RECEIVED_LENGTH;
        int received_bytes = 0;

        /* loop until there is nothing received or we've ran out of buffer space */
        nsapi_size_or_error_t result = remaining_bytes;
        while (result > 0 && remaining_bytes > 0) {
            nsapi_size_or_error_t result = _socket.recv(buffer + received_bytes, remaining_bytes);
            if (result < 0) {
                printf("Error! _socket.recv() returned: %d\r\n", result);
                return false;

            received_bytes += result;
            remaining_bytes -= result;

        /* the message is likely larger but we only want the HTTP response code */

        printf("received %d bytes:\r\n%.*s\r\n\r\n", received_bytes, strstr(buffer, "\n") - buffer, buffer);

        return true;

    void wifi_scan()
        WiFiInterface *wifi = _net->wifiInterface();

        WiFiAccessPoint ap[MAX_NUMBER_OF_ACCESS_POINTS];

        /* scan call returns number of access points found */
        int result = wifi->scan(ap, MAX_NUMBER_OF_ACCESS_POINTS);

        if (result <= 0) {
            printf("WiFiInterface::scan() failed with return value: %d\r\n", result);

        printf("%d networks available:\r\n", result);

        for (int i = 0; i < result; i++) {
            printf("Network: %s secured: %s BSSID: %hhX:%hhX:%hhX:%hhx:%hhx:%hhx RSSI: %hhd Ch: %hhd\r\n",
                   ap[i].get_ssid(), get_security_string(ap[i].get_security()),
                   ap[i].get_bssid()[0], ap[i].get_bssid()[1], ap[i].get_bssid()[2],
                   ap[i].get_bssid()[3], ap[i].get_bssid()[4], ap[i].get_bssid()[5],
                   ap[i].get_rssi(), ap[i].get_channel());

    void print_network_info()
        /* print the network info */
        SocketAddress a;
        printf("IP address: %s\r\n", a.get_ip_address() ? a.get_ip_address() : "None");
        printf("Netmask: %s\r\n", a.get_ip_address() ? a.get_ip_address() : "None");
        printf("Gateway: %s\r\n", a.get_ip_address() ? a.get_ip_address() : "None");

    NetworkInterface *_net;

    TLSSocket _socket;
    TCPSocket _socket;

int main() {
    printf("\r\nStarting socket demo\r\n\r\n");


    SocketDemo *example = new SocketDemo();

    return 0;

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.