Protocomm 扩展方案

protocomm_ext 是 ESP-IDF protocomm 的 客户端扩展。

组件	角色
protocomm (IDF)	设备端 Server：承接配网 / 本地控制会话
protocomm_ext	控制器端 Client：主动建连、完成安全握手、收发载荷

本组件只做 协议管道，不编解码 Wi-Fi 配网或 esp_local_ctrl 业务 protobuf。上层应将已编好的端点载荷交给 protocomm_ext_send_data()。

功能

Security 0：明文会话
Security 1：Curve25519 + AES-256-CTR（可选 PoP）
Security 2：SRP-6a（NG_3072 / SHA512）+ AES-256-GCM（用户名 / 密码）
传输：HTTP / HTTPS、BLE（NimBLE Central）、UART Console
可通过 Kconfig 裁剪未使用的安全版本

支持目标： ESP32 / ESP32-S3 / ESP32-C2 / ESP32-C3 / ESP32-C5 / ESP32-C6 / ESP32-C61 / ESP32-P4

典型流程

#include "protocomm_ext.h"
#include "protocomm_ext_http.h"
#include "protocomm_ext_security.h"

esp_http_client_config_t http_cfg = {
    .url = "http://192.168.4.1:80",
    .timeout_ms = 5000,
};

protocomm_ext_security1_params_t pop = {
    .data = (const uint8_t *)"abcd1234",
    .len = 8,
};

protocomm_ext_config_data_t cfg = {
    .transport_method = PROTOCOMM_EXT_TRANSPORT_METHOD_HTTP,
    .security_method = PROTOCOMM_EXT_SECURITY_METHOD_SECURITY_1,
    .transport_data = &http_cfg,
    .security_data = &pop,
};

protocomm_ext_t *pc = protocomm_ext_new(&cfg);
protocomm_ext_open_session(pc, NULL);
protocomm_ext_establish_security(pc, "prov-session");

uint8_t *resp = NULL;
size_t resp_len = 0;
protocomm_ext_send_data(pc, "prov-config", req, req_len, &resp, &resp_len);
free(resp);

protocomm_ext_close_session(pc);
protocomm_ext_delete(pc);

添加依赖

dependencies:
  espressif/protocomm_ext: "^1.0.0"

API 参考

Header File

components/protocomm_ext/include/common/protocomm_ext.h

Functions

protocomm_ext_t *protocomm_ext_new(protocomm_ext_config_data_t *config)

Create a new protocomm_ext instance.

参数

config – [in] Configuration data

返回

non-NULL : Success
NULL : Invalid argument / unsupported method / OOM

void protocomm_ext_delete(protocomm_ext_t *pc)

Delete a protocomm_ext instance created by protocomm_ext_new()

参数: pc – [in] Instance to delete (NULL-safe)

esp_err_t protocomm_ext_open_session(protocomm_ext_t *pc, const void *config)

Open a transport session.

参数

pc – [in] Instance
config – [in] Transport-specific connect config (BLE address, etc.; may be NULL for HTTP)

返回

ESP_OK on success

esp_err_t protocomm_ext_close_session(protocomm_ext_t *pc)

Close a transport session opened by protocomm_ext_open_session()

参数: pc – [in] Instance
返回: ESP_OK on success

esp_err_t protocomm_ext_get_version_capabilities(protocomm_ext_t *pc, const char *ep_name, uint8_t **out_data, size_t *out_data_len)

Read version/capabilities from the peer version endpoint (plaintext)

Typical endpoint names: “proto-ver”, “esp_local_ctrl/version”. Caller must free *out_data on success.

参数

pc – [in] Instance
ep_name – [in] Version endpoint name
out_data – [out] Received payload
out_data_len – [out] Received payload length

返回

ESP_OK on success

esp_err_t protocomm_ext_set_security(protocomm_ext_t *pc, protocomm_ext_security_method_t security_method, const void *security_data)

Change security scheme / credentials before the handshake.

Typical use: create with Sec0 → open transport → read proto-ver → call this with the peer’s sec_ver and user-entered PoP / username+password → protocomm_ext_security_init() / establish_security().

Cleans up any previous security instance and copied params. Must be called before a successful establish_security().

参数

pc – [in] Instance
security_method – [in] Sec0 / Sec1 / Sec2
security_data – [in] Same meaning as protocomm_ext_config_data_t::security_data

返回

ESP_OK on success

esp_err_t protocomm_ext_security_init(protocomm_ext_t *pc)

Locally prepare security state (e.g. Sec2 SRP client keygen)

Does not talk to the peer. Call this before opening a SoftAP/HTTP session so long CPU-bound work does not starve an idle keep-alive and get the STA kicked.

参数: pc – [in] Instance
返回: ESP_OK on success

esp_err_t protocomm_ext_establish_security(protocomm_ext_t *pc, const char *ep_name)

Run the selected security handshake on the session endpoint.

Typical endpoint names: “prov-session”, “esp_local_ctrl/session”. Reuses an instance from protocomm_ext_security_init() when already prepared.

参数

pc – [in] Instance
ep_name – [in] Session endpoint name

返回

ESP_OK on success

esp_err_t protocomm_ext_send_data(protocomm_ext_t *pc, const char *ep_name, const uint8_t *data, size_t data_len, uint8_t **out_data, size_t *out_data_len)

Send application payload on a business endpoint (encrypt / decrypt as needed)

This API is a pipe only: it does not encode/decode provisioning or local-ctrl protobufs. Caller must free *out_data on success.

参数

pc – [in] Instance
ep_name – [in] Business endpoint name
data – [in] Plaintext request
data_len – [in] Request length
out_data – [out] Plaintext response
out_data_len – [out] Response length

返回

ESP_OK on success

void *protocomm_ext_get_transport_handle(protocomm_ext_t *pc)

Get the underlying transport handle (e.g. for NimBLE scan helpers)

参数: pc – [in] Instance
返回: Transport handle, or NULL if pc is NULL / transport not initialized

protocomm_ext_transport_method_t protocomm_ext_get_transport_method(const protocomm_ext_t *pc)

Transport selected when this instance was created.

参数: pc – [in] Instance
返回: Transport method, or PROTOCOMM_EXT_TRANSPORT_METHOD_MAX if pc is NULL

esp_err_t protocomm_ext_set_config_endpoint(protocomm_ext_t *pc, const char *endpoint_name, uint16_t uuid)

Register a logical endpoint name → BLE characteristic UUID16 mapping.

Required for BLE before get_version / establish_security / send_data that use named endpoints. Mirrors device-side wifi_prov_scheme_t::set_config_endpoint (e.g. manager.c registering “prov-session” → 0xFF51).

Application components (network_provisioner, esp_local_controller, …) should call this for each endpoint they use. HTTP and Console ignore uuid and return ESP_OK.

Re-registering the same name updates the UUID.

参数

pc – [in] Instance
endpoint_name – [in] Logical name (must not be NULL)
uuid – [in] 16-bit UUID embedded in the peer GATT characteristic

返回

ESP_OK on success

Structures

struct protocomm_ext_config_data_t

Configuration for creating a protocomm_ext instance.

transport_data / security_data meaning depends on the selected methods:

HTTP: transport_data -> esp_http_client_config_t *
BLE: transport_data -> NULL (scan/connect via NimBLE helpers)
Console:transport_data -> protocomm_ext_console_config_t *
Sec0: security_data -> NULL
Sec1: security_data -> protocomm_ext_security1_params_t * (optional PoP)
Sec2: security_data -> protocomm_ext_security2_params_t * (username/password)

Public Members

protocomm_ext_transport_method_t transport_method: Selected transport implementation.

protocomm_ext_security_method_t security_method: Selected security scheme.

void *transport_data

Transport-specific configuration pointer.

Meaning depends on transport_method:

HTTP: pointer to esp_http_client_config_t
BLE: NULL
Console: pointer to protocomm_ext_console_config_t

void *security_data

Security-specific configuration pointer.

Meaning depends on security_method:

Sec0: NULL
Sec1: pointer to protocomm_ext_security1_params_t
Sec2: pointer to protocomm_ext_security2_params_t

Type Definitions

typedef struct protocomm_ext protocomm_ext_t: Opaque protocomm_ext instance returned by protocomm_ext_new()

Enumerations

enum protocomm_ext_transport_method_t

Values:

enumerator PROTOCOMM_EXT_TRANSPORT_METHOD_BLE: BLE (NimBLE central) transport

enumerator PROTOCOMM_EXT_TRANSPORT_METHOD_HTTP: HTTP/HTTPS transport

enumerator PROTOCOMM_EXT_TRANSPORT_METHOD_CONSOLE: UART console transport

enumerator PROTOCOMM_EXT_TRANSPORT_METHOD_MAX: Maximum transport method

enum protocomm_ext_security_method_t

Values:

enumerator PROTOCOMM_EXT_SECURITY_METHOD_NONE: Security 0 (no encryption)

enumerator PROTOCOMM_EXT_SECURITY_METHOD_SECURITY_1: Security 1 (Curve25519 + AES-CTR)

enumerator PROTOCOMM_EXT_SECURITY_METHOD_SECURITY_2: Security 2 (SRP-6a + AES-GCM)

enumerator PROTOCOMM_EXT_SECURITY_METHOD_MAX: Maximum security method

Header File

components/protocomm_ext/include/security/protocomm_ext_security.h

Structures

struct protocomm_ext_security1_params

Protocomm Ext Security 1 parameters: Proof Of Possession.

Public Members

const uint8_t *data: Pointer to buffer containing the proof of possession data

uint16_t len: Length (in bytes) of the proof of possession data

struct protocomm_ext_security2_params

Protocomm Ext Security 2 parameters: username + password.

Strings need not be null-terminated when lengths are provided.

Public Members

const char *username: Username buffer used by the Security 2 SRP client.

uint16_t username_len: Username length in bytes.

const char *password: Password buffer used by the Security 2 SRP client.

uint16_t password_len: Password length in bytes.

struct protocomm_ext_security

Protocomm Ext security object structure.

The member functions are used for implementing secure protocomm sessions.

备注

This structure should not have any dynamic members to allow re-entrancy

Public Members

int ver: Unique version number of security implementation

esp_err_t (*init)(protocomm_ext_security_handle_t *handle, const void *sec_params)

Function for initializing/allocating security infrastructure

Param handle: Security handle
Param sec_params: Security parameters
Return: ESP_OK on success, otherwise an error code

esp_err_t (*cleanup)(protocomm_ext_security_handle_t handle)

Function for deallocating security infrastructure

Param handle: Security handle
Return: ESP_OK on success, otherwise an error code

esp_err_t (*security_send_command0)(protocomm_ext_security_handle_t handle, uint8_t **outbuf, ssize_t *outlen, void *priv_data)

Function for getting security send command0 data

Param handle: Security handle
Param outbuf: Output buffer, need to be freed by the caller
Param outlen: Output length
Param priv_data: Private data
Return: ESP_OK on success, otherwise an error code

esp_err_t (*security_parse_command0)(protocomm_ext_security_handle_t handle, const uint8_t *inbuf, ssize_t inlen, void *priv_data)

Function for parsing security command0 response

Param handle: Security handle
Param inbuf: Input buffer
Param inlen: Input length
Param priv_data: Private data
Return: ESP_OK on success, otherwise an error code

esp_err_t (*security_send_command1)(protocomm_ext_security_handle_t handle, uint8_t **outbuf, ssize_t *outlen, void *priv_data)

Function for getting security send command1 data

Param handle: Security handle
Param outbuf: Output buffer, need to be freed by the caller
Param outlen: Output length
Param priv_data: Private data
Return: ESP_OK on success, otherwise an error code

esp_err_t (*security_parse_command1)(protocomm_ext_security_handle_t handle, const uint8_t *inbuf, ssize_t inlen, void *priv_data)

Function for parsing security command1 response

Param handle: Security handle
Param inbuf: Input buffer
Param inlen: Input length
Param priv_data: Private data
Return: ESP_OK on success, otherwise an error code

esp_err_t (*encrypt)(protocomm_ext_security_handle_t handle, const uint8_t *inbuf, ssize_t inlen, uint8_t **outbuf, ssize_t *outlen)

Function which implements the encryption algorithm

Param handle: Security handle
Param inbuf: Input buffer
Param inlen: Input length
Param outbuf: Output buffer, need to be freed by the caller
Param outlen: Output length
Return: ESP_OK on success, otherwise an error code

esp_err_t (*decrypt)(protocomm_ext_security_handle_t handle, const uint8_t *inbuf, ssize_t inlen, uint8_t **outbuf, ssize_t *outlen)

Function which implements the decryption algorithm

Param handle: Security handle
Param inbuf: Input buffer
Param inlen: Input length
Param outbuf: Output buffer, need to be freed by the caller
Param outlen: Output length
Return: ESP_OK on success, otherwise an error code

Type Definitions

typedef struct protocomm_ext_security1_params protocomm_ext_security1_params_t: Protocomm Ext Security 1 parameters: Proof Of Possession.

typedef struct protocomm_ext_security2_params protocomm_ext_security2_params_t

Protocomm Ext Security 2 parameters: username + password.

Strings need not be null-terminated when lengths are provided.

typedef void *protocomm_ext_security_handle_t

typedef struct protocomm_ext_security protocomm_ext_security_t

Protocomm Ext security object structure.

The member functions are used for implementing secure protocomm sessions.

备注

This structure should not have any dynamic members to allow re-entrancy

Structures

struct protocomm_ext_console_config_t

Configuration for protocomm console client transport.

Talks to a device-side protocomm_console server over UART using the text protocol: <ep_name> <session_id> <hex_payload>\r, response is a hex line.

If the UART driver is already installed for uart_num, init reuses it and does not reconfigure pins/baud or delete the driver on deinit. Otherwise init installs the driver (param/pin) and deinit deletes it.

Public Members

int uart_num: UART port number, for example UART_NUM_0.

int tx_io_num: TX GPIO number used when the driver is installed by this transport.

int rx_io_num: RX GPIO number used when the driver is installed by this transport.

int baud_rate: UART baud rate. Uses 115200 when set to 0.

uint32_t timeout_ms: Response timeout in milliseconds. Uses 5000 when set to 0.

提供有关此文档的反馈