1 // Hardware crypto support Copyright 2017 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 16 #ifndef __ESP_WIFI_CRYPTO_TYPES_H__ 17 #define __ESP_WIFI_CRYPTO_TYPES_H__ 18 19 /* This is an internal API header for configuring the implementation used for WiFi cryptographic 20 operations. 21 22 During normal operation, you don't need to use any of these types or functions in this header. 23 See esp_wifi.h & esp_wifi_types.h instead. 24 */ 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 #define ESP_WIFI_CRYPTO_VERSION 0x00000001 31 32 /* 33 * Enumeration for hash operations. 34 * When WPA2 is connecting, this enum is used to 35 * request a hash algorithm via crypto_hash_xxx functions. 36 */ 37 typedef enum { 38 ESP_CRYPTO_HASH_ALG_MD5, ESP_CRYPTO_HASH_ALG_SHA1, 39 ESP_CRYPTO_HASH_ALG_HMAC_MD5, ESP_CRYPTO_HASH_ALG_HMAC_SHA1, 40 ESP_CRYPTO_HASH_ALG_SHA256, ESP_CRYPTO_HASH_ALG_HMAC_SHA256 41 }esp_crypto_hash_alg_t; 42 43 /* 44 * Enumeration for block cipher operations. 45 * When WPA2 is connecting, this enum is used to request a block 46 * cipher algorithm via crypto_cipher_xxx functions. 47 */ 48 typedef enum { 49 ESP_CRYPTO_CIPHER_NULL, ESP_CRYPTO_CIPHER_ALG_AES, ESP_CRYPTO_CIPHER_ALG_3DES, 50 ESP_CRYPTO_CIPHER_ALG_DES, ESP_CRYPTO_CIPHER_ALG_RC2, ESP_CRYPTO_CIPHER_ALG_RC4 51 } esp_crypto_cipher_alg_t; 52 53 /* 54 * This structure is about the algorithm when do crypto_hash operation, for detail, 55 * please reference to the structure crypto_hash. 56 */ 57 typedef struct crypto_hash esp_crypto_hash_t; 58 59 /* 60 * This structure is about the algorithm when do crypto_cipher operation, for detail, 61 * please reference to the structure crypto_cipher. 62 */ 63 typedef struct crypto_cipher esp_crypto_cipher_t; 64 65 /** 66 * @brief The AES callback function when do WPS connect. 67 * 68 * @param key Encryption key. 69 * @param iv Encryption IV for CBC mode (16 bytes). 70 * @param data Data to encrypt in-place. 71 * @param data_len Length of data in bytes (must be divisible by 16) 72 */ 73 typedef int (*esp_aes_128_encrypt_t)(const unsigned char *key, const unsigned char *iv, unsigned char *data, int data_len); 74 75 /** 76 * @brief The AES callback function when do WPS connect. 77 * 78 * @param key Decryption key. 79 * @param iv Decryption IV for CBC mode (16 bytes). 80 * @param data Data to decrypt in-place. 81 * @param data_len Length of data in bytes (must be divisible by 16) 82 * 83 */ 84 typedef int (*esp_aes_128_decrypt_t)(const unsigned char *key, const unsigned char *iv, unsigned char *data, int data_len); 85 86 /** 87 * @brief The AES callback function when do STA connect. 88 * 89 * @param kek 16-octet Key encryption key (KEK). 90 * @param n Length of the plaintext key in 64-bit units; 91 * @param plain Plaintext key to be wrapped, n * 64 bits 92 * @param cipher Wrapped key, (n + 1) * 64 bits 93 * 94 */ 95 typedef int (*esp_aes_wrap_t)(const unsigned char *kek, int n, const unsigned char *plain, unsigned char *cipher); 96 97 /** 98 * @brief The AES callback function when do STA connect. 99 * 100 * @param kek 16-octet Key decryption key (KEK). 101 * @param n Length of the plaintext key in 64-bit units; 102 * @param cipher Wrapped key to be unwrapped, (n + 1) * 64 bits 103 * @param plain Plaintext key, n * 64 bits 104 * 105 */ 106 typedef int (*esp_aes_unwrap_t)(const unsigned char *kek, int n, const unsigned char *cipher, unsigned char *plain); 107 108 /** 109 * @brief The SHA256 callback function when do WPS connect. 110 * 111 * @param key Key for HMAC operations. 112 * @param key_len Length of the key in bytes. 113 * @param num_elem Number of elements in the data vector. 114 * @param addr Pointers to the data areas. 115 * @param len Lengths of the data blocks. 116 * @param mac Buffer for the hash (32 bytes). 117 * 118 */ 119 typedef int (*esp_hmac_sha256_vector_t)(const unsigned char *key, int key_len, int num_elem, 120 const unsigned char *addr[], const int *len, unsigned char *mac); 121 122 /** 123 * @brief The AES callback function when do STA connect. 124 * 125 * @param key Key for PRF. 126 * @param key_len Length of the key in bytes. 127 * @param label A unique label for each purpose of the PRF. 128 * @param data Extra data to bind into the key. 129 * @param data_len Length of the data. 130 * @param buf Buffer for the generated pseudo-random key. 131 * @param buf_len Number of bytes of key to generate. 132 * 133 */ 134 typedef int (*esp_sha256_prf_t)(const unsigned char *key, int key_len, const char *label, 135 const unsigned char *data, int data_len, unsigned char *buf, int buf_len); 136 137 /** 138 * @brief HMAC-MD5 over data buffer (RFC 2104)' 139 * 140 * @key: Key for HMAC operations 141 * @key_len: Length of the key in bytes 142 * @data: Pointers to the data area 143 * @data_len: Length of the data area 144 * @mac: Buffer for the hash (16 bytes) 145 * Returns: 0 on success, -1 on failure 146 */ 147 typedef int (*esp_hmac_md5_t)(const unsigned char *key, unsigned int key_len, const unsigned char *data, 148 unsigned int data_len, unsigned char *mac); 149 150 /** 151 * @brief HMAC-MD5 over data vector (RFC 2104) 152 * 153 * @key: Key for HMAC operations 154 * @key_len: Length of the key in bytes 155 * @num_elem: Number of elements in the data vector 156 * @addr: Pointers to the data areas 157 * @len: Lengths of the data blocks 158 * @mac: Buffer for the hash (16 bytes) 159 * Returns: 0 on success, -1 on failure 160 */ 161 typedef int (*esp_hmac_md5_vector_t)(const unsigned char *key, unsigned int key_len, unsigned int num_elem, 162 const unsigned char *addr[], const unsigned int *len, unsigned char *mac); 163 164 /** 165 * @brief HMAC-SHA1 over data buffer (RFC 2104) 166 * 167 * @key: Key for HMAC operations 168 * @key_len: Length of the key in bytes 169 * @data: Pointers to the data area 170 * @data_len: Length of the data area 171 * @mac: Buffer for the hash (20 bytes) 172 * Returns: 0 on success, -1 of failure 173 */ 174 typedef int (*esp_hmac_sha1_t)(const unsigned char *key, unsigned int key_len, const unsigned char *data, 175 unsigned int data_len, unsigned char *mac); 176 177 /** 178 * @brief HMAC-SHA1 over data vector (RFC 2104) 179 * 180 * @key: Key for HMAC operations 181 * @key_len: Length of the key in bytes 182 * @num_elem: Number of elements in the data vector 183 * @addr: Pointers to the data areas 184 * @len: Lengths of the data blocks 185 * @mac: Buffer for the hash (20 bytes) 186 * Returns: 0 on success, -1 on failure 187 */ 188 typedef int (*esp_hmac_sha1_vector_t)(const unsigned char *key, unsigned int key_len, unsigned int num_elem, 189 const unsigned char *addr[], const unsigned int *len, unsigned char *mac); 190 191 /** 192 * @brief SHA1-based Pseudo-Random Function (PRF) (IEEE 802.11i, 8.5.1.1) 193 * 194 * @key: Key for PRF 195 * @key_len: Length of the key in bytes 196 * @label: A unique label for each purpose of the PRF 197 * @data: Extra data to bind into the key 198 * @data_len: Length of the data 199 * @buf: Buffer for the generated pseudo-random key 200 * @buf_len: Number of bytes of key to generate 201 * Returns: 0 on success, -1 of failure 202 * 203 * This function is used to derive new, cryptographically separate keys from a 204 * given key (e.g., PMK in IEEE 802.11i). 205 */ 206 typedef int (*esp_sha1_prf_t)(const unsigned char *key, unsigned int key_len, const char *label, 207 const unsigned char *data, unsigned int data_len, unsigned char *buf, unsigned int buf_len); 208 209 /** 210 * @brief SHA-1 hash for data vector 211 * 212 * @num_elem: Number of elements in the data vector 213 * @addr: Pointers to the data areas 214 * @len: Lengths of the data blocks 215 * @mac: Buffer for the hash 216 * Returns: 0 on success, -1 on failure 217 */ 218 typedef int (*esp_sha1_vector_t)(unsigned int num_elem, const unsigned char *addr[], const unsigned int *len, 219 unsigned char *mac); 220 221 /** 222 * @brief SHA1-based key derivation function (PBKDF2) for IEEE 802.11i 223 * 224 * @passphrase: ASCII passphrase 225 * @ssid: SSID 226 * @ssid_len: SSID length in bytes 227 * @iterations: Number of iterations to run 228 * @buf: Buffer for the generated key 229 * @buflen: Length of the buffer in bytes 230 * Returns: 0 on success, -1 of failure 231 * 232 * This function is used to derive PSK for WPA-PSK. For this protocol, 233 * iterations is set to 4096 and buflen to 32. This function is described in 234 * IEEE Std 802.11-2004, Clause H.4. The main construction is from PKCS#5 v2.0. 235 */ 236 typedef int (*esp_pbkdf2_sha1_t)(const char *passphrase, const char *ssid, unsigned int ssid_len, 237 int iterations, unsigned char *buf, unsigned int buflen); 238 239 /** 240 * @brief XOR RC4 stream to given data with skip-stream-start 241 * 242 * @key: RC4 key 243 * @keylen: RC4 key length 244 * @skip: number of bytes to skip from the beginning of the RC4 stream 245 * @data: data to be XOR'ed with RC4 stream 246 * @data_len: buf length 247 * Returns: 0 on success, -1 on failure 248 * 249 * Generate RC4 pseudo random stream for the given key, skip beginning of the 250 * stream, and XOR the end result with the data buffer to perform RC4 251 * encryption/decryption. 252 */ 253 typedef int (*esp_rc4_skip_t)(const unsigned char *key, unsigned int keylen, unsigned int skip, 254 unsigned char *data, unsigned int data_len); 255 256 /** 257 * @brief MD5 hash for data vector 258 * 259 * @num_elem: Number of elements in the data vector 260 * @addr: Pointers to the data areas 261 * @len: Lengths of the data blocks 262 * @mac: Buffer for the hash 263 * Returns: 0 on success, -1 on failure 264 */ 265 typedef int (*esp_md5_vector_t)(unsigned int num_elem, const unsigned char *addr[], const unsigned int *len, 266 unsigned char *mac); 267 268 /** 269 * @brief Encrypt one AES block 270 * 271 * @ctx: Context pointer from aes_encrypt_init() 272 * @plain: Plaintext data to be encrypted (16 bytes) 273 * @crypt: Buffer for the encrypted data (16 bytes) 274 */ 275 typedef void (*esp_aes_encrypt_t)(void *ctx, const unsigned char *plain, unsigned char *crypt); 276 277 /** 278 * @brief Initialize AES for encryption 279 * 280 * @key: Encryption key 281 * @len: Key length in bytes (usually 16, i.e., 128 bits) 282 * Returns: Pointer to context data or %NULL on failure 283 */ 284 typedef void * (*esp_aes_encrypt_init_t)(const unsigned char *key, unsigned int len); 285 286 /** 287 * @brief Deinitialize AES encryption 288 * 289 * @ctx: Context pointer from aes_encrypt_init() 290 */ 291 typedef void (*esp_aes_encrypt_deinit_t)(void *ctx); 292 293 /** 294 * @brief Decrypt one AES block 295 * 296 * @ctx: Context pointer from aes_encrypt_init() 297 * @crypt: Encrypted data (16 bytes) 298 * @plain: Buffer for the decrypted data (16 bytes) 299 */ 300 typedef void (*esp_aes_decrypt_t)(void *ctx, const unsigned char *crypt, unsigned char *plain); 301 302 /** 303 * @brief Initialize AES for decryption 304 * 305 * @key: Decryption key 306 * @len: Key length in bytes (usually 16, i.e., 128 bits) 307 * Returns: Pointer to context data or %NULL on failure 308 */ 309 typedef void * (*esp_aes_decrypt_init_t)(const unsigned char *key, unsigned int len); 310 311 /** 312 * @brief Deinitialize AES decryption 313 * 314 * @ctx: Context pointer from aes_encrypt_init() 315 */ 316 typedef void (*esp_aes_decrypt_deinit_t)(void *ctx); 317 318 /** 319 * @brief One-Key CBC MAC (OMAC1) hash with AES-128 for MIC computation 320 * 321 * @key: 128-bit key for the hash operation 322 * @data: Data buffer for which a MIC is computed 323 * @data_len: Length of data buffer in bytes 324 * @mic: Buffer for MIC (128 bits, i.e., 16 bytes) 325 * Returns: 0 on success, -1 on failure 326 */ 327 typedef int (*esp_omac1_aes_128_t)(const uint8_t *key, const uint8_t *data, size_t data_len, 328 uint8_t *mic); 329 330 /** 331 * @brief Decrypt data using CCMP (Counter Mode CBC-MAC Protocol OR 332 * Counter Mode Cipher Block Chaining Message Authentication 333 * Code Protocol) which is used in IEEE 802.11i RSN standard. 334 * @tk: 128-bit Temporal Key for obtained during 4-way handshake 335 * @hdr: Pointer to IEEE802.11 frame headeri needed for AAD 336 * @data: Pointer to encrypted data buffer 337 * @data_len: Encrypted data length in bytes 338 * @decrypted_len: Length of decrypted data 339 * @espnow_pkt: Indicates if it's an ESPNOW packet 340 * Returns: Pointer to decrypted data on success, NULL on failure 341 */ 342 typedef uint8_t * (*esp_ccmp_decrypt_t)(const uint8_t *tk, const uint8_t *ieee80211_hdr, 343 const uint8_t *data, size_t data_len, 344 size_t *decrypted_len, bool espnow_pkt); 345 346 /** 347 * @brief Encrypt data using CCMP (Counter Mode CBC-MAC Protocol OR 348 * Counter Mode Cipher Block Chaining Message Authentication 349 * Code Protocol) which is used in IEEE 802.11i RSN standard. 350 * @tk: 128-bit Temporal Key for obtained during 4-way handshake 351 * @frame: Pointer to IEEE802.11 frame including header 352 * @len: Length of the frame including header 353 * @hdrlen: Length of the header 354 * @pn: Packet Number counter 355 * @keyid: Key ID to be mentioned in CCMP Vector 356 * @encrypted_len: Length of the encrypted frame including header 357 */ 358 typedef uint8_t * (*esp_ccmp_encrypt_t)(const uint8_t *tk, uint8_t *frame, size_t len, size_t hdrlen, 359 uint8_t *pn, int keyid, size_t *encrypted_len); 360 361 /** 362 * @brief The crypto callback function structure used when do station security connect. 363 * The structure can be set as software crypto or the crypto optimized by ESP32 364 * hardware. 365 */ 366 typedef struct { 367 uint32_t size; 368 uint32_t version; 369 esp_aes_wrap_t aes_wrap; /**< station connect function used when send EAPOL frame */ 370 esp_aes_unwrap_t aes_unwrap; /**< station connect function used when decrypt key data */ 371 esp_hmac_sha256_vector_t hmac_sha256_vector; /**< station connect function used when check MIC */ 372 esp_sha256_prf_t sha256_prf; /**< station connect function used when check MIC */ 373 esp_hmac_md5_t hmac_md5; 374 esp_hmac_md5_vector_t hamc_md5_vector; 375 esp_hmac_sha1_t hmac_sha1; 376 esp_hmac_sha1_vector_t hmac_sha1_vector; 377 esp_sha1_prf_t sha1_prf; 378 esp_sha1_vector_t sha1_vector; 379 esp_pbkdf2_sha1_t pbkdf2_sha1; 380 esp_rc4_skip_t rc4_skip; 381 esp_md5_vector_t md5_vector; 382 esp_aes_encrypt_t aes_encrypt; 383 esp_aes_encrypt_init_t aes_encrypt_init; 384 esp_aes_encrypt_deinit_t aes_encrypt_deinit; 385 esp_aes_decrypt_t aes_decrypt; 386 esp_aes_decrypt_init_t aes_decrypt_init; 387 esp_aes_decrypt_deinit_t aes_decrypt_deinit; 388 esp_aes_128_encrypt_t aes_128_encrypt; 389 esp_aes_128_decrypt_t aes_128_decrypt; 390 esp_omac1_aes_128_t omac1_aes_128; 391 esp_ccmp_decrypt_t ccmp_decrypt; 392 esp_ccmp_encrypt_t ccmp_encrypt; 393 }wpa_crypto_funcs_t; 394 395 /** 396 * @brief The crypto callback function structure used in mesh vendor IE encryption. The 397 * structure can be set as software crypto or the crypto optimized by ESP32 398 * hardware. 399 */ 400 typedef struct{ 401 esp_aes_128_encrypt_t aes_128_encrypt; /**< function used in mesh vendor IE encryption */ 402 esp_aes_128_decrypt_t aes_128_decrypt; /**< function used in mesh vendor IE decryption */ 403 } mesh_crypto_funcs_t; 404 405 #ifdef __cplusplus 406 } 407 #endif 408 #endif 409