Компонент ESP-TLS предоставляет упрощенный интерфейс API для доступа к функционалу TLS. Он поддерживает общие сценарии использования, такие как проверка сертификата сервера (CA certification validation), SNI, ALPN-переговоры, неблокирующая реализация соединения и т. п. Вся конфигурация может быть задана в структуре данных esp_tls_cfg_t.

Примечание: здесь приведен перевод документации [1] на библиотеку TLS для микроконтроллеров ESP32 от компании Espressif. Незнакомые термины и сокращения см. в разделе "Словарик", в конце статьи.

После того, как конфигурация была определена в переменной структуры esp_tls_cfg_t, коммуникации TLS могут быть осуществлены с помощью следующих API-функций:

esp_tls_init(): инициализирует дескриптор соединения TLS.
esp_tls_conn_new_sync(): откроет новое блокирующее выполнение текущего потока соединение TLS.
esp_tls_conn_new_async(): функция для открытия не блокирующего поток соединения TLS.
esp_tls_conn_read(): функция для чтения из соединения.
esp_tls_conn_write(): функция для записи в соединение.
esp_tls_conn_destroy(): функция для освобождения соединения.

Замечания по поводу форматов сертификатов:

· Структура esp_tls_cfg (esp_tls_cfg_t) включает сертификаты центра сертификации (Certificate Authority, CA), клиента или сервера, а также приватные ключи, которые могут быть в формате PEM или DER. В случае формата PEM буфер должен представлять собой блок данных, завершающийся нулем (NULL terminated; символ NULL должен быть включен а размер сертификата).

· При использовании формата PEM сертификат из Certificate Authority может быть цепочкой сертификатов, но в случае формата DER может быть только один сертификат.

· Имена переменных сертификатов, и буферы приватного ключа, и их размеры определены как объединения (union) для предоставления обратной совместимости с устаревшими именами *_pem_buf и *_pem_bytes, которые подразумевали только поддержку формата PEM. Рекомендуется использовать обычные имена, такие как cacert_buf и cacert_bytes.

typedef struct esp_tls_cfg
{
   const char **alpn_protos; /*!< Протоколы приложения, требуемые для HTTP2.

                                  Если требуется поддержка HTTP2/ALPN, должны

                                  произойти переговоры по утверждению списка

                                  протоколов. Формат списка: длина, за которой

                                  идет имя протокола. Для большинства случаев

                                  подойдет следующий вариант:

                                  const char **alpn_protos = { "h2", NULL };

                                  Здесь 'h2' это имя протокола */

   union
   {
      const unsigned char *cacert_buf; /*!< Сертификат CA в буфере. Формат может

                                            быть PEM или DER, в зависимости от

                                            выбора поддержки mbedtls.

                                            Этот буфер в случае PEM должен

                                            завершаться символом NULL. */
      const unsigned char *cacert_pem_buf; /*!< Устаревшее имя сертификата CA,

                                            оставленное для совместимости. */
   };

   union
   {
      unsigned int cacert_bytes;       /*!< Размер сертификата CA, на который

                                            указывает cacert_buf (размер включает

                                            и символ NULL, если используется

                                            формат PEM). */
      unsigned int cacert_pem_bytes;   /*!< Устаревшее имя длины сертификата CA,

                                            оставленное для совместимости. */
   };

   union
   {
      const unsigned char *clientcert_buf; /*!< Сертификат клиента в буфере.

                                                Формат может быть PEM или DER,

                                                в зависимости от выбора поддержки

                                                mbedtls. Этот буфер в случае PEM

                                                должен завершаться символом NULL. */
      const unsigned char *clientcert_pem_buf; /*!< Устаревшее имя сертификата клиента,

                                                оставленное для совместимости. */
   };

   union
   {
      unsigned int clientcert_bytes;       /*!< Размер сертификата клиента, на который

                                                указывает clientcert_pem_buf (размер

                                                включает и символ NULL, если используется

                                                формат PEM). */
      unsigned int clientcert_pem_bytes;   /*!< Устаревшее имя размера сертификата клиента,

                                                оставленное для совместимости. */
   };

   union
   {
      const unsigned char *clientkey_buf;  /*!< Буфер для ключа клиента. Формат буфера

                                                может быть PEM или DER, в зависимости

                                                от выбора поддержки mbedtls. Этот буфер

                                                в случае PEM должен завершаться

                                                символом NULL. */
      const unsigned char *clientkey_pem_buf; /*!< Устаревшее имя ключа клиента. */
   };

   union
   {
      unsigned int clientkey_bytes;        /*!< Размер ключа клиента, на который указывает

                                                clientkey_pem_buf (размер включает и символ

                                                NULL, если используется формат PEM). */
      unsigned int clientkey_pem_bytes;    /*!< Устаревшее имя размера ключа клиента. */
   };

   const unsigned char *clientkey_password;/*!< Строка пароля расшифровки ключа клиента. */

   unsigned int clientkey_password_len;    /*!< Длина строки пароля, на которую указывает

                                                clientkey_password. */

   bool non_block;                         /*!< Конфигурирует не блокирующий режим. Если

                                                установлено в true, то нижележащий сокет

                                                будет сконфигурирован в non blocking режиме

                                                после установки сессии TLS. */

   bool use_secure_element;                /*!< Установите эту опцию для использования элемента

                                                безопасности чипа atecc608a (интегрирован

                                                на плату разработчика ESP32-WROOM-32SE). */

   int timeout_ms;                         /*!< Таймаут сети в миллисекундах. */

   bool use_global_ca_store;               /*!< Использует глобальное хранилище сертификатов

                                                ca_store для всех соединений, в которых

                                                этот параметр установлен в true. */

   const char *common_name;                /*!< Если не NULL, то CN сертификата сервера должен

                                                совпадать с этим именем. Если NULL, то CN

                                                сертификата сервера должен совпадать с hostname. */

   bool skip_common_name;                  /*!< Пропускать любую проверку поля CN сертификата

                                                сервера. */

   tls_keep_alive_cfg_t *keep_alive_cfg;   /*!< Разрешает таймаут TCP keep-alive для соединения SSL. */

   const psk_hint_key_t* psk_hint_key;     /*!< Указатель на PSK hint и key. Если не NULL (и сертификаты

                                                NULL), то сконфигурированной настройкой разрешена

                                                аутентификация PSK. Важное замечание: для соединения

                                                этот указатель должен быть достоверным. */

   esp_err_t (*crt_bundle_attach)(void *conf);
                                           /*!< Указатель на функцию esp_crt_bundle_attach. Разрешает

                                                использование пакета сертификатов (certification

                                                bundle) для верификации сервера, что должно быть

                                                разрешено в menuconfig. */

   void *ds_data;                          /*!< Указатель на данные цифровой подписи контекста

                                                периферийного устройства DS. */

   bool is_plain_tcp;                      /*!< Использование соединения без TLS: когда установлено

                                                в true, то esp-tls использует чистый транспорт TCP

                                                вместо соединения TLS/SSL. Обратите внимание,

                                                что можно соединиться чистым транспортом TCP

                                                напрямую, с помощью esp_tls_plain_tcp_connect(). */

   struct ifreq *if_name;                  /*!< Имя интерфейса, через который проходят данные.

                                                Без этой установки используется интерфейс

                                                по умолчанию. */

#ifdef CONFIG_ESP_TLS_CLIENT_SESSION_TICKETS
   esp_tls_client_session_t *client_session; /*! Указатель на контекст тикета сессии клиента. */

#endif /* CONFIG_ESP_TLS_CLIENT_SESSION_TICKETS */
} esp_tls_cfg_t;

Поверх слоя защищенного соединения TLS соединения может быть реализован любой протокол наподобие HTTP1, HTTP2 и т. д. Простой пример клиента HTTPS, который использует ESP-TLS для установки соединения защищенного сокета: protocols/https_request.

Дерево структуры компонента TLS:

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

Компонент ESP-TLS подключается к проекту заголовочным файлом esp-tls/esp_tls.h, который содержит объявления публичных заголовков и API-функций для компонента. Внутри себя компонент ESP-TLS для своей работы использует одну из двух библиотек SSL/TLS: mbedtls и wolfssl. Соответствующие этим библиотекам API-функции объявлены в заголовочных файлах esp_tls_mbedtls.h и esp_tls_wolfssl.h.

[Проверка сервера TLS]

ESP-TLS предоставляет несколько опций для верификации сервера TLS на стороне клиента. Клиент ESP-TLS может проверить сервер путем проверки его сертификата, или с помощью предварительного обмена ключами (pre-shared keys). Пользователь должен выбрать одну из следующих опций в структуре esp_tls_cfg_t, чтобы определить опцию проверки сервера TLS. Если не выбрана ни одна из опций, то клиент выполнит возврат с фатальной ошибкой по умолчанию в момент попытки настройки соединения TLS.

· cacert_buf и cacert_bytes: сертификат CA может быть предоставлен в буфере для структуры esp_tls_cfg_t. ESP-TLS будет использовать сертификат CA, предоставленный в этом буфере, чтобы верифицировать сервер. Для этой цели в структуре должен быть установлен указатель на буфер данных CA-сертификата cacert_buf, и размер данных сертификата в этом буфере cacert_bytes.

· use_global_ca_store: может быть однократно установлен и инициализирован global_ca_store. Тогда это может использоваться для верификации сервера для всех соединений ESP-TLS, у которых установлено use_global_ca_store = true в своей соответствующей структуре esp_tls_cfg_t. См. далее справочник по API для получения информации по инициализации и настройке global_ca_store.

· crt_bundle_attach: ESP x509 Certificate Bundle API предоставляет простой способ подключения пакета пользовательских корневых сертификатов x509 (custom x509 root certificates) для верификации сервера TLS. Подробную информацию по библиотеке ESP x509 Certificate Bundle см. в документации [2].

· psk_hint_key: предварительно распределенные между клиентом и сервером секретные ключи (pre-shared keys), предназначенные для верификации сервера. Для этого варианта проверки сервера должна быть разрешена опция CONFIG_ESP_TLS_PSK_VERIFICATION в ESP-TLS menuconfig (idf.py menuconfig → Component config → ESP-TLS → Enable PSK verification). Затем в структуре esp_tls_cfg_t должны быть предоставлены PSK hint и key. ESP-TLS будет использовать PSK для верификации сервера только когда не была выбрана никакая другая опция, относящаяся к верификации сервера.

· skip server verification: это небезопасная опция, предоставленная в ESP-TLS для целей тестирования. Эта опция может быть установлена путем разрешения menuconfig-опций CONFIG_ESP_TLS_INSECURE (idf.py menuconfig → Component config → ESP-TLS → Allow potentially insecure options) и CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY (idf.py menuconfig → Component config → ESP-TLS → Skip server certificate verification by default). Когда эта опция разрешена, компонент ESP-TLS будет по умолчанию пропускать верификацию сервера, когда в структуре esp_tls_cfg_t не выбрана никакая другая опция верификации сервера TLS. ПРЕДУПРЕЖДЕНИЕ: разрешение этой опции вносит потенциальный риск установки соединения TLS с поддельным сервером при условии, что идентификация этого сервера не была проверена ни через предоставленный сертификат (см. описание функции []), ни через другой механизм проверки наподобие ca_store, и т. п.

ESP-TLS Server cert selection hook. Компонент ESP-TLS предоставляет опцию установки функции перехвата момента выбора сертификата сервера (server cert selection hook), когда используется стек mbedTLS. Это дает возможность конфигурирования и использования callback-функции выбора сертификата во время установки обмена с сервером (server handshake), чтобы выбрать сертификат для представления клиенту на основе TLS-расширений, предоставленных в hello клиента (ALPN, SNI и т. д.). Чтобы разрешить эту функцию, разрешите CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK в ESP-TLS menuconfig. Callback-функция выбора сертификата может быть сконфигурирована в структуре esp_tls_cfg_t следующим образом:

int cert_selection_callback(mbedtls_ssl_context *ssl)
{
   /* Код, который выполнит callback */
   ...
   return 0;
}

esp_tls_cfg_t cfg = {
   cert_select_cb = cert_section_callback,
};

[Выбор библиотеки SSL/TLS нижнего уровня]

У компонента ESP-TLS есть опции использования mbedtls или wolfssl в качестве своей нижележащей библиотеки шифрования трафика (SSL/TLS Library). По умолчанию доступна и используется только mbedtls, библиотека wolfssl SSL/TLS публично доступна в репозитории Git [4]. Этот репозиторий предоставляет компонент wolfssl в двоичном формате, и также предоставляет несколько примеров, полезных для понимания его API. Для информации о лицензировании и других опций см. файл README.md из этого репозитория.

Примечание: поскольку выбор варианта библиотеки SSL/TLS влияет на внутреннее поведение ESP-TLS, переключение библиотек не меняет код проекта, специфичный для использования ESP-TLS.

Сравнение mbedtls и wolfssl. В следующей таблице показано типовое сравнение использования wolfssl и mbedtls в примере protocols/https_request (в котором имеется аутентификация сервера). Этот пример запускался с обоими библиотеками SSL/TLS в контексте использования конфигурации по умолчанию (длина mbedtls IN_CONTENT и OUT_CONTENT были установлены в 16384 и 4096 байт соответственно).

Примечание: значения в этой таблице могут меняться в зависимости от опций конфигурации и версий используемых библиотек.

[Цифровая подпись в ESP-TLS]

ESP-TLS предоставляет поддержку для использования цифровой подписи (Digital Signature, DS) вместе с микроконтроллером ESP32-C3. Использование DS для TLS поддерживается только когда ESP-TLS работает вместе с mbedTLS в качестве нижележащей библиотеки SSL/TLS (выбранный по умолчанию стек шифрования). Более подробно про библиотеку, использующую аппаратуру цифровой подписи микроконтроллера см. документацию [6]. Технические подробности технологии DS, такие как вычисление параметров приватного ключа, можно найти в главе "21 Digital Signature (DS)" технического руководства ESP32-C3 [7] (документ PDF). Периферийное устройство DS должно быть предварительно сконфигурировано, чтобы его можно было использовать для цифровой подписи, см. главу "Configure the DS peripheral for a TLS connection" документации [6].

Периферийное устройство DS должно использоваться с требуемыми параметрами приватного шифрованного ключа (encrypted private key), получаемыми при конфигурировании периферийного устройства DS. Библиотека ESP-TLS внутренне инициализирует периферийное устройство DS, когда ей предоставляется требуемый контекст цифровой подписи (параметры DS). Ниже показан кусок кода, демонстрирующий передачу контекста DS в контекст esp-tls. Контекст DS, переданный в контекст esp-tls, не должен освобождаться до тех пор, пока не будет удалено соединение TLS.

#include "esp_tls.h"

esp_ds_data_ctx_t *ds_ctx;

/* Инициализирует ds_ctx параметрами приватного ключа шифрования, который может быть

   прочитан из энергонезависимой памяти (NVS [8]), или предоставлен в коде приложения. */

esp_tls_cfg_t cfg = {
   .clientcert_buf = /* сертификат клиента */,
   .clientcert_bytes = /* длина сертификата клиента */,
   /* другие опции конфигурации */
   .ds_data = (void *)ds_ctx,
};

Примечание: когда используется цифровая подпись для соединения TLS, вместе с другими требуемыми параметрами требуется только сертификат клиента (clientcert_buf) и параметры DS (ds_data), и ключ клиента (clientkey_buf) может быть установлен в NULL.

Пример взаимной аутентификации с помощью периферийного устройства DS можно найти приложении esp-idf/examples/protocols/mqtt/ssl_mutual_auth/ [9], которое использует ESP-TLS для соединения TLS.

[Справочник по API библиотеки ESP TLS]

Заголовочный файл: components/esp-tls/esp_tls.h.

Ниже в таблице приведен общий список API-функций библиотеки ESP TLS. Подробное описание параметров API-функций, структур, типов данных, перечислений и макросов см. в документации [1].

Примечания:

(1) Функция esp_tls_conn_http_new предоставлена для обеспечения обратной совместимости с предыдущими версиями библиотек. Альтернативная функция, обладающая таким же функционалом, esp_tls_conn_http_new_sync (и её асинхронная, не блокирующая версия esp_tls_conn_http_new_async).
(2) Модификация указателя может вызывать сбой при проверке сертификатов.

[Словарик]

ALPN Application-Layer Protocol Negotiation, согласование протокола прикладного уровня — расширение протокола TLS, которое позволяет на прикладном уровне модели OSI согласовать протокол безопасного соединения, что позволяет избежать дополнительных циклов обмена, и который не зависит от целевого протокола прикладного уровня. ALPN используется для установления соединений HTTP/2 без дополнительных циклов согласования протокола обмена данными. Клиент и сервер при этом могут обмениваться данными HTTP/2 через порты, назначенные для HTTPS с HTTP/1.1, или продолжать использовать HTTP/1.1, не создавая новое соединение и не закрывая исходное (из Википедии).

CA Certificate Authority, хранилище доверенных сертификатов, или публичный сервер для выдачи доверенных сертификатов.

TLS Transport Layer Security, протокол защиты транспортного уровня[1]), как и его предшественник SSL (secure sockets layer — слой защищённых сокетов) — криптографические протоколы, обеспечивающие защищённую передачу данных между узлами в сети Интернет. TLS и SSL используют асимметричное шифрование для аутентификации, симметричное шифрование для конфиденциальности и коды аутентичности сообщений для сохранения целостности сообщений (из Википедии).

PSK Pre-Shared Key, пара согласованных ключей, которая распределена между участниками соединения (клиентом и сервером). В TLS это используется как один из вариантов проверки сервера на стороне клиента.

SNI Server Name Indication — расширение компьютерного протокола TLS[1], которое позволяет клиенту сообщать имя хоста, с которым он желает соединиться во время процесса «рукопожатия». Это позволяет серверу предоставлять несколько сертификатов на одном IP-адресе и TCP-порту, и, следовательно, позволяет работать нескольким безопасным (HTTPS) сайтам (или другим сервисам поверх TLS) на одном IP-адресе без использования одного и того же сертификата на всех сайтах. Это эквивалентно возможности основанного на имени виртуального хостинга из HTTP/1.1. Запрашиваемое имя хоста не шифруется, что позволяет злоумышленнику его перехватить (из Википедии).

[Ссылки]

1. ESP TLS site:espressif.com.
2. ESP x509 Certificate Bundle site:espressif.com.
3. ESP32-C3: клиент HTTP.
4. ESP-WOLFSSL.
5. ESP-IDF Build System.
6. Digital Signature (DS) site:espressif.com.
7. ESP32­C3 Technical Reference Manual site:espressif.com.
8. ESP32: библиотека энергонезависимого хранилища данных.
9. ESP-MQTT SSL Sample application (mutual authentication).