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
-
int state
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.