Security API

Security layer related APIs for ESP-NOW.

API Reference

Header File

Functions

esp_err_t espnow_sec_init(espnow_sec_t *sec)

Initialize the specified security info.

  • ESP_OK

  • ESP_ERR_INVALID_ARG

Parameters:

sec – [in] the security info to initialize. This must not be NULL.

esp_err_t espnow_sec_deinit(espnow_sec_t *sec)

Clear the specified security info.

  • ESP_OK

  • ESP_ERR_INVALID_ARG

Parameters:

sec – [in] the security info to clear. This must not be NULL.

esp_err_t espnow_sec_setkey(espnow_sec_t *sec, uint8_t app_key[APP_KEY_LEN])

Set the security key info.

  • ESP_OK

  • ESP_ERR_INVALID_ARG

Parameters:
  • sec – [in] the security info to set.

  • app_key – [in] raw key info used to set encryption key and iv.

esp_err_t espnow_sec_auth_encrypt(espnow_sec_t *sec, const uint8_t *input, size_t ilen, uint8_t *output, size_t output_len, size_t *olen, size_t tag_len)

The authenticated encryption function. Encryption with 128 bit AES-CCM.

Note

the tag will be appended to the ciphertext

Parameters:
  • sec – [in] the security info used for encryption.

  • input – [in] the buffer for the input data

  • ilen – [in] the length of the input data

  • output – [out] the buffer for the output data

  • output_len – [in] the length of the output buffer in bytes

  • olen – [out] the actual number of bytes written to the output buffer

  • tag_len – [in] the desired length of the authentication tag

Returns:

  • ESP_OK

  • ESP_FAIL

esp_err_t espnow_sec_auth_decrypt(espnow_sec_t *sec, const uint8_t *input, size_t ilen, uint8_t *output, size_t output_len, size_t *olen, size_t tag_len)

The authenticated decryption function. Decryption with 128 bit AES-CCM.

Note

the tag must be appended to the ciphertext

Note

An authentication failure (wrong tag, wrong key) is reported only through the return value and is not logged by this function, because a forged frame can produce it at wire rate; the caller decides how to report it. Other failures are logged.

Parameters:
  • sec – [in] the security info used for encryption.

  • input – [in] the buffer for the input data

  • ilen – [in] the length of the input data

  • output – [out] the buffer for the output data

  • output_len – [in] the length of the output buffer in bytes

  • olen – [out] the actual number of bytes written to the output buffer

  • tag_len – [in] the desired length of the authentication tag

Returns:

  • ESP_OK

  • ESP_FAIL _cplusplus

Structures

struct espnow_sec_s

Struct of security.

Public Members

int state

State defined by espnow_sec_state_t

uint8_t key[KEY_LEN]

Secret key

uint8_t iv[IV_LEN]

The initialization vector (nonce)

uint8_t key_len

Secret key length

uint8_t iv_len

The initialization vector (nonce) length

uint8_t tag_len

The length of the authentication field

void *cipher_ctx

The cipher context

Macros

APP_KEY_LEN

AES-128-CCM parameters: 4-byte tag (forgery 2^-32 per attempt) and 8-byte random nonce (may repeat near 2^32 frames). Rotate the key before 2^32 frames and never act irreversibly on a single frame.

< _cplusplus Exchanged key length

KEY_LEN

Secret key length

IV_LEN

The initialization vector (nonce) length

TAG_LEN

The length of the authentication field

ESPNOW_SEC_PACKET_MAX_SIZE

Maximum length of a single encrypted packet transmitted

ESP_EVENT_ESPNOW_SEC_OK
ESP_EVENT_ESPNOW_SEC_FAIL

Type Definitions

typedef struct espnow_sec_s espnow_sec_t

Struct of security.

Enumerations

enum espnow_sec_state_t

State of security.

Values:

enumerator ESPNOW_SEC_UNFINISHED

Security handshake is not finished

enumerator ESPNOW_SEC_OVER

Security handshake is over and APP key is received