ESP-TLS

Overview

The ESP-TLS component provides a simplified API interface for accessing the commonly used TLS functionality. It supports common scenarios like CA certification validation, SNI, ALPN negotiation, non-blocking connection among others. All the configuration can be specified in the esp_tls_cfg_t data structure. Once done, TLS communication can be conducted using the following APIs: * esp_tls_conn_new(): for opening a new TLS connection * esp_tls_conn_read/write(): for reading/writing from the connection * esp_tls_conn_delete(): for freeing up the connection Any application layer protocol like HTTP1, HTTP2 etc can be executed on top of this layer.

Application Example

Simple HTTPS example that uses ESP-TLS to establish a secure socket connection: protocols/https_request.

API Reference

Header File

Functions

esp_tls_t *esp_tls_init()

Create TLS connection.

This function allocates and initializes esp-tls structure handle.

Return
tls Pointer to esp-tls as esp-tls handle if successfully initialized, NULL if allocation error

esp_tls_t *esp_tls_conn_new(const char *hostname, int hostlen, int port, const esp_tls_cfg_t *cfg)

Create a new blocking TLS/SSL connection.

This function establishes a TLS/SSL connection with the specified host in blocking manner.

Note: This API is present for backward compatibility reasons. Alternative function with the same functionality is esp_tls_conn_new_sync (and its asynchronous version esp_tls_conn_new_async)

Return
pointer to esp_tls_t, or NULL if connection couldn’t be opened.
Parameters
  • hostname: Hostname of the host.
  • hostlen: Length of hostname.
  • port: Port number of the host.
  • cfg: TLS configuration as esp_tls_cfg_t. If you wish to open non-TLS connection, keep this NULL. For TLS connection, a pass pointer to esp_tls_cfg_t. At a minimum, this structure should be zero-initialized.

int esp_tls_conn_new_sync(const char *hostname, int hostlen, int port, const esp_tls_cfg_t *cfg, esp_tls_t *tls)

Create a new blocking TLS/SSL connection.

This function establishes a TLS/SSL connection with the specified host in blocking manner.

Return
  • -1 If connection establishment fails.
  • 1 If connection establishment is successful.
  • 0 Reserved for connection state is in progress.
Parameters
  • hostname: Hostname of the host.
  • hostlen: Length of hostname.
  • port: Port number of the host.
  • cfg: TLS configuration as esp_tls_cfg_t. If you wish to open non-TLS connection, keep this NULL. For TLS connection, a pass pointer to esp_tls_cfg_t. At a minimum, this structure should be zero-initialized.
  • tls: Pointer to esp-tls as esp-tls handle.

esp_tls_t *esp_tls_conn_http_new(const char *url, const esp_tls_cfg_t *cfg)

Create a new blocking TLS/SSL connection with a given “HTTP” url.

The behaviour is same as esp_tls_conn_new() API. However this API accepts host’s url.

Return
pointer to esp_tls_t, or NULL if connection couldn’t be opened.
Parameters
  • url: url of host.
  • cfg: TLS configuration as esp_tls_cfg_t. If you wish to open non-TLS connection, keep this NULL. For TLS connection, a pass pointer to ‘esp_tls_cfg_t’. At a minimum, this structure should be zero-initialized.

int esp_tls_conn_new_async(const char *hostname, int hostlen, int port, const esp_tls_cfg_t *cfg, esp_tls_t *tls)

Create a new non-blocking TLS/SSL connection.

This function initiates a non-blocking TLS/SSL connection with the specified host, but due to its non-blocking nature, it doesn’t wait for the connection to get established.

Return
  • -1 If connection establishment fails.
  • 0 If connection establishment is in progress.
  • 1 If connection establishment is successful.
Parameters
  • hostname: Hostname of the host.
  • hostlen: Length of hostname.
  • port: Port number of the host.
  • cfg: TLS configuration as esp_tls_cfg_t. non_block member of this structure should be set to be true.
  • tls: pointer to esp-tls as esp-tls handle.

int esp_tls_conn_http_new_async(const char *url, const esp_tls_cfg_t *cfg, esp_tls_t *tls)

Create a new non-blocking TLS/SSL connection with a given “HTTP” url.

The behaviour is same as esp_tls_conn_new() API. However this API accepts host’s url.

Return
  • -1 If connection establishment fails.
  • 0 If connection establishment is in progress.
  • 1 If connection establishment is successful.
Parameters
  • url: url of host.
  • cfg: TLS configuration as esp_tls_cfg_t.
  • tls: pointer to esp-tls as esp-tls handle.

static ssize_t esp_tls_conn_write(esp_tls_t *tls, const void *data, size_t datalen)

Write from buffer ‘data’ into specified tls connection.

Return
  • >0 if write operation was successful, the return value is the number of bytes actually written to the TLS/SSL connection.
  • 0 if write operation was not successful. The underlying connection was closed.
  • <0 if write operation was not successful, because either an error occured or an action must be taken by the calling process.
Parameters
  • tls: pointer to esp-tls as esp-tls handle.
  • data: Buffer from which data will be written.
  • datalen: Length of data buffer.

static ssize_t esp_tls_conn_read(esp_tls_t *tls, void *data, size_t datalen)

Read from specified tls connection into the buffer ‘data’.

Return
  • >0 if read operation was successful, the return value is the number of bytes actually read from the TLS/SSL connection.
  • 0 if read operation was not successful. The underlying connection was closed.
  • <0 if read operation was not successful, because either an error occured or an action must be taken by the calling process.
Parameters
  • tls: pointer to esp-tls as esp-tls handle.
  • data: Buffer to hold read data.
  • datalen: Length of data buffer.

void esp_tls_conn_delete(esp_tls_t *tls)

Close the TLS/SSL connection and free any allocated resources.

This function should be called to close each tls connection opened with esp_tls_conn_new() or esp_tls_conn_http_new() APIs.

Parameters
  • tls: pointer to esp-tls as esp-tls handle.

ssize_t esp_tls_get_bytes_avail(esp_tls_t *tls)

Return the number of application data bytes remaining to be read from the current record.

This API is a wrapper over mbedtls’s mbedtls_ssl_get_bytes_avail() API.

Return
  • -1 in case of invalid arg
  • bytes available in the application data record read buffer
Parameters
  • tls: pointer to esp-tls as esp-tls handle.

esp_err_t esp_tls_init_global_ca_store()

Create a global CA store, initially empty.

This function should be called if the application wants to use the same CA store for multiple connections. This function initialises the global CA store which can be then set by calling esp_tls_set_global_ca_store(). To be effective, this function must be called before any call to esp_tls_set_global_ca_store().

Return
  • ESP_OK if creating global CA store was successful.
  • ESP_ERR_NO_MEM if an error occured when allocating the mbedTLS resources.

esp_err_t esp_tls_set_global_ca_store(const unsigned char *cacert_pem_buf, const unsigned int cacert_pem_bytes)

Set the global CA store with the buffer provided in pem format.

This function should be called if the application wants to set the global CA store for multiple connections i.e. to add the certificates in the provided buffer to the certificate chain. This function implicitly calls esp_tls_init_global_ca_store() if it has not already been called. The application must call this function before calling esp_tls_conn_new().

Return
  • ESP_OK if adding certificates was successful.
  • Other if an error occured or an action must be taken by the calling process.
Parameters
  • cacert_pem_buf: Buffer which has certificates in pem format. This buffer is used for creating a global CA store, which can be used by other tls connections.
  • cacert_pem_bytes: Length of the buffer.

mbedtls_x509_crt *esp_tls_get_global_ca_store()

Get the pointer to the global CA store currently being used.

The application must first call esp_tls_set_global_ca_store(). Then the same CA store could be used by the application for APIs other than esp_tls.

Note
Modifying the pointer might cause a failure in verifying the certificates.
Return
  • Pointer to the global CA store currently being used if successful.
  • NULL if there is no global CA store set.

void esp_tls_free_global_ca_store()

Free the global CA store currently being used.

The memory being used by the global CA store to store all the parsed certificates is freed up. The application can call this API if it no longer needs the global CA store.

esp_err_t esp_tls_get_and_clear_last_error(esp_tls_error_handle_t h, int *mbedtls_code, int *mbedtls_flags)

Returns last error in esp_tls with detailed mbedtls related error codes. The error information is cleared internally upon return.

Return
  • ESP_ERR_INVALID_STATE if invalid parameters
  • ESP_OK (0) if no error occurred
  • specific error code (based on ESP_ERR_ESP_TLS_BASE) otherwise
Parameters
  • h: esp-tls error handle.
  • mbedtls_code: last error code returned from mbedtls api (set to zero if none) This pointer could be NULL if caller does not care about mbedtls_code
  • mbedtls_flags: last certification verification flags (set to zero if none) This pointer could be NULL if caller does not care about mbedtls_flags

Structures

struct esp_tls_last_error

Error structure containing relevant errors in case tls error occurred.

Public Members

esp_err_t last_error

error code (based on ESP_ERR_ESP_TLS_BASE) of the last occurred error

int mbedtls_error_code

mbedtls error code from last mbedtls failed api

int mbedtls_flags

last certification verification flags

struct esp_tls_cfg

ESP-TLS configuration parameters.

Public Members

const char **alpn_protos

Application protocols required for HTTP2. If HTTP2/ALPN support is required, a list of protocols that should be negotiated. The format is length followed by protocol name. For the most common cases the following is ok: const char **alpn_protos = { “h2”, NULL };

  • where ‘h2’ is the protocol name

const unsigned char *cacert_pem_buf

Certificate Authority’s certificate in a buffer. This buffer should be NULL terminated

unsigned int cacert_pem_bytes

Size of Certificate Authority certificate pointed to by cacert_pem_buf

const unsigned char *clientcert_pem_buf

Client certificate in a buffer This buffer should be NULL terminated

unsigned int clientcert_pem_bytes

Size of client certificate pointed to by clientcert_pem_buf

const unsigned char *clientkey_pem_buf

Client key in a buffer This buffer should be NULL terminated

unsigned int clientkey_pem_bytes

Size of client key pointed to by clientkey_pem_buf

const unsigned char *clientkey_password

Client key decryption password string

unsigned int clientkey_password_len

String length of the password pointed to by clientkey_password

bool non_block

Configure non-blocking mode. If set to true the underneath socket will be configured in non blocking mode after tls session is established

int timeout_ms

Network timeout in milliseconds

bool use_global_ca_store

Use a global ca_store for all the connections in which this bool is set.

const char *common_name

If non-NULL, server certificate CN must match this name. If NULL, server certificate CN must match hostname.

bool skip_common_name

Skip any validation of server certificate CN field

struct esp_tls

ESP-TLS Connection Handle.

Public Members

mbedtls_ssl_context ssl

TLS/SSL context

mbedtls_entropy_context entropy

mbedTLS entropy context structure

mbedtls_ctr_drbg_context ctr_drbg

mbedTLS ctr drbg context structure. CTR_DRBG is deterministic random bit generation based on AES-256

mbedtls_ssl_config conf

TLS/SSL configuration to be shared between mbedtls_ssl_context structures

mbedtls_net_context server_fd

mbedTLS wrapper type for sockets

mbedtls_x509_crt cacert

Container for the X.509 CA certificate

mbedtls_x509_crt *cacert_ptr

Pointer to the cacert being used.

mbedtls_x509_crt clientcert

Container for the X.509 client certificate

mbedtls_pk_context clientkey

Container for the private key of the client certificate

int sockfd

Underlying socket file descriptor.

ssize_t (*read)(struct esp_tls *tls, char *data, size_t datalen)

Callback function for reading data from TLS/SSL connection.

ssize_t (*write)(struct esp_tls *tls, const char *data, size_t datalen)

Callback function for writing data to TLS/SSL connection.

esp_tls_conn_state_t conn_state

ESP-TLS Connection state

fd_set rset

read file descriptors

fd_set wset

write file descriptors

bool is_tls

indicates connection type (TLS or NON-TLS)

esp_tls_role_t role

esp-tls role

  • ESP_TLS_CLIENT
  • ESP_TLS_SERVER

esp_tls_error_handle_t error_handle

handle to error descriptor

Macros

ESP_ERR_ESP_TLS_BASE

Starting number of ESP-TLS error codes

ESP_ERR_ESP_TLS_CANNOT_RESOLVE_HOSTNAME

Error if hostname couldn’t be resolved upon tls connection

ESP_ERR_ESP_TLS_CANNOT_CREATE_SOCKET

Failed to create socket

ESP_ERR_ESP_TLS_UNSUPPORTED_PROTOCOL_FAMILY

Unsupported protocol family

ESP_ERR_ESP_TLS_FAILED_CONNECT_TO_HOST

Failed to connect to host

ESP_ERR_ESP_TLS_SOCKET_SETOPT_FAILED

failed to set socket option

ESP_ERR_MBEDTLS_CERT_PARTLY_OK

mbedtls parse certificates was partly successful

ESP_ERR_MBEDTLS_CTR_DRBG_SEED_FAILED

mbedtls api returned error

ESP_ERR_MBEDTLS_SSL_SET_HOSTNAME_FAILED

mbedtls api returned error

ESP_ERR_MBEDTLS_SSL_CONFIG_DEFAULTS_FAILED

mbedtls api returned error

ESP_ERR_MBEDTLS_SSL_CONF_ALPN_PROTOCOLS_FAILED

mbedtls api returned error

ESP_ERR_MBEDTLS_X509_CRT_PARSE_FAILED

mbedtls api returned error

ESP_ERR_MBEDTLS_SSL_CONF_OWN_CERT_FAILED

mbedtls api returned error

ESP_ERR_MBEDTLS_SSL_SETUP_FAILED

mbedtls api returned error

ESP_ERR_MBEDTLS_SSL_WRITE_FAILED

mbedtls api returned error

ESP_ERR_MBEDTLS_PK_PARSE_KEY_FAILED

mbedtls api returned failed

ESP_ERR_MBEDTLS_SSL_HANDSHAKE_FAILED

mbedtls api returned failed

Type Definitions

typedef struct esp_tls_last_error *esp_tls_error_handle_t
typedef struct esp_tls_last_error esp_tls_last_error_t

Error structure containing relevant errors in case tls error occurred.

typedef enum esp_tls_conn_state esp_tls_conn_state_t

ESP-TLS Connection State.

typedef enum esp_tls_role esp_tls_role_t
typedef struct esp_tls_cfg esp_tls_cfg_t

ESP-TLS configuration parameters.

typedef struct esp_tls esp_tls_t

ESP-TLS Connection Handle.

Enumerations

enum esp_tls_conn_state

ESP-TLS Connection State.

Values:

ESP_TLS_INIT = 0
ESP_TLS_CONNECTING
ESP_TLS_HANDSHAKE
ESP_TLS_FAIL
ESP_TLS_DONE
enum esp_tls_role

Values:

ESP_TLS_CLIENT = 0
ESP_TLS_SERVER