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


DTLSSocket and DTLSSocketWrapper implement DTLS stream over the existing Socket transport. You can find design and implementation details in the Secure Socket page.

To use secure DTLS connections, application use the DTLSSocketWrapper through the Socket API, so existing applications and libraries are compatible.

DTLSSocketWrapper inherits TLSSocketWrapper and uses the same API. The only difference is that it uses timers to keep track of DTLS timeouts. Please see TLSSocket for an example.

DTLSSocket class reference

Public Types
Public Member Functions
 DTLSSocket ()
 Create an uninitialized DTLS socket. More...
virtual ~DTLSSocket ()
 Destroy the DTLSSocket and closes the transport. More...
template<typename S >
 DTLSSocket (S *stack, const char *hostname=NULL)
 Create a socket on a network interface. More...
virtual nsapi_error_t open (NetworkStack *stack)
 Opens a socket. More...
nsapi_error_t connect (const char *host, uint16_t port)
 Connects TCP socket to a remote host. 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...
virtual nsapi_error_t send (const void *data, nsapi_size_t size)
 Send data over a TLS socket. More...
virtual nsapi_size_or_error_t recv (void *data, nsapi_size_t size)
 Receive data over a TLS socket. More...
virtual nsapi_error_t close ()
 Closes the socket. More...
virtual nsapi_error_t connect (const SocketAddress &address=SocketAddress())
 Connects socket to a remote address. More...
virtual nsapi_size_or_error_t sendto (const SocketAddress &address, const void *data, nsapi_size_t size)
 Send a message on a socket. More...
virtual nsapi_size_or_error_t recvfrom (SocketAddress *address, void *data, nsapi_size_t size)
 Receive a data from a socket. More...
virtual nsapi_error_t bind (const SocketAddress &address)
 Bind a specific address to a socket. More...
virtual void set_blocking (bool blocking)
 Set blocking or non-blocking mode of the socket. More...
virtual void set_timeout (int timeout)
 Set timeout on blocking socket operations. More...
virtual void sigio (mbed::Callback< void()> func)
 Register a callback on state change of the socket. More...
virtual nsapi_error_t setsockopt (int level, int optname, const void *optval, unsigned optlen)
 Set socket options. More...
virtual nsapi_error_t getsockopt (int level, int optname, void *optval, unsigned *optlen)
 Get socket options. More...
virtual Socketaccept (nsapi_error_t *error=NULL)
 Accepts a connection on a socket. More...
virtual nsapi_error_t listen (int backlog=1)
 Listen for incoming connections. More...
virtual nsapi_error_t getpeername (SocketAddress *address)
 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...

DTLSSocket example

Please see the TLSSocket example:

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

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 != 0) {
        printf("Error! net->connect() returned: %d\n", result);
        return result;

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

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

    printf("Connecting to ifconfig.io\n");
    result = socket->connect("ifconfig.io", 443);
    if (result != 0) {
        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.