update(wifi): update esp_wifi_crypto_types.h

components/esp_wifi/include/esp_wifi_crypto_types.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2017-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2017-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -129,11 +129,11 @@ typedef int (*esp_sha256_prf_t)(const unsigned char *key, int key_len, const cha
 /**
  * @brief HMAC-MD5 over data buffer (RFC 2104)'
  *
- * @key: Key for HMAC operations
- * @key_len: Length of the key in bytes
- * @data: Pointers to the data area
- * @data_len: Length of the data area
- * @mac: Buffer for the hash (16 bytes)
+ * @param key Key for HMAC operations
+ * @param key_len Length of the key in bytes
+ * @param dataPointers to the data area
+ * @param data_len Length of the data area
+ * @param mac Buffer for the hash (16 bytes)
  * Returns: 0 on success, -1 on failure
  */
 typedef int (*esp_hmac_md5_t)(const unsigned char *key, unsigned int key_len, const unsigned char *data,
@@ -142,12 +142,12 @@ typedef int (*esp_hmac_md5_t)(const unsigned char *key, unsigned int key_len, co
 /**
  * @brief HMAC-MD5 over data vector (RFC 2104)
  *
- * @key: Key for HMAC operations
- * @key_len: Length of the key in bytes
- * @num_elem: Number of elements in the data vector
- * @addr: Pointers to the data areas
- * @len: Lengths of the data blocks
- * @mac: Buffer for the hash (16 bytes)
+ * @param key Key for HMAC operations
+ * @param key_len Length of the key in bytes
+ * @param num_elem Number of elements in the data vector
+ * @param addr Pointers to the data areas
+ * @param len Lengths of the data blocks
+ * @param mac Buffer for the hash (16 bytes)
  * Returns: 0 on success, -1 on failure
  */
 typedef int (*esp_hmac_md5_vector_t)(const unsigned char *key, unsigned int key_len, unsigned int num_elem,
@@ -156,11 +156,11 @@ typedef int (*esp_hmac_md5_vector_t)(const unsigned char *key, unsigned int key_
 /**
  * @brief HMAC-SHA1 over data buffer (RFC 2104)
  *
- * @key: Key for HMAC operations
- * @key_len: Length of the key in bytes
- * @data: Pointers to the data area
- * @data_len: Length of the data area
- * @mac: Buffer for the hash (20 bytes)
+ * @param key Key for HMAC operations
+ * @param key_len Length of the key in bytes
+ * @param data Pointers to the data area
+ * @param data_len Length of the data area
+ * @param mac Buffer for the hash (20 bytes)
  * Returns: 0 on success, -1 of failure
  */
 typedef int (*esp_hmac_sha1_t)(const unsigned char *key, unsigned int key_len, const unsigned char *data,
@@ -169,12 +169,12 @@ typedef int (*esp_hmac_sha1_t)(const unsigned char *key, unsigned int key_len, c
 /**
  * @brief HMAC-SHA1 over data vector (RFC 2104)
  *
- * @key: Key for HMAC operations
- * @key_len: Length of the key in bytes
- * @num_elem: Number of elements in the data vector
- * @addr: Pointers to the data areas
- * @len: Lengths of the data blocks
- * @mac: Buffer for the hash (20 bytes)
+ * @param key Key for HMAC operations
+ * @param key_len Length of the key in bytes
+ * @param num_elem Number of elements in the data vector
+ * @param addr Pointers to the data areas
+ * @param len Lengths of the data blocks
+ * @param mac Buffer for the hash (20 bytes)
  * Returns: 0 on success, -1 on failure
  */
 typedef int (*esp_hmac_sha1_vector_t)(const unsigned char *key, unsigned int key_len, unsigned int num_elem,
@@ -183,13 +183,13 @@ typedef int (*esp_hmac_sha1_vector_t)(const unsigned char *key, unsigned int key
 /**
  * @brief SHA1-based Pseudo-Random Function (PRF) (IEEE 802.11i, 8.5.1.1)
  *
- * @key: Key for PRF
- * @key_len: Length of the key in bytes
- * @label: A unique label for each purpose of the PRF
- * @data: Extra data to bind into the key
- * @data_len: Length of the data
- * @buf: Buffer for the generated pseudo-random key
- * @buf_len: Number of bytes of key to generate
+ * @param key Key for PRF
+ * @param key_len Length of the key in bytes
+ * @param label A unique label for each purpose of the PRF
+ * @param data Extra data to bind into the key
+ * @param data_len Length of the data
+ * @param buf Buffer for the generated pseudo-random key
+ * @param buf_len Number of bytes of key to generate
  * Returns: 0 on success, -1 of failure
  *
  * This function is used to derive new, cryptographically separate keys from a
@@ -201,10 +201,10 @@ typedef int (*esp_sha1_prf_t)(const unsigned char *key, unsigned int key_len, co
 /**
  * @brief SHA-1 hash for data vector
  *
- * @num_elem: Number of elements in the data vector
- * @addr: Pointers to the data areas
- * @len: Lengths of the data blocks
- * @mac: Buffer for the hash
+ * @param num_elem Number of elements in the data vector
+ * @param addr Pointers to the data areas
+ * @param len Lengths of the data blocks
+ * @param mac Buffer for the hash
  * Returns: 0 on success, -1 on failure
  */
 typedef int (*esp_sha1_vector_t)(unsigned int num_elem, const unsigned char *addr[], const unsigned int *len,
@@ -213,12 +213,12 @@ typedef int (*esp_sha1_vector_t)(unsigned int num_elem, const unsigned char *add
 /**
  * @brief SHA1-based key derivation function (PBKDF2) for IEEE 802.11i
  *
- * @passphrase: ASCII passphrase
- * @ssid: SSID
- * @ssid_len: SSID length in bytes
- * @iterations: Number of iterations to run
- * @buf: Buffer for the generated key
- * @buflen: Length of the buffer in bytes
+ * @param passphrase ASCII passphrase
+ * @param ssid SSID
+ * @param ssid_len SSID length in bytes
+ * @param iterations Number of iterations to run
+ * @param buf Buffer for the generated key
+ * @param buflen Length of the buffer in bytes
  * Returns: 0 on success, -1 of failure
  *
  * This function is used to derive PSK for WPA-PSK. For this protocol,
@@ -231,11 +231,11 @@ typedef int (*esp_pbkdf2_sha1_t)(const char *passphrase, const char *ssid, unsig
 /**
  * @brief XOR RC4 stream to given data with skip-stream-start
  *
- * @key: RC4 key
- * @keylen: RC4 key length
- * @skip: number of bytes to skip from the beginning of the RC4 stream
- * @data: data to be XOR'ed with RC4 stream
- * @data_len: buf length
+ * @param key RC4 key
+ * @param keylen RC4 key length
+ * @param skip number of bytes to skip from the beginning of the RC4 stream
+ * @param data data to be XOR'ed with RC4 stream
+ * @param data_len buf length
  * Returns: 0 on success, -1 on failure
  *
  * Generate RC4 pseudo random stream for the given key, skip beginning of the
@@ -248,10 +248,10 @@ typedef int (*esp_rc4_skip_t)(const unsigned char *key, unsigned int keylen, uns
 /**
  * @brief MD5 hash for data vector
  *
- * @num_elem: Number of elements in the data vector
- * @addr: Pointers to the data areas
- * @len: Lengths of the data blocks
- * @mac: Buffer for the hash
+ * @param num_elem Number of elements in the data vector
+ * @param addr Pointers to the data areas
+ * @param len Lengths of the data blocks
+ * @param mac Buffer for the hash
  * Returns: 0 on success, -1 on failure
  */
 typedef int (*esp_md5_vector_t)(unsigned int num_elem, const unsigned char *addr[], const unsigned int *len,
@@ -260,17 +260,17 @@ typedef int (*esp_md5_vector_t)(unsigned int num_elem, const unsigned char *addr
 /**
  * @brief Encrypt one AES block
  *
- * @ctx: Context pointer from aes_encrypt_init()
- * @plain: Plaintext data to be encrypted (16 bytes)
- * @crypt: Buffer for the encrypted data (16 bytes)
+ * @param ctx Context pointer from aes_encrypt_init()
+ * @param plain Plaintext data to be encrypted (16 bytes)
+ * @param crypt Buffer for the encrypted data (16 bytes)
  */
 typedef void (*esp_aes_encrypt_t)(void *ctx, const unsigned char *plain, unsigned char *crypt);
 
 /**
  * @brief Initialize AES for encryption
  *
- * @key: Encryption key
- * @len: Key length in bytes (usually 16, i.e., 128 bits)
+ * @param key Encryption key
+ * @param len Key length in bytes (usually 16, i.e., 128 bits)
  * Returns: Pointer to context data or %NULL on failure
  */
 typedef void * (*esp_aes_encrypt_init_t)(const unsigned char *key,  unsigned int len);
@@ -278,24 +278,24 @@ typedef void * (*esp_aes_encrypt_init_t)(const unsigned char *key,  unsigned int
 /**
  * @brief Deinitialize AES encryption
  *
- * @ctx: Context pointer from aes_encrypt_init()
+ * @param ctx Context pointer from aes_encrypt_init()
  */
 typedef void (*esp_aes_encrypt_deinit_t)(void *ctx);
 
 /**
  * @brief Decrypt one AES block
  *
- * @ctx: Context pointer from aes_encrypt_init()
- * @crypt: Encrypted data (16 bytes)
- * @plain: Buffer for the decrypted data (16 bytes)
+ * @param ctx Context pointer from aes_encrypt_init()
+ * @param crypt Encrypted data (16 bytes)
+ * @param plain Buffer for the decrypted data (16 bytes)
  */
 typedef void (*esp_aes_decrypt_t)(void *ctx, const unsigned char *crypt, unsigned char *plain);
 
 /**
  * @brief Initialize AES for decryption
  *
- * @key: Decryption key
- * @len: Key length in bytes (usually 16, i.e., 128 bits)
+ * @param key Decryption key
+ * @param len Key length in bytes (usually 16, i.e., 128 bits)
  * Returns: Pointer to context data or %NULL on failure
  */
 typedef void * (*esp_aes_decrypt_init_t)(const unsigned char *key, unsigned int len);
@@ -303,17 +303,17 @@ typedef void * (*esp_aes_decrypt_init_t)(const unsigned char *key, unsigned int
 /**
  * @brief Deinitialize AES decryption
  *
- * @ctx: Context pointer from aes_encrypt_init()
+ * @param ctx Context pointer from aes_encrypt_init()
  */
 typedef void (*esp_aes_decrypt_deinit_t)(void *ctx);
 
 /**
  * @brief One-Key CBC MAC (OMAC1) hash with AES-128 for MIC computation
  *
- * @key: 128-bit key for the hash operation
- * @data: Data buffer for which a MIC is computed
- * @data_len: Length of data buffer in bytes
- * @mic: Buffer for MIC (128 bits, i.e., 16 bytes)
+ * @param key 128-bit key for the hash operation
+ * @param data Data buffer for which a MIC is computed
+ * @param data_len Length of data buffer in bytes
+ * @param mic Buffer for MIC (128 bits, i.e., 16 bytes)
  * Returns: 0 on success, -1 on failure
  */
 typedef int (*esp_omac1_aes_128_t)(const uint8_t *key, const uint8_t *data, size_t data_len,
@@ -323,12 +323,12 @@ typedef int (*esp_omac1_aes_128_t)(const uint8_t *key, const uint8_t *data, size
  * @brief Decrypt data using CCMP (Counter Mode CBC-MAC Protocol OR
  *        Counter Mode Cipher Block Chaining Message Authentication
  *        Code Protocol) which is used in IEEE 802.11i RSN standard.
- * @tk: 128-bit Temporal Key for obtained during 4-way handshake
- * @hdr: Pointer to IEEE802.11 frame headeri needed for AAD
- * @data: Pointer to encrypted data buffer
- * @data_len: Encrypted data length in bytes
- * @decrypted_len: Length of decrypted data
- * @espnow_pkt: Indicates if it's an ESPNOW packet
+ * @param tk 128-bit Temporal Key for obtained during 4-way handshake
+ * @param hdr Pointer to IEEE802.11 frame headeri needed for AAD
+ * @param data Pointer to encrypted data buffer
+ * @param data_len Encrypted data length in bytes
+ * @param decrypted_len Length of decrypted data
+ * @param espnow_pkt Indicates if it's an ESPNOW packet
  * Returns: Pointer to decrypted data on success, NULL on failure
  */
 typedef uint8_t * (*esp_ccmp_decrypt_t)(const uint8_t *tk, const uint8_t *ieee80211_hdr,
@@ -339,13 +339,13 @@ typedef uint8_t * (*esp_ccmp_decrypt_t)(const uint8_t *tk, const uint8_t *ieee80
  * @brief Encrypt data using CCMP (Counter Mode CBC-MAC Protocol OR
  *        Counter Mode Cipher Block Chaining Message Authentication
  *        Code Protocol) which is used in IEEE 802.11i RSN standard.
- * @tk: 128-bit Temporal Key for obtained during 4-way handshake
- * @frame: Pointer to IEEE802.11 frame including header
- * @len: Length of the frame including header
- * @hdrlen: Length of the header
- * @pn: Packet Number counter
- * @keyid: Key ID to be mentioned in CCMP Vector
- * @encrypted_len: Length of the encrypted frame including header
+ * @param tk 128-bit Temporal Key for obtained during 4-way handshake
+ * @param frame Pointer to IEEE802.11 frame including header
+ * @param len Length of the frame including header
+ * @param hdrlen Length of the header
+ * @param pn Packet Number counter
+ * @param keyid Key ID to be mentioned in CCMP Vector
+ * @param encrypted_len Length of the encrypted frame including header
  */
 typedef uint8_t * (*esp_ccmp_encrypt_t)(const uint8_t *tk, uint8_t *frame, size_t len, size_t hdrlen,
                                         uint8_t *pn, int keyid, size_t *encrypted_len);
@@ -353,13 +353,13 @@ typedef uint8_t * (*esp_ccmp_encrypt_t)(const uint8_t *tk, uint8_t *frame, size_
 /**
  * @brief One-Key GMAC hash with AES for MIC computation
  *
- * @key: key for the hash operation
- * @keylen: key length
- * @iv: initialization vector
- * @iv_len: initialization vector length
- * @aad: aad
- * @aad_len: aad length
- * @mic: Buffer for MIC (128 bits, i.e., 16 bytes)
+ * @param key key for the hash operation
+ * @param keylen key length
+ * @param iv initialization vector
+ * @param iv_len initialization vector length
+ * @param aad aad
+ * @param aad_len aad length
+ * @param mic Buffer for MIC (128 bits, i.e., 16 bytes)
  * Returns: 0 on success, -1 on failure
  */
 typedef int (*esp_aes_gmac_t)(const uint8_t *key, size_t keylen, const uint8_t *iv, size_t iv_len,
@@ -367,10 +367,10 @@ typedef int (*esp_aes_gmac_t)(const uint8_t *key, size_t keylen, const uint8_t *
 
 /**
  * @brief SHA256 hash for data vector
- * @num_elem: Number of elements in the data vector
- * @addr: Pointers to the data areas
- * @len: Lengths of the data blocks
- * @mac: Buffer for the hash
+ * @param num_elem Number of elements in the data vector
+ * @param addr Pointers to the data areas
+ * @param len Lengths of the data blocks
+ * @param mac Buffer for the hash
  * Returns: 0 on success, -1 on failure
  */
 typedef int (*esp_sha256_vector_t)(size_t num_elem, const uint8_t *addr[], const size_t *len, uint8_t *buf);
@@ -378,9 +378,9 @@ typedef int (*esp_sha256_vector_t)(size_t num_elem, const uint8_t *addr[], const
 /**
  * @brief CRC32 value in little endian.
  *
- * @param crc: Initial CRC value (result of last calculation or 0 for the first time)
- * @param buf: Data buffer that used to calculate the CRC value
- * @param len: Length of the data buffer
+ * @param crc Initial CRC value (result of last calculation or 0 for the first time)
+ * @param buf Data buffer that used to calculate the CRC value
+ * @param len Length of the data buffer
  * @return CRC32 value
  */
 typedef uint32_t (*esp_crc32_le_t)(uint32_t crc, uint8_t const *buf, uint32_t len);
@@ -391,35 +391,35 @@ typedef uint32_t (*esp_crc32_le_t)(uint32_t crc, uint8_t const *buf, uint32_t le
   *        hardware.
   */
 typedef struct {
-    uint32_t size;
-    uint32_t version;
-    esp_aes_wrap_t aes_wrap;                         /**< station connect function used when send EAPOL frame */
-    esp_aes_unwrap_t aes_unwrap;                     /**< station connect function used when decrypt key data */
-    esp_hmac_sha256_vector_t hmac_sha256_vector;     /**< station connect function used when check MIC */
-    esp_sha256_prf_t sha256_prf;                     /**< station connect function used when check MIC */
-    esp_hmac_md5_t hmac_md5;
-    esp_hmac_md5_vector_t hamc_md5_vector;
-    esp_hmac_sha1_t hmac_sha1;
-    esp_hmac_sha1_vector_t hmac_sha1_vector;
-    esp_sha1_prf_t sha1_prf;
-    esp_sha1_vector_t sha1_vector;
-    esp_pbkdf2_sha1_t pbkdf2_sha1;
-    esp_rc4_skip_t rc4_skip;
-    esp_md5_vector_t md5_vector;
-    esp_aes_encrypt_t aes_encrypt;
-    esp_aes_encrypt_init_t aes_encrypt_init;
-    esp_aes_encrypt_deinit_t aes_encrypt_deinit;
-    esp_aes_decrypt_t aes_decrypt;
-    esp_aes_decrypt_init_t aes_decrypt_init;
-    esp_aes_decrypt_deinit_t aes_decrypt_deinit;
-    esp_aes_128_encrypt_t aes_128_encrypt;
-    esp_aes_128_decrypt_t aes_128_decrypt;
-    esp_omac1_aes_128_t omac1_aes_128;
-    esp_ccmp_decrypt_t ccmp_decrypt;
-    esp_ccmp_encrypt_t ccmp_encrypt;
-    esp_aes_gmac_t aes_gmac;
-    esp_sha256_vector_t sha256_vector;
-    esp_crc32_le_t crc32;
+    uint32_t size;                                   /**< The crypto callback function structure size */
+    uint32_t version;                                /**< The crypto callback function structure version */
+    esp_aes_wrap_t aes_wrap;                         /**< The AES callback function when do STA connect */
+    esp_aes_unwrap_t aes_unwrap;                     /**< The AES callback function when do STA connect */
+    esp_hmac_sha256_vector_t hmac_sha256_vector;     /**< The SHA256 callback function when do WPS connect */
+    esp_sha256_prf_t sha256_prf;                     /**< The AES callback function when do STA connect */
+    esp_hmac_md5_t hmac_md5;                         /**< HMAC-MD5 over data buffer (RFC 2104) */
+    esp_hmac_md5_vector_t hamc_md5_vector;           /**< HMAC-MD5 over data vector (RFC 2104) */
+    esp_hmac_sha1_t hmac_sha1;                       /**< HMAC-SHA1 over data buffer (RFC 2104) */
+    esp_hmac_sha1_vector_t hmac_sha1_vector;         /**< HMAC-SHA1 over data vector (RFC 2104) */
+    esp_sha1_prf_t sha1_prf;                         /**< SHA1-based Pseudo-Random Function (PRF) (IEEE 802.11i, 8.5.1.1) */
+    esp_sha1_vector_t sha1_vector;                   /**< SHA-1 hash for data vector */
+    esp_pbkdf2_sha1_t pbkdf2_sha1;                   /**< SHA1-based key derivation function (PBKDF2) for IEEE 802.11i */
+    esp_rc4_skip_t rc4_skip;                         /**< XOR RC4 stream to given data with skip-stream-start */
+    esp_md5_vector_t md5_vector;                     /**< MD5 hash for data vector */
+    esp_aes_encrypt_t aes_encrypt;                   /**< Encrypt one AES block */
+    esp_aes_encrypt_init_t aes_encrypt_init;         /**< Initialize AES for encryption */
+    esp_aes_encrypt_deinit_t aes_encrypt_deinit;     /**< Deinitialize AES encryption */
+    esp_aes_decrypt_t aes_decrypt;                   /**< Decrypt one AES block */
+    esp_aes_decrypt_init_t aes_decrypt_init;         /**< Initialize AES for decryption */
+    esp_aes_decrypt_deinit_t aes_decrypt_deinit;     /**< Deinitialize AES decryption */
+    esp_aes_128_encrypt_t aes_128_encrypt;           /**< The AES callback function when do WPS connect */
+    esp_aes_128_decrypt_t aes_128_decrypt;           /**< The AES callback function when do WPS connect */
+    esp_omac1_aes_128_t omac1_aes_128;               /**< One-Key CBC MAC (OMAC1) hash with AES-128 for MIC computation */
+    esp_ccmp_decrypt_t ccmp_decrypt;                 /**< Decrypt data using CCMP */
+    esp_ccmp_encrypt_t ccmp_encrypt;                 /**< encrypt data using CCMP */
+    esp_aes_gmac_t aes_gmac;                         /**< One-Key GMAC hash with AES for MIC computation */
+    esp_sha256_vector_t sha256_vector;               /**< SHA256 hash for data vector */
+    esp_crc32_le_t crc32;                            /**< CRC32 value in little endian */
 }wpa_crypto_funcs_t;
 
 /**