contrib/hostapd-0.5.8/crypto.h

   1 /*
   2  * WPA Supplicant / wrapper functions for crypto libraries
   3  * Copyright (c) 2004-2005, 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  */
  37 void md4_vector(size_t num_elem, const u8 *addr[], const size_t *len, u8 *mac);
  38
  39 /**
  40  * md5_vector - MD5 hash for data vector
  41  * @num_elem: Number of elements in the data vector
  42  * @addr: Pointers to the data areas
  43  * @len: Lengths of the data blocks
  44  * @mac: Buffer for the hash
  45  */
  46 void md5_vector(size_t num_elem, const u8 *addr[], const size_t *len, u8 *mac);
  47
  48 /**
  49  * sha1_vector - SHA-1 hash for data vector
  50  * @num_elem: Number of elements in the data vector
  51  * @addr: Pointers to the data areas
  52  * @len: Lengths of the data blocks
  53  * @mac: Buffer for the hash
  54  */
  55 void sha1_vector(size_t num_elem, const u8 *addr[], const size_t *len,
  56                  u8 *mac);
  57
  58 /**
  59  * fips186_2-prf - NIST FIPS Publication 186-2 change notice 1 PRF
  60  * @seed: Seed/key for the PRF
  61  * @seed_len: Seed length in bytes
  62  * @x: Buffer for PRF output
  63  * @xlen: Output length in bytes
  64  * Returns: 0 on success, -1 on failure
  65  *
  66  * This function implements random number generation specified in NIST FIPS
  67  * Publication 186-2 for EAP-SIM. This PRF uses a function that is similar to
  68  * SHA-1, but has different message padding.
  69  */
  70 int fips186_2_prf(const u8 *seed, size_t seed_len, u8 *x, size_t xlen);
  71
  72 /**
  73  * sha256_vector - SHA256 hash for data vector
  74  * @num_elem: Number of elements in the data vector
  75  * @addr: Pointers to the data areas
  76  * @len: Lengths of the data blocks
  77  * @mac: Buffer for the hash
  78  */
  79 void sha256_vector(size_t num_elem, const u8 *addr[], const size_t *len,
  80                    u8 *mac);
  81
  82 /**
  83  * des_encrypt - Encrypt one block with DES
  84  * @clear: 8 octets (in)
  85  * @key: 7 octets (in) (no parity bits included)
  86  * @cypher: 8 octets (out)
  87  */
  88 void des_encrypt(const u8 *clear, const u8 *key, u8 *cypher);
  89
  90 /**
  91  * aes_encrypt_init - Initialize AES for encryption
  92  * @key: Encryption key
  93  * @len: Key length in bytes (usually 16, i.e., 128 bits)
  94  * Returns: Pointer to context data or %NULL on failure
  95  */
  96 void * aes_encrypt_init(const u8 *key, size_t len);
  97
  98 /**
  99  * aes_encrypt - Encrypt one AES block
 100  * @ctx: Context pointer from aes_encrypt_init()
 101  * @plain: Plaintext data to be encrypted (16 bytes)
 102  * @crypt: Buffer for the encrypted data (16 bytes)
 103  */
 104 void aes_encrypt(void *ctx, const u8 *plain, u8 *crypt);
 105
 106 /**
 107  * aes_encrypt_deinit - Deinitialize AES encryption
 108  * @ctx: Context pointer from aes_encrypt_init()
 109  */
 110 void aes_encrypt_deinit(void *ctx);
 111
 112 /**
 113  * aes_decrypt_init - Initialize AES for decryption
 114  * @key: Decryption key
 115  * @len: Key length in bytes (usually 16, i.e., 128 bits)
 116  * Returns: Pointer to context data or %NULL on failure
 117  */
 118 void * aes_decrypt_init(const u8 *key, size_t len);
 119
 120 /**
 121  * aes_decrypt - Decrypt one AES block
 122  * @ctx: Context pointer from aes_encrypt_init()
 123  * @crypt: Encrypted data (16 bytes)
 124  * @plain: Buffer for the decrypted data (16 bytes)
 125  */
 126 void aes_decrypt(void *ctx, const u8 *crypt, u8 *plain);
 127
 128 /**
 129  * aes_decrypt_deinit - Deinitialize AES decryption
 130  * @ctx: Context pointer from aes_encrypt_init()
 131  */
 132 void aes_decrypt_deinit(void *ctx);
 133
 134
 135 enum crypto_hash_alg {
 136         CRYPTO_HASH_ALG_MD5, CRYPTO_HASH_ALG_SHA1,
 137         CRYPTO_HASH_ALG_HMAC_MD5, CRYPTO_HASH_ALG_HMAC_SHA1
 138 };
 139
 140 struct crypto_hash;
 141
 142 /**
 143  * crypto_hash_init - Initialize hash/HMAC function
 144  * @alg: Hash algorithm
 145  * @key: Key for keyed hash (e.g., HMAC) or %NULL if not needed
 146  * @key_len: Length of the key in bytes
 147  * Returns: Pointer to hash context to use with other hash functions or %NULL
 148  * on failure
 149  *
 150  * This function is only used with internal TLSv1 implementation
 151  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 152  * to implement this.
 153  */
 154 struct crypto_hash * crypto_hash_init(enum crypto_hash_alg alg, const u8 *key,
 155                                       size_t key_len);
 156
 157 /**
 158  * crypto_hash_update - Add data to hash calculation
 159  * @ctx: Context pointer from crypto_hash_init()
 160  * @data: Data buffer to add
 161  * @len: Length of the buffer
 162  *
 163  * This function is only used with internal TLSv1 implementation
 164  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 165  * to implement this.
 166  */
 167 void crypto_hash_update(struct crypto_hash *ctx, const u8 *data, size_t len);
 168
 169 /**
 170  * crypto_hash_finish - Complete hash calculation
 171  * @ctx: Context pointer from crypto_hash_init()
 172  * @hash: Buffer for hash value or %NULL if caller is just freeing the hash
 173  * context
 174  * @len: Pointer to length of the buffer or %NULL if caller is just freeing the
 175  * hash context; on return, this is set to the actual length of the hash value
 176  * Returns: 0 on success, -1 if buffer is too small (len set to needed length),
 177  * or -2 on other failures (including failed crypto_hash_update() operations)
 178  *
 179  * This function calculates the hash value and frees the context buffer that
 180  * was used for hash calculation.
 181  *
 182  * This function is only used with internal TLSv1 implementation
 183  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 184  * to implement this.
 185  */
 186 int crypto_hash_finish(struct crypto_hash *ctx, u8 *hash, size_t *len);
 187
 188
 189 enum crypto_cipher_alg {
 190         CRYPTO_CIPHER_NULL = 0, CRYPTO_CIPHER_ALG_AES, CRYPTO_CIPHER_ALG_3DES,
 191         CRYPTO_CIPHER_ALG_DES, CRYPTO_CIPHER_ALG_RC2, CRYPTO_CIPHER_ALG_RC4
 192 };
 193
 194 struct crypto_cipher;
 195
 196 /**
 197  * crypto_cipher_init - Initialize block/stream cipher function
 198  * @alg: Cipher algorithm
 199  * @iv: Initialization vector for block ciphers or %NULL for stream ciphers
 200  * @key: Cipher key
 201  * @key_len: Length of key in bytes
 202  * Returns: Pointer to cipher context to use with other cipher functions or
 203  * %NULL on failure
 204  *
 205  * This function is only used with internal TLSv1 implementation
 206  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 207  * to implement this.
 208  */
 209 struct crypto_cipher * crypto_cipher_init(enum crypto_cipher_alg alg,
 210                                           const u8 *iv, const u8 *key,
 211                                           size_t key_len);
 212
 213 /**
 214  * crypto_cipher_encrypt - Cipher encrypt
 215  * @ctx: Context pointer from crypto_cipher_init()
 216  * @plain: Plaintext to cipher
 217  * @crypt: Resulting ciphertext
 218  * @len: Length of the plaintext
 219  * Returns: 0 on success, -1 on failure
 220  *
 221  * This function is only used with internal TLSv1 implementation
 222  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 223  * to implement this.
 224  */
 225 int crypto_cipher_encrypt(struct crypto_cipher *ctx, const u8 *plain,
 226                           u8 *crypt, size_t len);
 227
 228 /**
 229  * crypto_cipher_decrypt - Cipher decrypt
 230  * @ctx: Context pointer from crypto_cipher_init()
 231  * @crypt: Ciphertext to decrypt
 232  * @plain: Resulting plaintext
 233  * @len: Length of the cipher text
 234  * Returns: 0 on success, -1 on failure
 235  *
 236  * This function is only used with internal TLSv1 implementation
 237  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 238  * to implement this.
 239  */
 240 int crypto_cipher_decrypt(struct crypto_cipher *ctx, const u8 *crypt,
 241                           u8 *plain, size_t len);
 242
 243 /**
 244  * crypto_cipher_decrypt - Free cipher context
 245  * @ctx: Context pointer from crypto_cipher_init()
 246  *
 247  * This function is only used with internal TLSv1 implementation
 248  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 249  * to implement this.
 250  */
 251 void crypto_cipher_deinit(struct crypto_cipher *ctx);
 252
 253
 254 struct crypto_public_key;
 255 struct crypto_private_key;
 256
 257 /**
 258  * crypto_public_key_import - Import an RSA public key
 259  * @key: Key buffer (DER encoded RSA public key)
 260  * @len: Key buffer length in bytes
 261  * Returns: Pointer to the public key or %NULL on failure
 262  *
 263  * This function can just return %NULL if the crypto library supports X.509
 264  * parsing. In that case, crypto_public_key_from_cert() is used to import the
 265  * public key from a certificate.
 266  *
 267  * This function is only used with internal TLSv1 implementation
 268  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 269  * to implement this.
 270  */
 271 struct crypto_public_key * crypto_public_key_import(const u8 *key, size_t len);
 272
 273 /**
 274  * crypto_private_key_import - Import an RSA private key
 275  * @key: Key buffer (DER encoded RSA private key)
 276  * @len: Key buffer length in bytes
 277  * Returns: Pointer to the private key or %NULL on failure
 278  *
 279  * This function is only used with internal TLSv1 implementation
 280  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 281  * to implement this.
 282  */
 283 struct crypto_private_key * crypto_private_key_import(const u8 *key,
 284                                                       size_t len);
 285
 286 /**
 287  * crypto_public_key_from_cert - Import an RSA public key from a certificate
 288  * @buf: DER encoded X.509 certificate
 289  * @len: Certificate buffer length in bytes
 290  * Returns: Pointer to public key or %NULL on failure
 291  *
 292  * This function can just return %NULL if the crypto library does not support
 293  * X.509 parsing. In that case, internal code will be used to parse the
 294  * certificate and public key is imported using crypto_public_key_import().
 295  *
 296  * This function is only used with internal TLSv1 implementation
 297  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 298  * to implement this.
 299  */
 300 struct crypto_public_key * crypto_public_key_from_cert(const u8 *buf,
 301                                                        size_t len);
 302
 303 /**
 304  * crypto_public_key_encrypt_pkcs1_v15 - Public key encryption (PKCS #1 v1.5)
 305  * @key: Public key
 306  * @in: Plaintext buffer
 307  * @inlen: Length of plaintext buffer in bytes
 308  * @out: Output buffer for encrypted data
 309  * @outlen: Length of output buffer in bytes; set to used length on success
 310  * Returns: 0 on success, -1 on failure
 311  *
 312  * This function is only used with internal TLSv1 implementation
 313  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 314  * to implement this.
 315  */
 316 int crypto_public_key_encrypt_pkcs1_v15(struct crypto_public_key *key,
 317                                         const u8 *in, size_t inlen,
 318                                         u8 *out, size_t *outlen);
 319
 320 /**
 321  * crypto_private_key_sign_pkcs1 - Sign with private key (PKCS #1)
 322  * @key: Private key from crypto_private_key_import()
 323  * @in: Plaintext buffer
 324  * @inlen: Length of plaintext buffer in bytes
 325  * @out: Output buffer for encrypted (signed) data
 326  * @outlen: Length of output buffer in bytes; set to used length on success
 327  * Returns: 0 on success, -1 on failure
 328  *
 329  * This function is only used with internal TLSv1 implementation
 330  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 331  * to implement this.
 332  */
 333 int crypto_private_key_sign_pkcs1(struct crypto_private_key *key,
 334                                   const u8 *in, size_t inlen,
 335                                   u8 *out, size_t *outlen);
 336
 337 /**
 338  * crypto_public_key_free - Free public key
 339  * @key: Public key
 340  *
 341  * This function is only used with internal TLSv1 implementation
 342  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 343  * to implement this.
 344  */
 345 void crypto_public_key_free(struct crypto_public_key *key);
 346
 347 /**
 348  * crypto_private_key_free - Free private key
 349  * @key: Private key from crypto_private_key_import()
 350  *
 351  * This function is only used with internal TLSv1 implementation
 352  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 353  * to implement this.
 354  */
 355 void crypto_private_key_free(struct crypto_private_key *key);
 356
 357 /**
 358  * crypto_public_key_decrypt_pkcs1 - Decrypt PKCS #1 signature
 359  * @key: Public key
 360  * @crypt: Encrypted signature data (using the private key)
 361  * @crypt_len: Encrypted signature data length
 362  * @plain: Buffer for plaintext (at least crypt_len bytes)
 363  * @plain_len: Plaintext length (max buffer size on input, real len on output);
 364  * Returns: 0 on success, -1 on failure
 365  */
 366 int crypto_public_key_decrypt_pkcs1(struct crypto_public_key *key,
 367                                     const u8 *crypt, size_t crypt_len,
 368                                     u8 *plain, size_t *plain_len);
 369
 370 /**
 371  * crypto_global_init - Initialize crypto wrapper
 372  *
 373  * This function is only used with internal TLSv1 implementation
 374  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 375  * to implement this.
 376  */
 377 int crypto_global_init(void);
 378
 379 /**
 380  * crypto_global_deinit - Deinitialize crypto wrapper
 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  */
 386 void crypto_global_deinit(void);
 387
 388 /**
 389  * crypto_mod_exp - Modular exponentiation of large integers
 390  * @base: Base integer (big endian byte array)
 391  * @base_len: Length of base integer in bytes
 392  * @power: Power integer (big endian byte array)
 393  * @power_len: Length of power integer in bytes
 394  * @modulus: Modulus integer (big endian byte array)
 395  * @modulus_len: Length of modulus integer in bytes
 396  * @result: Buffer for the result
 397  * @result_len: Result length (max buffer size on input, real len on output)
 398  * Returns: 0 on success, -1 on failure
 399  *
 400  * This function calculates result = base ^ power mod modulus. modules_len is
 401  * used as the maximum size of modulus buffer. It is set to the used size on
 402  * success.
 403  *
 404  * This function is only used with internal TLSv1 implementation
 405  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 406  * to implement this.
 407  */
 408 int crypto_mod_exp(const u8 *base, size_t base_len,
 409                    const u8 *power, size_t power_len,
 410                    const u8 *modulus, size_t modulus_len,
 411                    u8 *result, size_t *result_len);
 412
 413 #endif /* CRYPTO_H */