Security Handshake API

Security handshake related APIs for ESP-NOW.

API Reference

Header File

Functions

esp_err_t espnow_sec_initiator_scan(espnow_sec_responder_t **info_list, size_t *num, TickType_t wait_ticks)

Root scans other node info.

Attention

Only called at the root

Parameters:

  • info_list – [out] destination nodes of mac

  • num – [out] number of scaned nodes

  • wait_ticks – [in] the maximum scanning time in ticks

Returns:

  • ESP_OK

  • ESP_ERR_INVALID_ARG

esp_err_t espnow_sec_initiator_scan_result_free(void)

Free memory in the scan information list.

Returns:

  • ESP_OK

esp_err_t espnow_sec_initiator_start(uint8_t key_info[APP_KEY_LEN], const char *pop_data, const uint8_t addrs_list[][6], size_t addrs_num, espnow_sec_result_t *res)

Root sends security to other nodes.

Attention

Only called at the root

Parameters:

  • key_info – [in] the security key info to sent to responder

  • pop_data – [in] Proof of Possession (PoP) string

  • addrs_list – [in] destination nodes of mac

  • addrs_num – [in] number of destination nodes

  • res – [out] must call espnow_sec_initiator_result_free to free memory

Returns:

  • ESP_OK

  • ESP_ERR_INVALID_ARG

esp_err_t espnow_sec_initiator_stop()

Stop Root to send security to other nodes.

Returns:

  • ESP_OK

esp_err_t espnow_sec_initiator_result_free(espnow_sec_result_t *result)

Free memory in the results list.

Parameters:

result – [in] pointer to device security status

Returns:

  • ESP_OK

  • ESP_ERR_INVALID_ARG

esp_err_t espnow_sec_responder_start(const char *pop_data)

Start security process.

Parameters:

pop_data – [in] Proof of Possession (PoP) string

Returns:

  • ESP_OK

  • ESP_FAIL

esp_err_t espnow_sec_responder_stop()

Stop security process.

Returns:

  • ESP_OK

  • ESP_FAIL _cplusplus

Structures

struct espnow_sec_info_s

Security information.

Public Members

uint8_t type

ESPNOW_SEC_TYPE_REQUEST or ESPNOW_SEC_TYPE_INFO

uint8_t sec_ver

Security version

uint8_t client_mac[6]

Mac address of initiator

struct espnow_sec_responder_s

Responder security information.

Public Members

uint8_t mac[6]

Mac address of responder

int8_t rssi

Packet rssi

uint8_t channel

The channel of responder

uint8_t sec_ver

The security version of responder

struct espnow_sec_packet_s

Handshake packet.

Public Members

uint8_t type

Type of packet, ESPNOW_SEC_TYPE_HANDSHAKE

uint8_t size

Size

uint8_t data[0]

Message

struct espnow_sec_result_s

List of device status during the security process.

Public Members

size_t unfinished_num

The number of devices to be set key

espnow_addr_t *unfinished_addr

MAC address of devices to be set key

size_t successed_num

The number of devices that succeeded to set key

espnow_addr_t *successed_addr

MAC address of devices that succeeded to set key

size_t requested_num

Reserved

espnow_addr_t *requested_addr

Reserved

Type Definitions

typedef struct espnow_sec_info_s espnow_sec_info_t

Security information.

typedef struct espnow_sec_responder_s espnow_sec_responder_t

Responder security information.

typedef struct espnow_sec_packet_s espnow_sec_packet_t

Handshake packet.

typedef struct espnow_sec_result_s espnow_sec_result_t

List of device status during the security process.

Enumerations

enum espnow_sec_type_t

Type of packet.

< _cplusplus

Values:

enumerator ESPNOW_SEC_TYPE_REQUEST

Request security information

enumerator ESPNOW_SEC_TYPE_INFO

Security information

enumerator ESPNOW_SEC_TYPE_HANDSHAKE

Handshake packet to get key

enumerator ESPNOW_SEC_TYPE_KEY

Packet containing app key

enumerator ESPNOW_SEC_TYPE_KEY_RESP

Response to confirm gotten the app key

enumerator ESPNOW_SEC_TYPE_REST

Reset security information

enum espnow_sec_ver_type_t

Security version.

Values:

enumerator ESPNOW_SEC_VER_NONE

No security

enumerator ESPNOW_SEC_VER_V1_0

The default security version

enumerator ESPNOW_SEC_VER_V1_1

Used in the future