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_conn_new(const char *hostname, int hostlen, int port, const esp_tls_cfg_t *cfg)

Create a new TLS/SSL connection.

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

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.

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

Create a new 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.

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.

Structures

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: “\x02h2”

  • where the first ‘2’ is the length of the protocol and
  • the subsequent ‘h2’ is the protocol name

const unsigned char *cacert_pem_buf

Certificate Authority’s certificate in a buffer

unsigned int cacert_pem_bytes

Size of Certificate Authority certificate pointed to by cacert_pem_buf

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

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 an X.509 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.

Type Definitions

typedef struct esp_tls_cfg esp_tls_cfg_t

ESP-TLS configuration parameters.

typedef struct esp_tls esp_tls_t

ESP-TLS Connection Handle.