Esp-Tls - Espressif ESP32-S2 Programming Manual

Chapter 2. API Reference

2.3.3 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(): for reading from the connection.
• esp_tls_conn_write(): for writing into 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.
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
nally 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_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
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
ture. The ESP-TLS will use the CA certificate present in the buffer to verify the server. The following variables
in esp_tls_cfg_t
– 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
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
• psk_hint_key: To use pre-shared keys for server 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
option regarding the server verification is selected.
Espressif Systems
esp-tls/esp_tls.h which contain the public API headers for the component. Inter-
esp-tls/private_include/esp_tls_mbedtls.h
esp_tls_cfg_t structure for TLS server verification. If no option is selected
structure must be set.
structure. See API Reference section below on information regarding
structure. The ESP-TLS will use the PSK for server verification only when no other
519
Submit Document Feedback
and API specific to wolfssl are present in
esp_tls_cfg_t
ESP x509 Certificate Bundle
CONFIG_ESP_TLS_PSK_VERIFICATION
struc-
Release v4.4