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_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 TLSSocket example creates TLS connection to the HTTPS server and receives a simple response from the server:

#include "mbed.h"
#include "mbed_trace.h"

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

const char cert[] = \
    "-----BEGIN CERTIFICATE-----\n"
    "-----END CERTIFICATE-----";

int main(void)
    char *buffer = new char[256];
    nsapi_size_or_error_t result;
    nsapi_size_t size;
    const char query[] = "GET / HTTP/1.1\r\nHost: ifconfig.io\r\nConnection: close\r\n\r\n";


    printf("TLSSocket Example.\n");
    printf("Mbed OS version: %d.%d.%d\n\n", MBED_MAJOR_VERSION, MBED_MINOR_VERSION, MBED_PATCH_VERSION);

    NetworkInterface *net = NetworkInterface::get_default_instance();

    if (!net) {
        printf("Error! No network inteface found.\n");
        return 0;

    printf("Connecting to network\n");
    result = net->connect();
    if (result != NSAPI_ERROR_OK) {
        printf("Error! net->connect() returned: %d\n", result);
        return result;

    printf("Connecting to ifconfig.io\n");
    SocketAddress addr;
    result = net->gethostbyname("ifconfig.io", &addr);
    if (result != NSAPI_ERROR_OK) {
	printf("Error! DNS resolution for ifconfig.io failed with %d\n", result);

    TLSSocket *socket = new TLSSocket;
    result = socket->open(net);
    if (result != NSAPI_ERROR_OK) {
        printf("Error! socket->open() returned: %d\n", result);
        return result;


    result = socket->set_root_ca_cert(cert);
    if (result != NSAPI_ERROR_OK) {
        printf("Error: socket->set_root_ca_cert() returned %d\n", result);
        return result;

    result = socket->connect(addr);
    if (result != NSAPI_ERROR_OK) {
        printf("Error! socket->connect() returned: %d\n", result);
        goto DISCONNECT;

    // Send a simple http request
    size = strlen(query);
    result = socket->send(query, size);
    if (result != size) {
        printf("Error! socket->send() returned: %d\n", result);
        goto DISCONNECT;

    // Receieve an HTTP response and print out the response line
    while ((result = socket->recv(buffer, 255)) > 0) {
        buffer[result] = 0;
        printf("%s", buffer);

    if (result < 0) {
        printf("Error! socket->recv() returned: %d\n", result);
        goto DISCONNECT;

    delete[] buffer;
    // Close the socket to return its memory
    delete socket;

    // Bring down the network interface

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.