crypto.h revision 1f69aa52ea2e0a73ac502565df8c666ee49cab6a
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 */ 38int 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 */ 48int 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 */ 59int 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 */ 74int 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 */ 89int __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 */ 100int 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 */ 109void 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 */ 117void * 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 */ 125void 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 */ 131void 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 */ 139void * 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 */ 147void 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 */ 153void aes_decrypt_deinit(void *ctx); 154 155 156enum crypto_hash_alg { 157 CRYPTO_HASH_ALG_MD5, CRYPTO_HASH_ALG_SHA1, 158 CRYPTO_HASH_ALG_HMAC_MD5, CRYPTO_HASH_ALG_HMAC_SHA1, 159 CRYPTO_HASH_ALG_SHA256, CRYPTO_HASH_ALG_HMAC_SHA256 160}; 161 162struct crypto_hash; 163 164/** 165 * crypto_hash_init - Initialize hash/HMAC function 166 * @alg: Hash algorithm 167 * @key: Key for keyed hash (e.g., HMAC) or %NULL if not needed 168 * @key_len: Length of the key in bytes 169 * Returns: Pointer to hash context to use with other hash functions or %NULL 170 * on failure 171 * 172 * This function is only used with internal TLSv1 implementation 173 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 174 * to implement this. 175 */ 176struct crypto_hash * crypto_hash_init(enum crypto_hash_alg alg, const u8 *key, 177 size_t key_len); 178 179/** 180 * crypto_hash_update - Add data to hash calculation 181 * @ctx: Context pointer from crypto_hash_init() 182 * @data: Data buffer to add 183 * @len: Length of the buffer 184 * 185 * This function is only used with internal TLSv1 implementation 186 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 187 * to implement this. 188 */ 189void crypto_hash_update(struct crypto_hash *ctx, const u8 *data, size_t len); 190 191/** 192 * crypto_hash_finish - Complete hash calculation 193 * @ctx: Context pointer from crypto_hash_init() 194 * @hash: Buffer for hash value or %NULL if caller is just freeing the hash 195 * context 196 * @len: Pointer to length of the buffer or %NULL if caller is just freeing the 197 * hash context; on return, this is set to the actual length of the hash value 198 * Returns: 0 on success, -1 if buffer is too small (len set to needed length), 199 * or -2 on other failures (including failed crypto_hash_update() operations) 200 * 201 * This function calculates the hash value and frees the context buffer that 202 * was used for hash calculation. 203 * 204 * This function is only used with internal TLSv1 implementation 205 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 206 * to implement this. 207 */ 208int crypto_hash_finish(struct crypto_hash *ctx, u8 *hash, size_t *len); 209 210 211enum crypto_cipher_alg { 212 CRYPTO_CIPHER_NULL = 0, CRYPTO_CIPHER_ALG_AES, CRYPTO_CIPHER_ALG_3DES, 213 CRYPTO_CIPHER_ALG_DES, CRYPTO_CIPHER_ALG_RC2, CRYPTO_CIPHER_ALG_RC4 214}; 215 216struct crypto_cipher; 217 218/** 219 * crypto_cipher_init - Initialize block/stream cipher function 220 * @alg: Cipher algorithm 221 * @iv: Initialization vector for block ciphers or %NULL for stream ciphers 222 * @key: Cipher key 223 * @key_len: Length of key in bytes 224 * Returns: Pointer to cipher context to use with other cipher functions or 225 * %NULL on failure 226 * 227 * This function is only used with internal TLSv1 implementation 228 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 229 * to implement this. 230 */ 231struct crypto_cipher * crypto_cipher_init(enum crypto_cipher_alg alg, 232 const u8 *iv, const u8 *key, 233 size_t key_len); 234 235/** 236 * crypto_cipher_encrypt - Cipher encrypt 237 * @ctx: Context pointer from crypto_cipher_init() 238 * @plain: Plaintext to cipher 239 * @crypt: Resulting ciphertext 240 * @len: Length of the plaintext 241 * Returns: 0 on success, -1 on failure 242 * 243 * This function is only used with internal TLSv1 implementation 244 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 245 * to implement this. 246 */ 247int __must_check crypto_cipher_encrypt(struct crypto_cipher *ctx, 248 const u8 *plain, u8 *crypt, size_t len); 249 250/** 251 * crypto_cipher_decrypt - Cipher decrypt 252 * @ctx: Context pointer from crypto_cipher_init() 253 * @crypt: Ciphertext to decrypt 254 * @plain: Resulting plaintext 255 * @len: Length of the cipher text 256 * Returns: 0 on success, -1 on failure 257 * 258 * This function is only used with internal TLSv1 implementation 259 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 260 * to implement this. 261 */ 262int __must_check crypto_cipher_decrypt(struct crypto_cipher *ctx, 263 const u8 *crypt, u8 *plain, size_t len); 264 265/** 266 * crypto_cipher_decrypt - Free cipher context 267 * @ctx: Context pointer from crypto_cipher_init() 268 * 269 * This function is only used with internal TLSv1 implementation 270 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 271 * to implement this. 272 */ 273void crypto_cipher_deinit(struct crypto_cipher *ctx); 274 275 276struct crypto_public_key; 277struct crypto_private_key; 278 279/** 280 * crypto_public_key_import - Import an RSA public key 281 * @key: Key buffer (DER encoded RSA public key) 282 * @len: Key buffer length in bytes 283 * Returns: Pointer to the public key or %NULL on failure 284 * 285 * This function can just return %NULL if the crypto library supports X.509 286 * parsing. In that case, crypto_public_key_from_cert() is used to import the 287 * public key from a certificate. 288 * 289 * This function is only used with internal TLSv1 implementation 290 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 291 * to implement this. 292 */ 293struct crypto_public_key * crypto_public_key_import(const u8 *key, size_t len); 294 295/** 296 * crypto_private_key_import - Import an RSA private key 297 * @key: Key buffer (DER encoded RSA private key) 298 * @len: Key buffer length in bytes 299 * @passwd: Key encryption password or %NULL if key is not encrypted 300 * Returns: Pointer to the private key or %NULL on failure 301 * 302 * This function is only used with internal TLSv1 implementation 303 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 304 * to implement this. 305 */ 306struct crypto_private_key * crypto_private_key_import(const u8 *key, 307 size_t len, 308 const char *passwd); 309 310/** 311 * crypto_public_key_from_cert - Import an RSA public key from a certificate 312 * @buf: DER encoded X.509 certificate 313 * @len: Certificate buffer length in bytes 314 * Returns: Pointer to public key or %NULL on failure 315 * 316 * This function can just return %NULL if the crypto library does not support 317 * X.509 parsing. In that case, internal code will be used to parse the 318 * certificate and public key is imported using crypto_public_key_import(). 319 * 320 * This function is only used with internal TLSv1 implementation 321 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 322 * to implement this. 323 */ 324struct crypto_public_key * crypto_public_key_from_cert(const u8 *buf, 325 size_t len); 326 327/** 328 * crypto_public_key_encrypt_pkcs1_v15 - Public key encryption (PKCS #1 v1.5) 329 * @key: Public key 330 * @in: Plaintext buffer 331 * @inlen: Length of plaintext buffer in bytes 332 * @out: Output buffer for encrypted data 333 * @outlen: Length of output buffer in bytes; set to used length on success 334 * Returns: 0 on success, -1 on failure 335 * 336 * This function is only used with internal TLSv1 implementation 337 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 338 * to implement this. 339 */ 340int __must_check crypto_public_key_encrypt_pkcs1_v15( 341 struct crypto_public_key *key, const u8 *in, size_t inlen, 342 u8 *out, size_t *outlen); 343 344/** 345 * crypto_private_key_decrypt_pkcs1_v15 - Private key decryption (PKCS #1 v1.5) 346 * @key: Private key 347 * @in: Encrypted buffer 348 * @inlen: Length of encrypted buffer in bytes 349 * @out: Output buffer for encrypted data 350 * @outlen: Length of output buffer in bytes; set to used length on success 351 * Returns: 0 on success, -1 on failure 352 * 353 * This function is only used with internal TLSv1 implementation 354 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 355 * to implement this. 356 */ 357int __must_check crypto_private_key_decrypt_pkcs1_v15( 358 struct crypto_private_key *key, const u8 *in, size_t inlen, 359 u8 *out, size_t *outlen); 360 361/** 362 * crypto_private_key_sign_pkcs1 - Sign with private key (PKCS #1) 363 * @key: Private key from crypto_private_key_import() 364 * @in: Plaintext buffer 365 * @inlen: Length of plaintext buffer in bytes 366 * @out: Output buffer for encrypted (signed) data 367 * @outlen: Length of output buffer in bytes; set to used length on success 368 * Returns: 0 on success, -1 on failure 369 * 370 * This function is only used with internal TLSv1 implementation 371 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 372 * to implement this. 373 */ 374int __must_check crypto_private_key_sign_pkcs1(struct crypto_private_key *key, 375 const u8 *in, size_t inlen, 376 u8 *out, size_t *outlen); 377 378/** 379 * crypto_public_key_free - Free public key 380 * @key: Public key 381 * 382 * This function is only used with internal TLSv1 implementation 383 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 384 * to implement this. 385 */ 386void crypto_public_key_free(struct crypto_public_key *key); 387 388/** 389 * crypto_private_key_free - Free private key 390 * @key: Private key from crypto_private_key_import() 391 * 392 * This function is only used with internal TLSv1 implementation 393 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 394 * to implement this. 395 */ 396void crypto_private_key_free(struct crypto_private_key *key); 397 398/** 399 * crypto_public_key_decrypt_pkcs1 - Decrypt PKCS #1 signature 400 * @key: Public key 401 * @crypt: Encrypted signature data (using the private key) 402 * @crypt_len: Encrypted signature data length 403 * @plain: Buffer for plaintext (at least crypt_len bytes) 404 * @plain_len: Plaintext length (max buffer size on input, real len on output); 405 * Returns: 0 on success, -1 on failure 406 */ 407int __must_check crypto_public_key_decrypt_pkcs1( 408 struct crypto_public_key *key, const u8 *crypt, size_t crypt_len, 409 u8 *plain, size_t *plain_len); 410 411/** 412 * crypto_global_init - Initialize crypto wrapper 413 * 414 * This function is only used with internal TLSv1 implementation 415 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 416 * to implement this. 417 */ 418int __must_check crypto_global_init(void); 419 420/** 421 * crypto_global_deinit - Deinitialize crypto wrapper 422 * 423 * This function is only used with internal TLSv1 implementation 424 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 425 * to implement this. 426 */ 427void crypto_global_deinit(void); 428 429/** 430 * crypto_mod_exp - Modular exponentiation of large integers 431 * @base: Base integer (big endian byte array) 432 * @base_len: Length of base integer in bytes 433 * @power: Power integer (big endian byte array) 434 * @power_len: Length of power integer in bytes 435 * @modulus: Modulus integer (big endian byte array) 436 * @modulus_len: Length of modulus integer in bytes 437 * @result: Buffer for the result 438 * @result_len: Result length (max buffer size on input, real len on output) 439 * Returns: 0 on success, -1 on failure 440 * 441 * This function calculates result = base ^ power mod modulus. modules_len is 442 * used as the maximum size of modulus buffer. It is set to the used size on 443 * success. 444 * 445 * This function is only used with internal TLSv1 implementation 446 * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need 447 * to implement this. 448 */ 449int __must_check crypto_mod_exp(const u8 *base, size_t base_len, 450 const u8 *power, size_t power_len, 451 const u8 *modulus, size_t modulus_len, 452 u8 *result, size_t *result_len); 453 454/** 455 * rc4_skip - XOR RC4 stream to given data with skip-stream-start 456 * @key: RC4 key 457 * @keylen: RC4 key length 458 * @skip: number of bytes to skip from the beginning of the RC4 stream 459 * @data: data to be XOR'ed with RC4 stream 460 * @data_len: buf length 461 * Returns: 0 on success, -1 on failure 462 * 463 * Generate RC4 pseudo random stream for the given key, skip beginning of the 464 * stream, and XOR the end result with the data buffer to perform RC4 465 * encryption/decryption. 466 */ 467int rc4_skip(const u8 *key, size_t keylen, size_t skip, 468 u8 *data, size_t data_len); 469 470#endif /* CRYPTO_H */ 471