1 /* 2 * WPA Supplicant / wrapper functions for crypto libraries 3 * Copyright (c) 2004-2009, Jouni Malinen <j@w1.fi> 4 * 5 * This program is free software; you can redistribute it and/or modify 6 * it under the terms of the GNU General Public License version 2 as 7 * published by the Free Software Foundation. 8 * 9 * Alternatively, this software may be distributed under the terms of BSD 10 * license. 11 * 12 * See README and COPYING for more details. 13 * 14 * This file defines the cryptographic functions that need to be implemented 15 * for wpa_supplicant and hostapd. When TLS is not used, internal 16 * implementation of MD5, SHA1, and AES is used and no external libraries are 17 * required. When TLS is enabled (e.g., by enabling EAP-TLS or EAP-PEAP), the 18 * crypto library used by the TLS implementation is expected to be used for 19 * non-TLS needs, too, in order to save space by not implementing these 20 * functions twice. 21 * 22 * Wrapper code for using each crypto library is in its own file (crypto*.c) 23 * and one of these files is build and linked in to provide the functions 24 * defined here. 25 */ 26 27 #ifndef CRYPTO_H 28 #define CRYPTO_H 29 30 /** 31 * md4_vector - MD4 hash for data vector 32 * @num_elem: Number of elements in the data vector 33 * @addr: Pointers to the data areas 34 * @len: Lengths of the data blocks 35 * @mac: Buffer for the hash 36 * Returns: 0 on success, -1 on failure 37 */ 38 int md4_vector(size_t num_elem, const u8 *addr[], const size_t *len, u8 *mac); 39 40 /** 41 * md5_vector - MD5 hash for data vector 42 * @num_elem: Number of elements in the data vector 43 * @addr: Pointers to the data areas 44 * @len: Lengths of the data blocks 45 * @mac: Buffer for the hash 46 * Returns: 0 on success, -1 on failure 47 */ 48 int md5_vector(size_t num_elem, const u8 *addr[], const size_t *len, u8 *mac); 49 50 #ifdef CONFIG_FIPS 51 /** 52 * md5_vector_non_fips_allow - MD5 hash for data vector (non-FIPS use allowed) 53 * @num_elem: Number of elements in the data vector 54 * @addr: Pointers to the data areas 55 * @len: Lengths of the data blocks 56 * @mac: Buffer for the hash 57 * Returns: 0 on success, -1 on failure 58 */ 59 int md5_vector_non_fips_allow(size_t num_elem, const u8 *addr[], 60 const size_t *len, u8 *mac); 61 #else /* CONFIG_FIPS */ 62 #define md5_vector_non_fips_allow md5_vector 63 #endif /* CONFIG_FIPS */ 64 65 66 /** 67 * sha1_vector - SHA-1 hash for data vector 68 * @num_elem: Number of elements in the data vector 69 * @addr: Pointers to the data areas 70 * @len: Lengths of the data blocks 71 * @mac: Buffer for the hash 72 * Returns: 0 on success, -1 on failure 73 */ 74 int sha1_vector(size_t num_elem, const u8 *addr[], const size_t *len, 75 u8 *mac); 76 77 /** 78 * fips186_2-prf - NIST FIPS Publication 186-2 change notice 1 PRF 79 * @seed: Seed/key for the PRF 80 * @seed_len: Seed length in bytes 81 * @x: Buffer for PRF output 82 * @xlen: Output length in bytes 83 * Returns: 0 on success, -1 on failure 84 * 85 * This function implements random number generation specified in NIST FIPS 86 * Publication 186-2 for EAP-SIM. This PRF uses a function that is similar to 87 * SHA-1, but has different message padding. 88 */ 89 int __must_check fips186_2_prf(const u8 *seed, size_t seed_len, u8 *x, 90 size_t xlen); 91 92 /** 93 * sha256_vector - SHA256 hash for data vector 94 * @num_elem: Number of elements in the data vector 95 * @addr: Pointers to the data areas 96 * @len: Lengths of the data blocks 97 * @mac: Buffer for the hash 98 * Returns: 0 on success, -1 on failure 99 */ 100 int sha256_vector(size_t num_elem, const u8 *addr[], const size_t *len, 101 u8 *mac); 102 103 /** 104 * des_encrypt - Encrypt one block with DES 105 * @clear: 8 octets (in) 106 * @key: 7 octets (in) (no parity bits included) 107 * @cypher: 8 octets (out) 108 */ 109 void des_encrypt(const u8 *clear, const u8 *key, u8 *cypher); 110 111 /** 112 * aes_encrypt_init - Initialize AES for encryption 113 * @key: Encryption key 114 * @len: Key length in bytes (usually 16, i.e., 128 bits) 115 * Returns: Pointer to context data or %NULL on failure 116 */ 117 void * aes_encrypt_init(const u8 *key, size_t len); 118 119 /** 120 * aes_encrypt - Encrypt one AES block 121 * @ctx: Context pointer from aes_encrypt_init() 122 * @plain: Plaintext data to be encrypted (16 bytes) 123 * @crypt: Buffer for the encrypted data (16 bytes) 124 */ 125 void aes_encrypt(void *ctx, const u8 *plain, u8 *crypt); 126 127 /** 128 * aes_encrypt_deinit - Deinitialize AES encryption 129 * @ctx: Context pointer from aes_encrypt_init() 130 */ 131 void aes_encrypt_deinit(void *ctx); 132 133 /** 134 * aes_decrypt_init - Initialize AES for decryption 135 * @key: Decryption key 136 * @len: Key length in bytes (usually 16, i.e., 128 bits) 137 * Returns: Pointer to context data or %NULL on failure 138 */ 139 void * aes_decrypt_init(const u8 *key, size_t len); 140 141 /** 142 * aes_decrypt - Decrypt one AES block 143 * @ctx: Context pointer from aes_encrypt_init() 144 * @crypt: Encrypted data (16 bytes) 145 * @plain: Buffer for the decrypted data (16 bytes) 146 */ 147 void aes_decrypt(void *ctx, const u8 *crypt, u8 *plain); 148 149 /** 150 * aes_decrypt_deinit - Deinitialize AES decryption 151 * @ctx: Context pointer from aes_encrypt_init() 152 */ 153 void aes_decrypt_deinit(void *ctx); 154 155 156 enum crypto_hash_alg { 157 CRYPTO_HASH_ALG_MD5, CRYPTO_HASH_ALG_SHA1, 158 CRYPTO_HASH_ALG_HMAC_MD5, CRYPTO_HASH_ALG_HMAC_SHA1 159 }; 160 161 struct crypto_hash; 162 163 /** 164 * crypto_hash_init - Initialize hash/HMAC function 165 * @alg: Hash algorithm 166 * @key: Key for keyed hash (e.g., HMAC) or %NULL if not needed 167 * @key_len: Length of the key in bytes 168 * Returns: Pointer to hash context to use with other hash functions or %NULL 169 * on failure 170 * 171 * This function is only used with internal TLSv1 implementation 172 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 173 * to implement this. 174 */ 175 struct crypto_hash * crypto_hash_init(enum crypto_hash_alg alg, const u8 *key, 176 size_t key_len); 177 178 /** 179 * crypto_hash_update - Add data to hash calculation 180 * @ctx: Context pointer from crypto_hash_init() 181 * @data: Data buffer to add 182 * @len: Length of the buffer 183 * 184 * This function is only used with internal TLSv1 implementation 185 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 186 * to implement this. 187 */ 188 void crypto_hash_update(struct crypto_hash *ctx, const u8 *data, size_t len); 189 190 /** 191 * crypto_hash_finish - Complete hash calculation 192 * @ctx: Context pointer from crypto_hash_init() 193 * @hash: Buffer for hash value or %NULL if caller is just freeing the hash 194 * context 195 * @len: Pointer to length of the buffer or %NULL if caller is just freeing the 196 * hash context; on return, this is set to the actual length of the hash value 197 * Returns: 0 on success, -1 if buffer is too small (len set to needed length), 198 * or -2 on other failures (including failed crypto_hash_update() operations) 199 * 200 * This function calculates the hash value and frees the context buffer that 201 * was used for hash calculation. 202 * 203 * This function is only used with internal TLSv1 implementation 204 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 205 * to implement this. 206 */ 207 int crypto_hash_finish(struct crypto_hash *ctx, u8 *hash, size_t *len); 208 209 210 enum crypto_cipher_alg { 211 CRYPTO_CIPHER_NULL = 0, CRYPTO_CIPHER_ALG_AES, CRYPTO_CIPHER_ALG_3DES, 212 CRYPTO_CIPHER_ALG_DES, CRYPTO_CIPHER_ALG_RC2, CRYPTO_CIPHER_ALG_RC4 213 }; 214 215 struct crypto_cipher; 216 217 /** 218 * crypto_cipher_init - Initialize block/stream cipher function 219 * @alg: Cipher algorithm 220 * @iv: Initialization vector for block ciphers or %NULL for stream ciphers 221 * @key: Cipher key 222 * @key_len: Length of key in bytes 223 * Returns: Pointer to cipher context to use with other cipher functions or 224 * %NULL on failure 225 * 226 * This function is only used with internal TLSv1 implementation 227 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 228 * to implement this. 229 */ 230 struct crypto_cipher * crypto_cipher_init(enum crypto_cipher_alg alg, 231 const u8 *iv, const u8 *key, 232 size_t key_len); 233 234 /** 235 * crypto_cipher_encrypt - Cipher encrypt 236 * @ctx: Context pointer from crypto_cipher_init() 237 * @plain: Plaintext to cipher 238 * @crypt: Resulting ciphertext 239 * @len: Length of the plaintext 240 * Returns: 0 on success, -1 on failure 241 * 242 * This function is only used with internal TLSv1 implementation 243 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 244 * to implement this. 245 */ 246 int __must_check crypto_cipher_encrypt(struct crypto_cipher *ctx, 247 const u8 *plain, u8 *crypt, size_t len); 248 249 /** 250 * crypto_cipher_decrypt - Cipher decrypt 251 * @ctx: Context pointer from crypto_cipher_init() 252 * @crypt: Ciphertext to decrypt 253 * @plain: Resulting plaintext 254 * @len: Length of the cipher text 255 * Returns: 0 on success, -1 on failure 256 * 257 * This function is only used with internal TLSv1 implementation 258 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 259 * to implement this. 260 */ 261 int __must_check crypto_cipher_decrypt(struct crypto_cipher *ctx, 262 const u8 *crypt, u8 *plain, size_t len); 263 264 /** 265 * crypto_cipher_decrypt - Free cipher context 266 * @ctx: Context pointer from crypto_cipher_init() 267 * 268 * This function is only used with internal TLSv1 implementation 269 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 270 * to implement this. 271 */ 272 void crypto_cipher_deinit(struct crypto_cipher *ctx); 273 274 275 struct crypto_public_key; 276 struct crypto_private_key; 277 278 /** 279 * crypto_public_key_import - Import an RSA public key 280 * @key: Key buffer (DER encoded RSA public key) 281 * @len: Key buffer length in bytes 282 * Returns: Pointer to the public key or %NULL on failure 283 * 284 * This function can just return %NULL if the crypto library supports X.509 285 * parsing. In that case, crypto_public_key_from_cert() is used to import the 286 * public key from a certificate. 287 * 288 * This function is only used with internal TLSv1 implementation 289 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 290 * to implement this. 291 */ 292 struct crypto_public_key * crypto_public_key_import(const u8 *key, size_t len); 293 294 /** 295 * crypto_private_key_import - Import an RSA private key 296 * @key: Key buffer (DER encoded RSA private key) 297 * @len: Key buffer length in bytes 298 * @passwd: Key encryption password or %NULL if key is not encrypted 299 * Returns: Pointer to the private key or %NULL on failure 300 * 301 * This function is only used with internal TLSv1 implementation 302 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 303 * to implement this. 304 */ 305 struct crypto_private_key * crypto_private_key_import(const u8 *key, 306 size_t len, 307 const char *passwd); 308 309 /** 310 * crypto_public_key_from_cert - Import an RSA public key from a certificate 311 * @buf: DER encoded X.509 certificate 312 * @len: Certificate buffer length in bytes 313 * Returns: Pointer to public key or %NULL on failure 314 * 315 * This function can just return %NULL if the crypto library does not support 316 * X.509 parsing. In that case, internal code will be used to parse the 317 * certificate and public key is imported using crypto_public_key_import(). 318 * 319 * This function is only used with internal TLSv1 implementation 320 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 321 * to implement this. 322 */ 323 struct crypto_public_key * crypto_public_key_from_cert(const u8 *buf, 324 size_t len); 325 326 /** 327 * crypto_public_key_encrypt_pkcs1_v15 - Public key encryption (PKCS #1 v1.5) 328 * @key: Public key 329 * @in: Plaintext buffer 330 * @inlen: Length of plaintext buffer in bytes 331 * @out: Output buffer for encrypted data 332 * @outlen: Length of output buffer in bytes; set to used length on success 333 * Returns: 0 on success, -1 on failure 334 * 335 * This function is only used with internal TLSv1 implementation 336 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 337 * to implement this. 338 */ 339 int __must_check crypto_public_key_encrypt_pkcs1_v15( 340 struct crypto_public_key *key, const u8 *in, size_t inlen, 341 u8 *out, size_t *outlen); 342 343 /** 344 * crypto_private_key_decrypt_pkcs1_v15 - Private key decryption (PKCS #1 v1.5) 345 * @key: Private key 346 * @in: Encrypted buffer 347 * @inlen: Length of encrypted buffer in bytes 348 * @out: Output buffer for encrypted data 349 * @outlen: Length of output buffer in bytes; set to used length on success 350 * Returns: 0 on success, -1 on failure 351 * 352 * This function is only used with internal TLSv1 implementation 353 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 354 * to implement this. 355 */ 356 int __must_check crypto_private_key_decrypt_pkcs1_v15( 357 struct crypto_private_key *key, const u8 *in, size_t inlen, 358 u8 *out, size_t *outlen); 359 360 /** 361 * crypto_private_key_sign_pkcs1 - Sign with private key (PKCS #1) 362 * @key: Private key from crypto_private_key_import() 363 * @in: Plaintext buffer 364 * @inlen: Length of plaintext buffer in bytes 365 * @out: Output buffer for encrypted (signed) data 366 * @outlen: Length of output buffer in bytes; set to used length on success 367 * Returns: 0 on success, -1 on failure 368 * 369 * This function is only used with internal TLSv1 implementation 370 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 371 * to implement this. 372 */ 373 int __must_check crypto_private_key_sign_pkcs1(struct crypto_private_key *key, 374 const u8 *in, size_t inlen, 375 u8 *out, size_t *outlen); 376 377 /** 378 * crypto_public_key_free - Free public key 379 * @key: Public key 380 * 381 * This function is only used with internal TLSv1 implementation 382 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 383 * to implement this. 384 */ 385 void crypto_public_key_free(struct crypto_public_key *key); 386 387 /** 388 * crypto_private_key_free - Free private key 389 * @key: Private key from crypto_private_key_import() 390 * 391 * This function is only used with internal TLSv1 implementation 392 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 393 * to implement this. 394 */ 395 void crypto_private_key_free(struct crypto_private_key *key); 396 397 /** 398 * crypto_public_key_decrypt_pkcs1 - Decrypt PKCS #1 signature 399 * @key: Public key 400 * @crypt: Encrypted signature data (using the private key) 401 * @crypt_len: Encrypted signature data length 402 * @plain: Buffer for plaintext (at least crypt_len bytes) 403 * @plain_len: Plaintext length (max buffer size on input, real len on output); 404 * Returns: 0 on success, -1 on failure 405 */ 406 int __must_check crypto_public_key_decrypt_pkcs1( 407 struct crypto_public_key *key, const u8 *crypt, size_t crypt_len, 408 u8 *plain, size_t *plain_len); 409 410 /** 411 * crypto_global_init - Initialize crypto wrapper 412 * 413 * This function is only used with internal TLSv1 implementation 414 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 415 * to implement this. 416 */ 417 int __must_check crypto_global_init(void); 418 419 /** 420 * crypto_global_deinit - Deinitialize crypto wrapper 421 * 422 * This function is only used with internal TLSv1 implementation 423 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 424 * to implement this. 425 */ 426 void crypto_global_deinit(void); 427 428 /** 429 * crypto_mod_exp - Modular exponentiation of large integers 430 * @base: Base integer (big endian byte array) 431 * @base_len: Length of base integer in bytes 432 * @power: Power integer (big endian byte array) 433 * @power_len: Length of power integer in bytes 434 * @modulus: Modulus integer (big endian byte array) 435 * @modulus_len: Length of modulus integer in bytes 436 * @result: Buffer for the result 437 * @result_len: Result length (max buffer size on input, real len on output) 438 * Returns: 0 on success, -1 on failure 439 * 440 * This function calculates result = base ^ power mod modulus. modules_len is 441 * used as the maximum size of modulus buffer. It is set to the used size on 442 * success. 443 * 444 * This function is only used with internal TLSv1 implementation 445 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 446 * to implement this. 447 */ 448 int __must_check crypto_mod_exp(const u8 *base, size_t base_len, 449 const u8 *power, size_t power_len, 450 const u8 *modulus, size_t modulus_len, 451 u8 *result, size_t *result_len); 452 453 /** 454 * rc4_skip - XOR RC4 stream to given data with skip-stream-start 455 * @key: RC4 key 456 * @keylen: RC4 key length 457 * @skip: number of bytes to skip from the beginning of the RC4 stream 458 * @data: data to be XOR'ed with RC4 stream 459 * @data_len: buf length 460 * Returns: 0 on success, -1 on failure 461 * 462 * Generate RC4 pseudo random stream for the given key, skip beginning of the 463 * stream, and XOR the end result with the data buffer to perform RC4 464 * encryption/decryption. 465 */ 466 int rc4_skip(const u8 *key, size_t keylen, size_t skip, 467 u8 *data, size_t data_len); 468 469 #endif /* CRYPTO_H */ 470