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:

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.

Tree structure for ESP-TLS component

├── esp_tls.c
├── esp_tls.h
├── esp_tls_mbedtls.c
├── esp_tls_wolfssl.c
└── private_include
    ├── esp_tls_mbedtls.h
    └── esp_tls_wolfssl.h

The ESP-TLS component has a file esp-tls/esp_tls.h which contain the public API headers for the component. Internally ESP-TLS component uses one of the two SSL/TLS Libraries between mbedtls and wolfssl for its operation. API specific to mbedtls are present in esp-tls/private_include/esp_tls_mbedtls.h and API specific to wolfssl are present in esp-tls/private_include/esp_tls_wolfssl.h.

TLS Server verification

The ESP-TLS provides multiple options for TLS server verification on the client side. The ESP-TLS client can verify the server by validating the peer's server certificate or with the help of pre-shared keys. The user should select only one of the following options in the esp_tls_cfg_t structure for TLS server verification. If no option is selected then client will return a fatal error by default at the time of the TLS connection setup.

  • cacert_buf and cacert_bytes: The CA certificate can be provided in a buffer to the esp_tls_cfg_t structure. The ESP-TLS will use the CA certificate present in the buffer to verify the server. The following variables in esp_tls_cfg_t structure must be set.

    • cacert_buf - pointer to the buffer which contains the CA cert.

    • cacert_bytes - size of the CA certificate in bytes.

  • use_global_ca_store: The global_ca_store can be initialized and set at once. Then it can be used to verify the server for all the ESP-TLS connections which have set use_global_ca_store = true in their respective esp_tls_cfg_t structure. See API Reference section below on information regarding different API used for initializing and setting up the global_ca_store.

  • crt_bundle_attach: The ESP x509 Certificate Bundle API provides an easy way to include a bundle of custom x509 root certificates for TLS server verification. More details can be found at ESP x509 Certificate Bundle

  • psk_hint_key: To use pre-shared keys for server verification, CONFIG_ESP_TLS_PSK_VERIFICATION should be enabled in the ESP-TLS menuconfig. Then the pointer to PSK hint and key should be provided to the esp_tls_cfg_t structure. The ESP-TLS will use the PSK for server verification only when no other option regarding the server verification is selected.

  • skip server verification: This is an insecure option provided in the ESP-TLS for testing purpose. The option can be set by enabling CONFIG_ESP_TLS_INSECURE and CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY in the ESP-TLS menuconfig. When this option is enabled the ESP-TLS will skip server verification by default when no other options for server verification are selected in the esp_tls_cfg_t structure. WARNING:Enabling this option comes with a potential risk of establishing a TLS connection with a server which has a fake identity, provided that the server certificate is not provided either through API or other mechanism like ca_store etc.

ESP-TLS Server cert selection hook

The ESP-TLS component provides an option to set the server cert selection hook when using the mbedTLS stack. This provides an ability to configure and use a certificate selection callback during server handshake, to select a certificate to present to the client based on the TLS extensions supplied in the client hello (alpn, sni, etc). To enable this feature, please enable CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK in the ESP-TLS menuconfig. The certificate selection callback can be configured in the esp_tls_cfg_t structure as follows:

int cert_selection_callback(mbedtls_ssl_context *ssl)
{
    /* Code that the callback should execute */
    return 0;
}

esp_tls_cfg_t cfg = {
    cert_select_cb = cert_section_callback,
};

Underlying SSL/TLS Library Options

The ESP-TLS component has an option to use mbedtls or wolfssl as their underlying SSL/TLS library. By default only mbedtls is available and is used, wolfssl SSL/TLS library is available publicly at https://github.com/espressif/esp-wolfssl. The repository provides wolfssl component in binary format, it also provides few examples which are useful for understanding the API. Please refer the repository README.md for information on licensing and other options. Please see below option for using wolfssl in your project.

Note

As the library options are internal to ESP-TLS, switching the libraries will not change ESP-TLS specific code for a project.

How to use wolfssl with ESP-IDF

There are two ways to use wolfssl in your project

  1. Directly add wolfssl as a component in your project with following three commands.:

    (First change directory (cd) to your project directory)
    mkdir components
    cd components
    git clone https://github.com/espressif/esp-wolfssl.git
    
  2. Add wolfssl as an extra component in your project.

  • Download wolfssl with:

    git clone https://github.com/espressif/esp-wolfssl.git
    
  • Include esp-wolfssl in ESP-IDF with setting EXTRA_COMPONENT_DIRS in CMakeLists.txt of your project as done in wolfssl/examples. For reference see Optional Project variables in build-system.

After above steps, you will have option to choose wolfssl as underlying SSL/TLS library in configuration menu of your project as follows:

idf.py menuconfig -> ESP-TLS -> choose SSL/TLS Library -> mbedtls/wolfssl

Comparison between mbedtls and wolfssl

The following table shows a typical comparison between wolfssl and mbedtls when protocols/https_request example (which has server authentication) was run with both SSL/TLS libraries and with all respective configurations set to default. (mbedtls IN_CONTENT length and OUT_CONTENT length were set to 16384 bytes and 4096 bytes respectively)

Property

Wolfssl

Mbedtls

Total Heap Consumed

~19 Kb

~37 Kb

Task Stack Used

~2.2 Kb

~3.6 Kb

Bin size

~858 Kb

~736 Kb

Note

These values are subject to change with change in configuration options and version of respective libraries.

Digital Signature with ESP-TLS

ESP-TLS provides support for using the Digital Signature (DS) with ESP32-C3. Use of the DS for TLS is supported only when ESP-TLS is used with mbedTLS (default stack) as its underlying SSL/TLS stack. For more details on Digital Signature, please refer to the Digital Signature Documentation. The technical details of Digital Signature such as how to calculate private key parameters can be found in ESP32-C3 Technical Reference Manual > Digital Signature (DS) [PDF]. The DS peripheral must be configured before it can be used to perform Digital Signature, see Configure the DS Peripheral in Digital Signature.

The DS peripheral must be initlized with the required encrypted private key parameters (obtained when the DS peripheral is configured). ESP-TLS internally initializes the DS peripheral when provided with the required DS context (DS parameters). Please see the below code snippet for passing the DS context to esp-tls context. The DS context passed to the esp-tls context should not be freed till the TLS connection is deleted.

#include "esp_tls.h"
esp_ds_data_ctx_t *ds_ctx;
/* initialize ds_ctx with encrypted private key parameters, which can be read from the nvs or
provided through the application code */
esp_tls_cfg_t cfg = {
    .clientcert_buf = /* the client cert */,
    .clientcert_bytes = /* length of the client cert */,
    /* other configurations options */
    .ds_data = (void *)ds_ctx,
};

Note

When using Digital Signature for the TLS connection, along with the other required params, only the client cert (clientcert_buf) and the DS params (ds_data) are required and the client key (clientkey_buf) can be set to NULL.

  • An example of mutual authentication with the DS peripheral can be found at ssl mutual auth which internally uses (ESP-TLS) for the TLS connection.

API Reference

Header File

Functions

esp_tls_t *esp_tls_init(void)

Create TLS connection.

This function allocates and initializes esp-tls structure handle.

Returns

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

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.

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

Parameters
  • url -- [in] url of host.

  • cfg -- [in] 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.

Returns

pointer to esp_tls_t, or NULL if connection couldn't be opened.

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.

Parameters
  • hostname -- [in] Hostname of the host.

  • hostlen -- [in] Length of hostname.

  • port -- [in] Port number of the host.

  • cfg -- [in] 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 -- [in] Pointer to esp-tls as esp-tls handle.

Returns

  • -1 If connection establishment fails.

  • 1 If connection establishment is successful.

  • 0 If connection state is in progress.

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

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

The behaviour is same as esp_tls_conn_new_sync() API. However this API accepts host's url.

Parameters
  • url -- [in] url of host.

  • cfg -- [in] 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 -- [in] Pointer to esp-tls as esp-tls handle.

Returns

  • -1 If connection establishment fails.

  • 1 If connection establishment is successful.

  • 0 If connection state is in progress.

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.

Parameters
  • hostname -- [in] Hostname of the host.

  • hostlen -- [in] Length of hostname.

  • port -- [in] Port number of the host.

  • cfg -- [in] TLS configuration as esp_tls_cfg_t. non_block member of this structure should be set to be true.

  • tls -- [in] pointer to esp-tls as esp-tls handle.

Returns

  • -1 If connection establishment fails.

  • 0 If connection establishment is in progress.

  • 1 If connection establishment is successful.

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_async() API. However this API accepts host's url.

Parameters
  • url -- [in] url of host.

  • cfg -- [in] TLS configuration as esp_tls_cfg_t.

  • tls -- [in] pointer to esp-tls as esp-tls handle.

Returns

  • -1 If connection establishment fails.

  • 0 If connection establishment is in progress.

  • 1 If connection establishment is successful.

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

Write from buffer 'data' into specified tls connection.

Parameters
  • tls -- [in] pointer to esp-tls as esp-tls handle.

  • data -- [in] Buffer from which data will be written.

  • datalen -- [in] Length of data buffer.

Returns

  • >=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, because either an error occured or an action must be taken by the calling process.

  • ESP_TLS_ERR_SSL_WANT_READ/ ESP_TLS_ERR_SSL_WANT_WRITE. if the handshake is incomplete and waiting for data to be available for reading. In this case this functions needs to be called again when the underlying transport is ready for operation.

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

Read from specified tls connection into the buffer 'data'.

Parameters
  • tls -- [in] pointer to esp-tls as esp-tls handle.

  • data -- [in] Buffer to hold read data.

  • datalen -- [in] Length of data buffer.

Returns

  • >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.

int esp_tls_conn_destroy(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_sync() (or esp_tls_conn_http_new_sync()) and esp_tls_conn_new_async() (or esp_tls_conn_http_new_async()) APIs.

Parameters

tls -- [in] pointer to esp-tls as esp-tls handle.

Returns

- 0 on success

  • -1 if socket error or an invalid argument

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.

Parameters

tls -- [in] pointer to esp-tls as esp-tls handle.

Returns

  • -1 in case of invalid arg

  • bytes available in the application data record read buffer

esp_err_t esp_tls_get_conn_sockfd(esp_tls_t *tls, int *sockfd)

Returns the connection socket file descriptor from esp_tls session.

Parameters
  • tls -- [in] handle to esp_tls context

  • sockfd -- [out] int pointer to sockfd value.

Returns

- ESP_OK on success and value of sockfd will be updated with socket file descriptor for connection

  • ESP_ERR_INVALID_ARG if (tls == NULL || sockfd == NULL)

esp_err_t esp_tls_set_conn_sockfd(esp_tls_t *tls, int sockfd)

Sets the connection socket file descriptor for the esp_tls session.

Parameters
  • tls -- [in] handle to esp_tls context

  • sockfd -- [in] sockfd value to set.

Returns

- ESP_OK on success and value of sockfd for the tls connection shall updated withthe provided value

  • ESP_ERR_INVALID_ARG if (tls == NULL || sockfd < 0)

esp_err_t esp_tls_get_conn_state(esp_tls_t *tls, esp_tls_conn_state_t *conn_state)

Gets the connection state for the esp_tls session.

Parameters
  • tls -- [in] handle to esp_tls context

  • conn_state -- [out] pointer to the connection state value.

Returns

- ESP_OK on success and value of sockfd for the tls connection shall updated withthe provided value

  • ESP_ERR_INVALID_ARG (Invalid arguments)

esp_err_t esp_tls_set_conn_state(esp_tls_t *tls, esp_tls_conn_state_t conn_state)

Sets the connection state for the esp_tls session.

Parameters
  • tls -- [in] handle to esp_tls context

  • conn_state -- [in] connection state value to set.

Returns

- ESP_OK on success and value of sockfd for the tls connection shall updated withthe provided value

  • ESP_ERR_INVALID_ARG (Invalid arguments)

void *esp_tls_get_ssl_context(esp_tls_t *tls)

Returns the ssl context.

Parameters

tls -- [in] handle to esp_tls context

Returns

- ssl_ctx pointer to ssl context of underlying TLS layer on success

  • NULL in case of error

esp_err_t esp_tls_init_global_ca_store(void)

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().

Returns

  • 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().

Parameters
  • cacert_pem_buf -- [in] 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 -- [in] Length of the buffer.

Returns

  • ESP_OK if adding certificates was successful.

  • Other if an error occured or an action must be taken by the calling process.

void esp_tls_free_global_ca_store(void)

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 *esp_tls_code, int *esp_tls_flags)

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

Parameters
  • h -- [in] esp-tls error handle.

  • esp_tls_code -- [out] last error code returned from mbedtls api (set to zero if none) This pointer could be NULL if caller does not care about esp_tls_code

  • esp_tls_flags -- [out] last certification verification flags (set to zero if none) This pointer could be NULL if caller does not care about esp_tls_code

Returns

  • 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

esp_err_t esp_tls_get_and_clear_error_type(esp_tls_error_handle_t h, esp_tls_error_type_t err_type, int *error_code)

Returns the last error captured in esp_tls of a specific type The error information is cleared internally upon return.

Parameters
  • h -- [in] esp-tls error handle.

  • err_type -- [in] specific error type

  • error_code -- [out] last error code returned from mbedtls api (set to zero if none) This pointer could be NULL if caller does not care about esp_tls_code

Returns

  • ESP_ERR_INVALID_STATE if invalid parameters

  • ESP_OK if a valid error returned and was cleared

esp_err_t esp_tls_get_error_handle(esp_tls_t *tls, esp_tls_error_handle_t *error_handle)

Returns the ESP-TLS error_handle.

Parameters
  • tls -- [in] handle to esp_tls context

  • error_handle -- [out] pointer to the error handle.

Returns

  • ESP_OK on success and error_handle will be updated with the ESP-TLS error handle.

  • ESP_ERR_INVALID_ARG if (tls == NULL || error_handle == NULL)

mbedtls_x509_crt *esp_tls_get_global_ca_store(void)

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.

Returns

  • Pointer to the global CA store currently being used if successful.

  • NULL if there is no global CA store set.

esp_err_t esp_tls_plain_tcp_connect(const char *host, int hostlen, int port, const esp_tls_cfg_t *cfg, esp_tls_error_handle_t error_handle, int *sockfd)

Creates a plain TCP connection, returning a valid socket fd on success or an error handle.

Parameters
  • host -- [in] Hostname of the host.

  • hostlen -- [in] Length of hostname.

  • port -- [in] Port number of the host.

  • cfg -- [in] ESP-TLS configuration as esp_tls_cfg_t.

  • error_handle -- [out] ESP-TLS error handle holding potential errors occurred during connection

  • sockfd -- [out] Socket descriptor if successfully connected on TCP layer

Returns

ESP_OK on success ESP_ERR_INVALID_ARG if invalid output parameters ESP-TLS based error codes on failure

Structures

struct psk_key_hint

ESP-TLS preshared key and hint structure.

Public Members

const uint8_t *key

key in PSK authentication mode in binary format

const size_t key_size

length of the key

const char *hint

hint in PSK authentication mode in string format

struct tls_keep_alive_cfg

esp-tls client session ticket ctx

Keep alive parameters structure

Public Members

bool keep_alive_enable

Enable keep-alive timeout

int keep_alive_idle

Keep-alive idle time (second)

int keep_alive_interval

Keep-alive interval time (second)

int keep_alive_count

Keep-alive packet retry send count

struct esp_tls_cfg

ESP-TLS configuration parameters.

Note

Note about format of certificates:

  • This structure includes certificates of a Certificate Authority, of client or server as well as private keys, which may be of PEM or DER format. In case of PEM format, the buffer must be NULL terminated (with NULL character included in certificate size).

  • Certificate Authority's certificate may be a chain of certificates in case of PEM format, but could be only one certificate in case of DER format

  • Variables names of certificates and private key buffers and sizes are defined as unions providing backward compatibility for legacy *_pem_buf and *_pem_bytes names which suggested only PEM format was supported. It is encouraged to use generic names such as cacert_buf and cacert_bytes.

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_buf

Certificate Authority's certificate in a buffer. Format may be PEM or DER, depending on mbedtls-support This buffer should be NULL terminated in case of PEM

const unsigned char *cacert_pem_buf

CA certificate buffer legacy name

unsigned int cacert_bytes

Size of Certificate Authority certificate pointed to by cacert_buf (including NULL-terminator in case of PEM format)

unsigned int cacert_pem_bytes

Size of Certificate Authority certificate legacy name

const unsigned char *clientcert_buf

Client certificate in a buffer Format may be PEM or DER, depending on mbedtls-support This buffer should be NULL terminated in case of PEM

const unsigned char *clientcert_pem_buf

Client certificate legacy name

unsigned int clientcert_bytes

Size of client certificate pointed to by clientcert_pem_buf (including NULL-terminator in case of PEM format)

unsigned int clientcert_pem_bytes

Size of client certificate legacy name

const unsigned char *clientkey_buf

Client key in a buffer Format may be PEM or DER, depending on mbedtls-support This buffer should be NULL terminated in case of PEM

const unsigned char *clientkey_pem_buf

Client key legacy name

unsigned int clientkey_bytes

Size of client key pointed to by clientkey_pem_buf (including NULL-terminator in case of PEM format)

unsigned int clientkey_pem_bytes

Size of client key legacy name

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 use_ecdsa_peripheral

Use the ECDSA peripheral for the private key operations

uint8_t ecdsa_key_efuse_blk

The efuse block where the ECDSA key is stored

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

bool use_secure_element

Enable this option to use secure element or atecc608a chip ( Integrated with ESP32-WROOM-32SE )

int timeout_ms

Network timeout in milliseconds. Note: If this value is not set, by default the timeout is set to 10 seconds. If you wish that the session should wait indefinitely then please use a larger value e.g., INT32_MAX

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

tls_keep_alive_cfg_t *keep_alive_cfg

Enable TCP keep-alive timeout for SSL connection

const psk_hint_key_t *psk_hint_key

Pointer to PSK hint and key. if not NULL (and certificates are NULL) then PSK authentication is enabled with configured setup. Important note: the pointer must be valid for connection

esp_err_t (*crt_bundle_attach)(void *conf)

Function pointer to esp_crt_bundle_attach. Enables the use of certification bundle for server verification, must be enabled in menuconfig

void *ds_data

Pointer for digital signature peripheral context

bool is_plain_tcp

Use non-TLS connection: When set to true, the esp-tls uses plain TCP transport rather then TLS/SSL connection. Note, that it is possible to connect using a plain tcp transport directly with esp_tls_plain_tcp_connect() API

struct ifreq *if_name

The name of interface for data to go through. Use the default interface without setting

esp_tls_addr_family_t addr_family

The address family to use when connecting to a host.

esp_tls_proto_ver_t tls_version

TLS protocol version of the connection, e.g., TLS 1.2, TLS 1.3 (default - no preference)

Type Definitions

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 psk_key_hint psk_hint_key_t

ESP-TLS preshared key and hint structure.

typedef struct tls_keep_alive_cfg tls_keep_alive_cfg_t

esp-tls client session ticket ctx

Keep alive parameters structure

typedef enum esp_tls_addr_family esp_tls_addr_family_t
typedef struct esp_tls_cfg esp_tls_cfg_t

ESP-TLS configuration parameters.

Note

Note about format of certificates:

  • This structure includes certificates of a Certificate Authority, of client or server as well as private keys, which may be of PEM or DER format. In case of PEM format, the buffer must be NULL terminated (with NULL character included in certificate size).

  • Certificate Authority's certificate may be a chain of certificates in case of PEM format, but could be only one certificate in case of DER format

  • Variables names of certificates and private key buffers and sizes are defined as unions providing backward compatibility for legacy *_pem_buf and *_pem_bytes names which suggested only PEM format was supported. It is encouraged to use generic names such as cacert_buf and cacert_bytes.

typedef struct esp_tls esp_tls_t

Enumerations

enum esp_tls_conn_state

ESP-TLS Connection State.

Values:

enumerator ESP_TLS_INIT
enumerator ESP_TLS_CONNECTING
enumerator ESP_TLS_HANDSHAKE
enumerator ESP_TLS_FAIL
enumerator ESP_TLS_DONE
enum esp_tls_role

Values:

enumerator ESP_TLS_CLIENT
enumerator ESP_TLS_SERVER
enum esp_tls_addr_family

Values:

enumerator ESP_TLS_AF_UNSPEC

Unspecified address family.

enumerator ESP_TLS_AF_INET

IPv4 address family.

enumerator ESP_TLS_AF_INET6

IPv6 address family.

enum esp_tls_proto_ver_t

Values:

enumerator ESP_TLS_VER_ANY
enumerator ESP_TLS_VER_TLS_1_2
enumerator ESP_TLS_VER_TLS_1_3
enumerator ESP_TLS_VER_TLS_MAX

Header File

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 esp_tls_error_code

esp_tls error code from last esp_tls failed api

int esp_tls_flags

last certification verification flags

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/get socket option

ESP_ERR_ESP_TLS_CONNECTION_TIMEOUT

new connection in esp_tls_low_level_conn connection timeouted

ESP_ERR_ESP_TLS_SE_FAILED
ESP_ERR_ESP_TLS_TCP_CLOSED_FIN
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

ESP_ERR_MBEDTLS_SSL_CONF_PSK_FAILED

mbedtls api returned failed

ESP_ERR_MBEDTLS_SSL_TICKET_SETUP_FAILED

mbedtls api returned failed

ESP_ERR_WOLFSSL_SSL_SET_HOSTNAME_FAILED

wolfSSL api returned error

ESP_ERR_WOLFSSL_SSL_CONF_ALPN_PROTOCOLS_FAILED

wolfSSL api returned error

ESP_ERR_WOLFSSL_CERT_VERIFY_SETUP_FAILED

wolfSSL api returned error

ESP_ERR_WOLFSSL_KEY_VERIFY_SETUP_FAILED

wolfSSL api returned error

ESP_ERR_WOLFSSL_SSL_HANDSHAKE_FAILED

wolfSSL api returned failed

ESP_ERR_WOLFSSL_CTX_SETUP_FAILED

wolfSSL api returned failed

ESP_ERR_WOLFSSL_SSL_SETUP_FAILED

wolfSSL api returned failed

ESP_ERR_WOLFSSL_SSL_WRITE_FAILED

wolfSSL api returned failed

ESP_TLS_ERR_SSL_WANT_READ

Definition of errors reported from IO API (potentially non-blocking) in case of error:

  • esp_tls_conn_read()

  • esp_tls_conn_write()

ESP_TLS_ERR_SSL_WANT_WRITE
ESP_TLS_ERR_SSL_TIMEOUT

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.

Enumerations

enum esp_tls_error_type_t

Definition of different types/sources of error codes reported from different components

Values:

enumerator ESP_TLS_ERR_TYPE_UNKNOWN
enumerator ESP_TLS_ERR_TYPE_SYSTEM

System error &#8212; errno

enumerator ESP_TLS_ERR_TYPE_MBEDTLS

Error code from mbedTLS library

enumerator ESP_TLS_ERR_TYPE_MBEDTLS_CERT_FLAGS

Certificate flags defined in mbedTLS

enumerator ESP_TLS_ERR_TYPE_ESP

ESP-IDF error type &#8212; esp_err_t

enumerator ESP_TLS_ERR_TYPE_WOLFSSL

Error code from wolfSSL library

enumerator ESP_TLS_ERR_TYPE_WOLFSSL_CERT_FLAGS

Certificate flags defined in wolfSSL

enumerator ESP_TLS_ERR_TYPE_MAX

Last err type &#8212; invalid entry