Home | History | Annotate | Download | only in crypto
      1 /*
      2  * Wrapper functions for crypto libraries
      3  * Copyright (c) 2004-2013, Jouni Malinen <j (at) w1.fi>
      4  *
      5  * This software may be distributed under the terms of the BSD license.
      6  * See README for more details.
      7  *
      8  * This file defines the cryptographic functions that need to be implemented
      9  * for wpa_supplicant and hostapd. When TLS is not used, internal
     10  * implementation of MD5, SHA1, and AES is used and no external libraries are
     11  * required. When TLS is enabled (e.g., by enabling EAP-TLS or EAP-PEAP), the
     12  * crypto library used by the TLS implementation is expected to be used for
     13  * non-TLS needs, too, in order to save space by not implementing these
     14  * functions twice.
     15  *
     16  * Wrapper code for using each crypto library is in its own file (crypto*.c)
     17  * and one of these files is build and linked in to provide the functions
     18  * defined here.
     19  */
     20 
     21 #ifndef CRYPTO_H
     22 #define CRYPTO_H
     23 
     24 /**
     25  * md4_vector - MD4 hash for data vector
     26  * @num_elem: Number of elements in the data vector
     27  * @addr: Pointers to the data areas
     28  * @len: Lengths of the data blocks
     29  * @mac: Buffer for the hash
     30  * Returns: 0 on success, -1 on failure
     31  */
     32 int md4_vector(size_t num_elem, const u8 *addr[], const size_t *len, u8 *mac);
     33 
     34 /**
     35  * md5_vector - MD5 hash for data vector
     36  * @num_elem: Number of elements in the data vector
     37  * @addr: Pointers to the data areas
     38  * @len: Lengths of the data blocks
     39  * @mac: Buffer for the hash
     40  * Returns: 0 on success, -1 on failure
     41  */
     42 int md5_vector(size_t num_elem, const u8 *addr[], const size_t *len, u8 *mac);
     43 
     44 
     45 /**
     46  * sha1_vector - SHA-1 hash for data vector
     47  * @num_elem: Number of elements in the data vector
     48  * @addr: Pointers to the data areas
     49  * @len: Lengths of the data blocks
     50  * @mac: Buffer for the hash
     51  * Returns: 0 on success, -1 on failure
     52  */
     53 int sha1_vector(size_t num_elem, const u8 *addr[], const size_t *len,
     54 		u8 *mac);
     55 
     56 /**
     57  * fips186_2-prf - NIST FIPS Publication 186-2 change notice 1 PRF
     58  * @seed: Seed/key for the PRF
     59  * @seed_len: Seed length in bytes
     60  * @x: Buffer for PRF output
     61  * @xlen: Output length in bytes
     62  * Returns: 0 on success, -1 on failure
     63  *
     64  * This function implements random number generation specified in NIST FIPS
     65  * Publication 186-2 for EAP-SIM. This PRF uses a function that is similar to
     66  * SHA-1, but has different message padding.
     67  */
     68 int __must_check fips186_2_prf(const u8 *seed, size_t seed_len, u8 *x,
     69 			       size_t xlen);
     70 
     71 /**
     72  * sha256_vector - SHA256 hash for data vector
     73  * @num_elem: Number of elements in the data vector
     74  * @addr: Pointers to the data areas
     75  * @len: Lengths of the data blocks
     76  * @mac: Buffer for the hash
     77  * Returns: 0 on success, -1 on failure
     78  */
     79 int 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 	CRYPTO_HASH_ALG_SHA256, CRYPTO_HASH_ALG_HMAC_SHA256
    139 };
    140 
    141 struct crypto_hash;
    142 
    143 /**
    144  * crypto_hash_init - Initialize hash/HMAC function
    145  * @alg: Hash algorithm
    146  * @key: Key for keyed hash (e.g., HMAC) or %NULL if not needed
    147  * @key_len: Length of the key in bytes
    148  * Returns: Pointer to hash context to use with other hash functions or %NULL
    149  * on failure
    150  *
    151  * This function is only used with internal TLSv1 implementation
    152  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
    153  * to implement this.
    154  */
    155 struct crypto_hash * crypto_hash_init(enum crypto_hash_alg alg, const u8 *key,
    156 				      size_t key_len);
    157 
    158 /**
    159  * crypto_hash_update - Add data to hash calculation
    160  * @ctx: Context pointer from crypto_hash_init()
    161  * @data: Data buffer to add
    162  * @len: Length of the buffer
    163  *
    164  * This function is only used with internal TLSv1 implementation
    165  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
    166  * to implement this.
    167  */
    168 void crypto_hash_update(struct crypto_hash *ctx, const u8 *data, size_t len);
    169 
    170 /**
    171  * crypto_hash_finish - Complete hash calculation
    172  * @ctx: Context pointer from crypto_hash_init()
    173  * @hash: Buffer for hash value or %NULL if caller is just freeing the hash
    174  * context
    175  * @len: Pointer to length of the buffer or %NULL if caller is just freeing the
    176  * hash context; on return, this is set to the actual length of the hash value
    177  * Returns: 0 on success, -1 if buffer is too small (len set to needed length),
    178  * or -2 on other failures (including failed crypto_hash_update() operations)
    179  *
    180  * This function calculates the hash value and frees the context buffer that
    181  * was used for hash calculation.
    182  *
    183  * This function is only used with internal TLSv1 implementation
    184  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
    185  * to implement this.
    186  */
    187 int crypto_hash_finish(struct crypto_hash *ctx, u8 *hash, size_t *len);
    188 
    189 
    190 enum crypto_cipher_alg {
    191 	CRYPTO_CIPHER_NULL = 0, CRYPTO_CIPHER_ALG_AES, CRYPTO_CIPHER_ALG_3DES,
    192 	CRYPTO_CIPHER_ALG_DES, CRYPTO_CIPHER_ALG_RC2, CRYPTO_CIPHER_ALG_RC4
    193 };
    194 
    195 struct crypto_cipher;
    196 
    197 /**
    198  * crypto_cipher_init - Initialize block/stream cipher function
    199  * @alg: Cipher algorithm
    200  * @iv: Initialization vector for block ciphers or %NULL for stream ciphers
    201  * @key: Cipher key
    202  * @key_len: Length of key in bytes
    203  * Returns: Pointer to cipher context to use with other cipher functions or
    204  * %NULL on failure
    205  *
    206  * This function is only used with internal TLSv1 implementation
    207  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
    208  * to implement this.
    209  */
    210 struct crypto_cipher * crypto_cipher_init(enum crypto_cipher_alg alg,
    211 					  const u8 *iv, const u8 *key,
    212 					  size_t key_len);
    213 
    214 /**
    215  * crypto_cipher_encrypt - Cipher encrypt
    216  * @ctx: Context pointer from crypto_cipher_init()
    217  * @plain: Plaintext to cipher
    218  * @crypt: Resulting ciphertext
    219  * @len: Length of the plaintext
    220  * Returns: 0 on success, -1 on failure
    221  *
    222  * This function is only used with internal TLSv1 implementation
    223  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
    224  * to implement this.
    225  */
    226 int __must_check crypto_cipher_encrypt(struct crypto_cipher *ctx,
    227 				       const u8 *plain, u8 *crypt, size_t len);
    228 
    229 /**
    230  * crypto_cipher_decrypt - Cipher decrypt
    231  * @ctx: Context pointer from crypto_cipher_init()
    232  * @crypt: Ciphertext to decrypt
    233  * @plain: Resulting plaintext
    234  * @len: Length of the cipher text
    235  * Returns: 0 on success, -1 on failure
    236  *
    237  * This function is only used with internal TLSv1 implementation
    238  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
    239  * to implement this.
    240  */
    241 int __must_check crypto_cipher_decrypt(struct crypto_cipher *ctx,
    242 				       const u8 *crypt, u8 *plain, size_t len);
    243 
    244 /**
    245  * crypto_cipher_decrypt - Free cipher context
    246  * @ctx: Context pointer from crypto_cipher_init()
    247  *
    248  * This function is only used with internal TLSv1 implementation
    249  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
    250  * to implement this.
    251  */
    252 void crypto_cipher_deinit(struct crypto_cipher *ctx);
    253 
    254 
    255 struct crypto_public_key;
    256 struct crypto_private_key;
    257 
    258 /**
    259  * crypto_public_key_import - Import an RSA public key
    260  * @key: Key buffer (DER encoded RSA public key)
    261  * @len: Key buffer length in bytes
    262  * Returns: Pointer to the public key or %NULL on failure
    263  *
    264  * This function can just return %NULL if the crypto library supports X.509
    265  * parsing. In that case, crypto_public_key_from_cert() is used to import the
    266  * public key from a certificate.
    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 struct crypto_public_key * crypto_public_key_import(const u8 *key, size_t len);
    273 
    274 struct crypto_public_key *
    275 crypto_public_key_import_parts(const u8 *n, size_t n_len,
    276 			       const u8 *e, size_t e_len);
    277 
    278 /**
    279  * crypto_private_key_import - Import an RSA private key
    280  * @key: Key buffer (DER encoded RSA private key)
    281  * @len: Key buffer length in bytes
    282  * @passwd: Key encryption password or %NULL if key is not encrypted
    283  * Returns: Pointer to the private key or %NULL on failure
    284  *
    285  * This function is only used with internal TLSv1 implementation
    286  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
    287  * to implement this.
    288  */
    289 struct crypto_private_key * crypto_private_key_import(const u8 *key,
    290 						      size_t len,
    291 						      const char *passwd);
    292 
    293 /**
    294  * crypto_public_key_from_cert - Import an RSA public key from a certificate
    295  * @buf: DER encoded X.509 certificate
    296  * @len: Certificate buffer length in bytes
    297  * Returns: Pointer to public key or %NULL on failure
    298  *
    299  * This function can just return %NULL if the crypto library does not support
    300  * X.509 parsing. In that case, internal code will be used to parse the
    301  * certificate and public key is imported using crypto_public_key_import().
    302  *
    303  * This function is only used with internal TLSv1 implementation
    304  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
    305  * to implement this.
    306  */
    307 struct crypto_public_key * crypto_public_key_from_cert(const u8 *buf,
    308 						       size_t len);
    309 
    310 /**
    311  * crypto_public_key_encrypt_pkcs1_v15 - Public key encryption (PKCS #1 v1.5)
    312  * @key: Public key
    313  * @in: Plaintext buffer
    314  * @inlen: Length of plaintext buffer in bytes
    315  * @out: Output buffer for encrypted data
    316  * @outlen: Length of output buffer in bytes; set to used length on success
    317  * Returns: 0 on success, -1 on failure
    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 int __must_check crypto_public_key_encrypt_pkcs1_v15(
    324 	struct crypto_public_key *key, const u8 *in, size_t inlen,
    325 	u8 *out, size_t *outlen);
    326 
    327 /**
    328  * crypto_private_key_decrypt_pkcs1_v15 - Private key decryption (PKCS #1 v1.5)
    329  * @key: Private key
    330  * @in: Encrypted buffer
    331  * @inlen: Length of encrypted 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  */
    340 int __must_check crypto_private_key_decrypt_pkcs1_v15(
    341 	struct crypto_private_key *key, const u8 *in, size_t inlen,
    342 	u8 *out, size_t *outlen);
    343 
    344 /**
    345  * crypto_private_key_sign_pkcs1 - Sign with private key (PKCS #1)
    346  * @key: Private key from crypto_private_key_import()
    347  * @in: Plaintext buffer
    348  * @inlen: Length of plaintext buffer in bytes
    349  * @out: Output buffer for encrypted (signed) 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  */
    357 int __must_check crypto_private_key_sign_pkcs1(struct crypto_private_key *key,
    358 					       const u8 *in, size_t inlen,
    359 					       u8 *out, size_t *outlen);
    360 
    361 /**
    362  * crypto_public_key_free - Free public key
    363  * @key: Public key
    364  *
    365  * This function is only used with internal TLSv1 implementation
    366  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
    367  * to implement this.
    368  */
    369 void crypto_public_key_free(struct crypto_public_key *key);
    370 
    371 /**
    372  * crypto_private_key_free - Free private key
    373  * @key: Private key from crypto_private_key_import()
    374  *
    375  * This function is only used with internal TLSv1 implementation
    376  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
    377  * to implement this.
    378  */
    379 void crypto_private_key_free(struct crypto_private_key *key);
    380 
    381 /**
    382  * crypto_public_key_decrypt_pkcs1 - Decrypt PKCS #1 signature
    383  * @key: Public key
    384  * @crypt: Encrypted signature data (using the private key)
    385  * @crypt_len: Encrypted signature data length
    386  * @plain: Buffer for plaintext (at least crypt_len bytes)
    387  * @plain_len: Plaintext length (max buffer size on input, real len on output);
    388  * Returns: 0 on success, -1 on failure
    389  */
    390 int __must_check crypto_public_key_decrypt_pkcs1(
    391 	struct crypto_public_key *key, const u8 *crypt, size_t crypt_len,
    392 	u8 *plain, size_t *plain_len);
    393 
    394 /**
    395  * crypto_global_init - Initialize crypto wrapper
    396  *
    397  * This function is only used with internal TLSv1 implementation
    398  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
    399  * to implement this.
    400  */
    401 int __must_check crypto_global_init(void);
    402 
    403 /**
    404  * crypto_global_deinit - Deinitialize crypto wrapper
    405  *
    406  * This function is only used with internal TLSv1 implementation
    407  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
    408  * to implement this.
    409  */
    410 void crypto_global_deinit(void);
    411 
    412 /**
    413  * crypto_mod_exp - Modular exponentiation of large integers
    414  * @base: Base integer (big endian byte array)
    415  * @base_len: Length of base integer in bytes
    416  * @power: Power integer (big endian byte array)
    417  * @power_len: Length of power integer in bytes
    418  * @modulus: Modulus integer (big endian byte array)
    419  * @modulus_len: Length of modulus integer in bytes
    420  * @result: Buffer for the result
    421  * @result_len: Result length (max buffer size on input, real len on output)
    422  * Returns: 0 on success, -1 on failure
    423  *
    424  * This function calculates result = base ^ power mod modulus. modules_len is
    425  * used as the maximum size of modulus buffer. It is set to the used size on
    426  * success.
    427  *
    428  * This function is only used with internal TLSv1 implementation
    429  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
    430  * to implement this.
    431  */
    432 int __must_check crypto_mod_exp(const u8 *base, size_t base_len,
    433 				const u8 *power, size_t power_len,
    434 				const u8 *modulus, size_t modulus_len,
    435 				u8 *result, size_t *result_len);
    436 
    437 /**
    438  * rc4_skip - XOR RC4 stream to given data with skip-stream-start
    439  * @key: RC4 key
    440  * @keylen: RC4 key length
    441  * @skip: number of bytes to skip from the beginning of the RC4 stream
    442  * @data: data to be XOR'ed with RC4 stream
    443  * @data_len: buf length
    444  * Returns: 0 on success, -1 on failure
    445  *
    446  * Generate RC4 pseudo random stream for the given key, skip beginning of the
    447  * stream, and XOR the end result with the data buffer to perform RC4
    448  * encryption/decryption.
    449  */
    450 int rc4_skip(const u8 *key, size_t keylen, size_t skip,
    451 	     u8 *data, size_t data_len);
    452 
    453 /**
    454  * crypto_get_random - Generate cryptographically strong pseudy-random bytes
    455  * @buf: Buffer for data
    456  * @len: Number of bytes to generate
    457  * Returns: 0 on success, -1 on failure
    458  *
    459  * If the PRNG does not have enough entropy to ensure unpredictable byte
    460  * sequence, this functions must return -1.
    461  */
    462 int crypto_get_random(void *buf, size_t len);
    463 
    464 
    465 /**
    466  * struct crypto_bignum - bignum
    467  *
    468  * Internal data structure for bignum implementation. The contents is specific
    469  * to the used crypto library.
    470  */
    471 struct crypto_bignum;
    472 
    473 /**
    474  * crypto_bignum_init - Allocate memory for bignum
    475  * Returns: Pointer to allocated bignum or %NULL on failure
    476  */
    477 struct crypto_bignum * crypto_bignum_init(void);
    478 
    479 /**
    480  * crypto_bignum_init_set - Allocate memory for bignum and set the value
    481  * @buf: Buffer with unsigned binary value
    482  * @len: Length of buf in octets
    483  * Returns: Pointer to allocated bignum or %NULL on failure
    484  */
    485 struct crypto_bignum * crypto_bignum_init_set(const u8 *buf, size_t len);
    486 
    487 /**
    488  * crypto_bignum_deinit - Free bignum
    489  * @n: Bignum from crypto_bignum_init() or crypto_bignum_init_set()
    490  * @clear: Whether to clear the value from memory
    491  */
    492 void crypto_bignum_deinit(struct crypto_bignum *n, int clear);
    493 
    494 /**
    495  * crypto_bignum_to_bin - Set binary buffer to unsigned bignum
    496  * @a: Bignum
    497  * @buf: Buffer for the binary number
    498  * @len: Length of @buf in octets
    499  * @padlen: Length in octets to pad the result to or 0 to indicate no padding
    500  * Returns: Number of octets written on success, -1 on failure
    501  */
    502 int crypto_bignum_to_bin(const struct crypto_bignum *a,
    503 			 u8 *buf, size_t buflen, size_t padlen);
    504 
    505 /**
    506  * crypto_bignum_add - c = a + b
    507  * @a: Bignum
    508  * @b: Bignum
    509  * @c: Bignum; used to store the result of a + b
    510  * Returns: 0 on success, -1 on failure
    511  */
    512 int crypto_bignum_add(const struct crypto_bignum *a,
    513 		      const struct crypto_bignum *b,
    514 		      struct crypto_bignum *c);
    515 
    516 /**
    517  * crypto_bignum_mod - c = a % b
    518  * @a: Bignum
    519  * @b: Bignum
    520  * @c: Bignum; used to store the result of a % b
    521  * Returns: 0 on success, -1 on failure
    522  */
    523 int crypto_bignum_mod(const struct crypto_bignum *a,
    524 		      const struct crypto_bignum *b,
    525 		      struct crypto_bignum *c);
    526 
    527 /**
    528  * crypto_bignum_exptmod - Modular exponentiation: d = a^b (mod c)
    529  * @a: Bignum; base
    530  * @b: Bignum; exponent
    531  * @c: Bignum; modulus
    532  * @d: Bignum; used to store the result of a^b (mod c)
    533  * Returns: 0 on success, -1 on failure
    534  */
    535 int crypto_bignum_exptmod(const struct crypto_bignum *a,
    536 			  const struct crypto_bignum *b,
    537 			  const struct crypto_bignum *c,
    538 			  struct crypto_bignum *d);
    539 
    540 /**
    541  * crypto_bignum_inverse - Inverse a bignum so that a * c = 1 (mod b)
    542  * @a: Bignum
    543  * @b: Bignum
    544  * @c: Bignum; used to store the result
    545  * Returns: 0 on success, -1 on failure
    546  */
    547 int crypto_bignum_inverse(const struct crypto_bignum *a,
    548 			  const struct crypto_bignum *b,
    549 			  struct crypto_bignum *c);
    550 
    551 /**
    552  * crypto_bignum_sub - c = a - b
    553  * @a: Bignum
    554  * @b: Bignum
    555  * @c: Bignum; used to store the result of a - b
    556  * Returns: 0 on success, -1 on failure
    557  */
    558 int crypto_bignum_sub(const struct crypto_bignum *a,
    559 		      const struct crypto_bignum *b,
    560 		      struct crypto_bignum *c);
    561 
    562 /**
    563  * crypto_bignum_div - c = a / b
    564  * @a: Bignum
    565  * @b: Bignum
    566  * @c: Bignum; used to store the result of a / b
    567  * Returns: 0 on success, -1 on failure
    568  */
    569 int crypto_bignum_div(const struct crypto_bignum *a,
    570 		      const struct crypto_bignum *b,
    571 		      struct crypto_bignum *c);
    572 
    573 /**
    574  * crypto_bignum_mulmod - d = a * b (mod c)
    575  * @a: Bignum
    576  * @b: Bignum
    577  * @c: Bignum
    578  * @d: Bignum; used to store the result of (a * b) % c
    579  * Returns: 0 on success, -1 on failure
    580  */
    581 int crypto_bignum_mulmod(const struct crypto_bignum *a,
    582 			 const struct crypto_bignum *b,
    583 			 const struct crypto_bignum *c,
    584 			 struct crypto_bignum *d);
    585 
    586 /**
    587  * crypto_bignum_cmp - Compare two bignums
    588  * @a: Bignum
    589  * @b: Bignum
    590  * Returns: -1 if a < b, 0 if a == b, or 1 if a > b
    591  */
    592 int crypto_bignum_cmp(const struct crypto_bignum *a,
    593 		      const struct crypto_bignum *b);
    594 
    595 /**
    596  * crypto_bignum_bits - Get size of a bignum in bits
    597  * @a: Bignum
    598  * Returns: Number of bits in the bignum
    599  */
    600 int crypto_bignum_bits(const struct crypto_bignum *a);
    601 
    602 /**
    603  * crypto_bignum_is_zero - Is the given bignum zero
    604  * @a: Bignum
    605  * Returns: 1 if @a is zero or 0 if not
    606  */
    607 int crypto_bignum_is_zero(const struct crypto_bignum *a);
    608 
    609 /**
    610  * crypto_bignum_is_one - Is the given bignum one
    611  * @a: Bignum
    612  * Returns: 1 if @a is one or 0 if not
    613  */
    614 int crypto_bignum_is_one(const struct crypto_bignum *a);
    615 
    616 /**
    617  * struct crypto_ec - Elliptic curve context
    618  *
    619  * Internal data structure for EC implementation. The contents is specific
    620  * to the used crypto library.
    621  */
    622 struct crypto_ec;
    623 
    624 /**
    625  * crypto_ec_init - Initialize elliptic curve context
    626  * @group: Identifying number for the ECC group (IANA "Group Description"
    627  *	attribute registrty for RFC 2409)
    628  * Returns: Pointer to EC context or %NULL on failure
    629  */
    630 struct crypto_ec * crypto_ec_init(int group);
    631 
    632 /**
    633  * crypto_ec_deinit - Deinitialize elliptic curve context
    634  * @e: EC context from crypto_ec_init()
    635  */
    636 void crypto_ec_deinit(struct crypto_ec *e);
    637 
    638 /**
    639  * crypto_ec_prime_len - Get length of the prime in octets
    640  * @e: EC context from crypto_ec_init()
    641  * Returns: Length of the prime defining the group
    642  */
    643 size_t crypto_ec_prime_len(struct crypto_ec *e);
    644 
    645 /**
    646  * crypto_ec_prime_len_bits - Get length of the prime in bits
    647  * @e: EC context from crypto_ec_init()
    648  * Returns: Length of the prime defining the group in bits
    649  */
    650 size_t crypto_ec_prime_len_bits(struct crypto_ec *e);
    651 
    652 /**
    653  * crypto_ec_get_prime - Get prime defining an EC group
    654  * @e: EC context from crypto_ec_init()
    655  * Returns: Prime (bignum) defining the group
    656  */
    657 const struct crypto_bignum * crypto_ec_get_prime(struct crypto_ec *e);
    658 
    659 /**
    660  * crypto_ec_get_order - Get order of an EC group
    661  * @e: EC context from crypto_ec_init()
    662  * Returns: Order (bignum) of the group
    663  */
    664 const struct crypto_bignum * crypto_ec_get_order(struct crypto_ec *e);
    665 
    666 /**
    667  * struct crypto_ec_point - Elliptic curve point
    668  *
    669  * Internal data structure for EC implementation to represent a point. The
    670  * contents is specific to the used crypto library.
    671  */
    672 struct crypto_ec_point;
    673 
    674 /**
    675  * crypto_ec_point_init - Initialize data for an EC point
    676  * @e: EC context from crypto_ec_init()
    677  * Returns: Pointer to EC point data or %NULL on failure
    678  */
    679 struct crypto_ec_point * crypto_ec_point_init(struct crypto_ec *e);
    680 
    681 /**
    682  * crypto_ec_point_deinit - Deinitialize EC point data
    683  * @p: EC point data from crypto_ec_point_init()
    684  * @clear: Whether to clear the EC point value from memory
    685  */
    686 void crypto_ec_point_deinit(struct crypto_ec_point *p, int clear);
    687 
    688 /**
    689  * crypto_ec_point_to_bin - Write EC point value as binary data
    690  * @e: EC context from crypto_ec_init()
    691  * @p: EC point data from crypto_ec_point_init()
    692  * @x: Buffer for writing the binary data for x coordinate or %NULL if not used
    693  * @y: Buffer for writing the binary data for y coordinate or %NULL if not used
    694  * Returns: 0 on success, -1 on failure
    695  *
    696  * This function can be used to write an EC point as binary data in a format
    697  * that has the x and y coordinates in big endian byte order fields padded to
    698  * the length of the prime defining the group.
    699  */
    700 int crypto_ec_point_to_bin(struct crypto_ec *e,
    701 			   const struct crypto_ec_point *point, u8 *x, u8 *y);
    702 
    703 /**
    704  * crypto_ec_point_from_bin - Create EC point from binary data
    705  * @e: EC context from crypto_ec_init()
    706  * @val: Binary data to read the EC point from
    707  * Returns: Pointer to EC point data or %NULL on failure
    708  *
    709  * This function readers x and y coordinates of the EC point from the provided
    710  * buffer assuming the values are in big endian byte order with fields padded to
    711  * the length of the prime defining the group.
    712  */
    713 struct crypto_ec_point * crypto_ec_point_from_bin(struct crypto_ec *e,
    714 						  const u8 *val);
    715 
    716 /**
    717  * crypto_bignum_add - c = a + b
    718  * @e: EC context from crypto_ec_init()
    719  * @a: Bignum
    720  * @b: Bignum
    721  * @c: Bignum; used to store the result of a + b
    722  * Returns: 0 on success, -1 on failure
    723  */
    724 int crypto_ec_point_add(struct crypto_ec *e, const struct crypto_ec_point *a,
    725 			const struct crypto_ec_point *b,
    726 			struct crypto_ec_point *c);
    727 
    728 /**
    729  * crypto_bignum_mul - res = b * p
    730  * @e: EC context from crypto_ec_init()
    731  * @p: EC point
    732  * @b: Bignum
    733  * @res: EC point; used to store the result of b * p
    734  * Returns: 0 on success, -1 on failure
    735  */
    736 int crypto_ec_point_mul(struct crypto_ec *e, const struct crypto_ec_point *p,
    737 			const struct crypto_bignum *b,
    738 			struct crypto_ec_point *res);
    739 
    740 /**
    741  * crypto_ec_point_invert - Compute inverse of an EC point
    742  * @e: EC context from crypto_ec_init()
    743  * @p: EC point to invert (and result of the operation)
    744  * Returns: 0 on success, -1 on failure
    745  */
    746 int crypto_ec_point_invert(struct crypto_ec *e, struct crypto_ec_point *p);
    747 
    748 /**
    749  * crypto_ec_point_solve_y_coord - Solve y coordinate for an x coordinate
    750  * @e: EC context from crypto_ec_init()
    751  * @p: EC point to use for the returning the result
    752  * @x: x coordinate
    753  * @y_bit: y-bit (0 or 1) for selecting the y value to use
    754  * Returns: 0 on success, -1 on failure
    755  */
    756 int crypto_ec_point_solve_y_coord(struct crypto_ec *e,
    757 				  struct crypto_ec_point *p,
    758 				  const struct crypto_bignum *x, int y_bit);
    759 
    760 /**
    761  * crypto_ec_point_is_at_infinity - Check whether EC point is neutral element
    762  * @e: EC context from crypto_ec_init()
    763  * @p: EC point
    764  * Returns: 1 if the specified EC point is the neutral element of the group or
    765  *	0 if not
    766  */
    767 int crypto_ec_point_is_at_infinity(struct crypto_ec *e,
    768 				   const struct crypto_ec_point *p);
    769 
    770 /**
    771  * crypto_ec_point_is_on_curve - Check whether EC point is on curve
    772  * @e: EC context from crypto_ec_init()
    773  * @p: EC point
    774  * Returns: 1 if the specified EC point is on the curve or 0 if not
    775  */
    776 int crypto_ec_point_is_on_curve(struct crypto_ec *e,
    777 				const struct crypto_ec_point *p);
    778 
    779 #endif /* CRYPTO_H */
    780