src/crypto/crypto.h

   1 /*
   2  * Wrapper functions for crypto libraries
   3  * Copyright (c) 2004-2013, Jouni Malinen <j@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  * sha384_vector - SHA384 hash for data vector
  84  * @num_elem: Number of elements in the data vector
  85  * @addr: Pointers to the data areas
  86  * @len: Lengths of the data blocks
  87  * @mac: Buffer for the hash
  88  * Returns: 0 on success, -1 on failure
  89  */
  90 int sha384_vector(size_t num_elem, const u8 *addr[], const size_t *len,
  91                   u8 *mac);
  92
  93 /**
  94  * sha512_vector - SHA512 hash for data vector
  95  * @num_elem: Number of elements in the data vector
  96  * @addr: Pointers to the data areas
  97  * @len: Lengths of the data blocks
  98  * @mac: Buffer for the hash
  99  * Returns: 0 on success, -1 on failure
 100  */
 101 int sha512_vector(size_t num_elem, const u8 *addr[], const size_t *len,
 102                   u8 *mac);
 103
 104 /**
 105  * des_encrypt - Encrypt one block with DES
 106  * @clear: 8 octets (in)
 107  * @key: 7 octets (in) (no parity bits included)
 108  * @cypher: 8 octets (out)
 109  */
 110 void des_encrypt(const u8 *clear, const u8 *key, u8 *cypher);
 111
 112 /**
 113  * aes_encrypt_init - Initialize AES for encryption
 114  * @key: Encryption 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_encrypt_init(const u8 *key, size_t len);
 119
 120 /**
 121  * aes_encrypt - Encrypt one AES block
 122  * @ctx: Context pointer from aes_encrypt_init()
 123  * @plain: Plaintext data to be encrypted (16 bytes)
 124  * @crypt: Buffer for the encrypted data (16 bytes)
 125  */
 126 void aes_encrypt(void *ctx, const u8 *plain, u8 *crypt);
 127
 128 /**
 129  * aes_encrypt_deinit - Deinitialize AES encryption
 130  * @ctx: Context pointer from aes_encrypt_init()
 131  */
 132 void aes_encrypt_deinit(void *ctx);
 133
 134 /**
 135  * aes_decrypt_init - Initialize AES for decryption
 136  * @key: Decryption key
 137  * @len: Key length in bytes (usually 16, i.e., 128 bits)
 138  * Returns: Pointer to context data or %NULL on failure
 139  */
 140 void * aes_decrypt_init(const u8 *key, size_t len);
 141
 142 /**
 143  * aes_decrypt - Decrypt one AES block
 144  * @ctx: Context pointer from aes_encrypt_init()
 145  * @crypt: Encrypted data (16 bytes)
 146  * @plain: Buffer for the decrypted data (16 bytes)
 147  */
 148 void aes_decrypt(void *ctx, const u8 *crypt, u8 *plain);
 149
 150 /**
 151  * aes_decrypt_deinit - Deinitialize AES decryption
 152  * @ctx: Context pointer from aes_encrypt_init()
 153  */
 154 void aes_decrypt_deinit(void *ctx);
 155
 156
 157 enum crypto_hash_alg {
 158         CRYPTO_HASH_ALG_MD5, CRYPTO_HASH_ALG_SHA1,
 159         CRYPTO_HASH_ALG_HMAC_MD5, CRYPTO_HASH_ALG_HMAC_SHA1,
 160         CRYPTO_HASH_ALG_SHA256, CRYPTO_HASH_ALG_HMAC_SHA256,
 161         CRYPTO_HASH_ALG_SHA384, CRYPTO_HASH_ALG_SHA512
 162 };
 163
 164 struct crypto_hash;
 165
 166 /**
 167  * crypto_hash_init - Initialize hash/HMAC function
 168  * @alg: Hash algorithm
 169  * @key: Key for keyed hash (e.g., HMAC) or %NULL if not needed
 170  * @key_len: Length of the key in bytes
 171  * Returns: Pointer to hash context to use with other hash functions or %NULL
 172  * on failure
 173  *
 174  * This function is only used with internal TLSv1 implementation
 175  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 176  * to implement this.
 177  */
 178 struct crypto_hash * crypto_hash_init(enum crypto_hash_alg alg, const u8 *key,
 179                                       size_t key_len);
 180
 181 /**
 182  * crypto_hash_update - Add data to hash calculation
 183  * @ctx: Context pointer from crypto_hash_init()
 184  * @data: Data buffer to add
 185  * @len: Length of the buffer
 186  *
 187  * This function is only used with internal TLSv1 implementation
 188  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 189  * to implement this.
 190  */
 191 void crypto_hash_update(struct crypto_hash *ctx, const u8 *data, size_t len);
 192
 193 /**
 194  * crypto_hash_finish - Complete hash calculation
 195  * @ctx: Context pointer from crypto_hash_init()
 196  * @hash: Buffer for hash value or %NULL if caller is just freeing the hash
 197  * context
 198  * @len: Pointer to length of the buffer or %NULL if caller is just freeing the
 199  * hash context; on return, this is set to the actual length of the hash value
 200  * Returns: 0 on success, -1 if buffer is too small (len set to needed length),
 201  * or -2 on other failures (including failed crypto_hash_update() operations)
 202  *
 203  * This function calculates the hash value and frees the context buffer that
 204  * was used for hash calculation.
 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 int crypto_hash_finish(struct crypto_hash *ctx, u8 *hash, size_t *len);
 211
 212
 213 enum crypto_cipher_alg {
 214         CRYPTO_CIPHER_NULL = 0, CRYPTO_CIPHER_ALG_AES, CRYPTO_CIPHER_ALG_3DES,
 215         CRYPTO_CIPHER_ALG_DES, CRYPTO_CIPHER_ALG_RC2, CRYPTO_CIPHER_ALG_RC4
 216 };
 217
 218 struct crypto_cipher;
 219
 220 /**
 221  * crypto_cipher_init - Initialize block/stream cipher function
 222  * @alg: Cipher algorithm
 223  * @iv: Initialization vector for block ciphers or %NULL for stream ciphers
 224  * @key: Cipher key
 225  * @key_len: Length of key in bytes
 226  * Returns: Pointer to cipher context to use with other cipher functions or
 227  * %NULL on failure
 228  *
 229  * This function is only used with internal TLSv1 implementation
 230  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 231  * to implement this.
 232  */
 233 struct crypto_cipher * crypto_cipher_init(enum crypto_cipher_alg alg,
 234                                           const u8 *iv, const u8 *key,
 235                                           size_t key_len);
 236
 237 /**
 238  * crypto_cipher_encrypt - Cipher encrypt
 239  * @ctx: Context pointer from crypto_cipher_init()
 240  * @plain: Plaintext to cipher
 241  * @crypt: Resulting ciphertext
 242  * @len: Length of the plaintext
 243  * Returns: 0 on success, -1 on failure
 244  *
 245  * This function is only used with internal TLSv1 implementation
 246  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 247  * to implement this.
 248  */
 249 int __must_check crypto_cipher_encrypt(struct crypto_cipher *ctx,
 250                                        const u8 *plain, u8 *crypt, size_t len);
 251
 252 /**
 253  * crypto_cipher_decrypt - Cipher decrypt
 254  * @ctx: Context pointer from crypto_cipher_init()
 255  * @crypt: Ciphertext to decrypt
 256  * @plain: Resulting plaintext
 257  * @len: Length of the cipher text
 258  * Returns: 0 on success, -1 on failure
 259  *
 260  * This function is only used with internal TLSv1 implementation
 261  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 262  * to implement this.
 263  */
 264 int __must_check crypto_cipher_decrypt(struct crypto_cipher *ctx,
 265                                        const u8 *crypt, u8 *plain, size_t len);
 266
 267 /**
 268  * crypto_cipher_decrypt - Free cipher context
 269  * @ctx: Context pointer from crypto_cipher_init()
 270  *
 271  * This function is only used with internal TLSv1 implementation
 272  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 273  * to implement this.
 274  */
 275 void crypto_cipher_deinit(struct crypto_cipher *ctx);
 276
 277
 278 struct crypto_public_key;
 279 struct crypto_private_key;
 280
 281 /**
 282  * crypto_public_key_import - Import an RSA public key
 283  * @key: Key buffer (DER encoded RSA public key)
 284  * @len: Key buffer length in bytes
 285  * Returns: Pointer to the public key or %NULL on failure
 286  *
 287  * This function can just return %NULL if the crypto library supports X.509
 288  * parsing. In that case, crypto_public_key_from_cert() is used to import the
 289  * public key from a certificate.
 290  *
 291  * This function is only used with internal TLSv1 implementation
 292  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 293  * to implement this.
 294  */
 295 struct crypto_public_key * crypto_public_key_import(const u8 *key, size_t len);
 296
 297 struct crypto_public_key *
 298 crypto_public_key_import_parts(const u8 *n, size_t n_len,
 299                                const u8 *e, size_t e_len);
 300
 301 /**
 302  * crypto_private_key_import - Import an RSA private key
 303  * @key: Key buffer (DER encoded RSA private key)
 304  * @len: Key buffer length in bytes
 305  * @passwd: Key encryption password or %NULL if key is not encrypted
 306  * Returns: Pointer to the private key or %NULL on failure
 307  *
 308  * This function is only used with internal TLSv1 implementation
 309  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 310  * to implement this.
 311  */
 312 struct crypto_private_key * crypto_private_key_import(const u8 *key,
 313                                                       size_t len,
 314                                                       const char *passwd);
 315
 316 /**
 317  * crypto_public_key_from_cert - Import an RSA public key from a certificate
 318  * @buf: DER encoded X.509 certificate
 319  * @len: Certificate buffer length in bytes
 320  * Returns: Pointer to public key or %NULL on failure
 321  *
 322  * This function can just return %NULL if the crypto library does not support
 323  * X.509 parsing. In that case, internal code will be used to parse the
 324  * certificate and public key is imported using crypto_public_key_import().
 325  *
 326  * This function is only used with internal TLSv1 implementation
 327  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 328  * to implement this.
 329  */
 330 struct crypto_public_key * crypto_public_key_from_cert(const u8 *buf,
 331                                                        size_t len);
 332
 333 /**
 334  * crypto_public_key_encrypt_pkcs1_v15 - Public key encryption (PKCS #1 v1.5)
 335  * @key: Public key
 336  * @in: Plaintext buffer
 337  * @inlen: Length of plaintext buffer in bytes
 338  * @out: Output buffer for encrypted data
 339  * @outlen: Length of output buffer in bytes; set to used length on success
 340  * Returns: 0 on success, -1 on failure
 341  *
 342  * This function is only used with internal TLSv1 implementation
 343  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 344  * to implement this.
 345  */
 346 int __must_check crypto_public_key_encrypt_pkcs1_v15(
 347         struct crypto_public_key *key, const u8 *in, size_t inlen,
 348         u8 *out, size_t *outlen);
 349
 350 /**
 351  * crypto_private_key_decrypt_pkcs1_v15 - Private key decryption (PKCS #1 v1.5)
 352  * @key: Private key
 353  * @in: Encrypted buffer
 354  * @inlen: Length of encrypted buffer in bytes
 355  * @out: Output buffer for encrypted data
 356  * @outlen: Length of output buffer in bytes; set to used length on success
 357  * Returns: 0 on success, -1 on failure
 358  *
 359  * This function is only used with internal TLSv1 implementation
 360  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 361  * to implement this.
 362  */
 363 int __must_check crypto_private_key_decrypt_pkcs1_v15(
 364         struct crypto_private_key *key, const u8 *in, size_t inlen,
 365         u8 *out, size_t *outlen);
 366
 367 /**
 368  * crypto_private_key_sign_pkcs1 - Sign with private key (PKCS #1)
 369  * @key: Private key from crypto_private_key_import()
 370  * @in: Plaintext buffer
 371  * @inlen: Length of plaintext buffer in bytes
 372  * @out: Output buffer for encrypted (signed) data
 373  * @outlen: Length of output buffer in bytes; set to used length on success
 374  * Returns: 0 on success, -1 on failure
 375  *
 376  * This function is only used with internal TLSv1 implementation
 377  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 378  * to implement this.
 379  */
 380 int __must_check crypto_private_key_sign_pkcs1(struct crypto_private_key *key,
 381                                                const u8 *in, size_t inlen,
 382                                                u8 *out, size_t *outlen);
 383
 384 /**
 385  * crypto_public_key_free - Free public key
 386  * @key: Public key
 387  *
 388  * This function is only used with internal TLSv1 implementation
 389  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 390  * to implement this.
 391  */
 392 void crypto_public_key_free(struct crypto_public_key *key);
 393
 394 /**
 395  * crypto_private_key_free - Free private key
 396  * @key: Private key from crypto_private_key_import()
 397  *
 398  * This function is only used with internal TLSv1 implementation
 399  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 400  * to implement this.
 401  */
 402 void crypto_private_key_free(struct crypto_private_key *key);
 403
 404 /**
 405  * crypto_public_key_decrypt_pkcs1 - Decrypt PKCS #1 signature
 406  * @key: Public key
 407  * @crypt: Encrypted signature data (using the private key)
 408  * @crypt_len: Encrypted signature data length
 409  * @plain: Buffer for plaintext (at least crypt_len bytes)
 410  * @plain_len: Plaintext length (max buffer size on input, real len on output);
 411  * Returns: 0 on success, -1 on failure
 412  */
 413 int __must_check crypto_public_key_decrypt_pkcs1(
 414         struct crypto_public_key *key, const u8 *crypt, size_t crypt_len,
 415         u8 *plain, size_t *plain_len);
 416
 417 /**
 418  * crypto_global_init - Initialize crypto wrapper
 419  *
 420  * This function is only used with internal TLSv1 implementation
 421  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 422  * to implement this.
 423  */
 424 int __must_check crypto_global_init(void);
 425
 426 /**
 427  * crypto_global_deinit - Deinitialize crypto wrapper
 428  *
 429  * This function is only used with internal TLSv1 implementation
 430  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 431  * to implement this.
 432  */
 433 void crypto_global_deinit(void);
 434
 435 /**
 436  * crypto_mod_exp - Modular exponentiation of large integers
 437  * @base: Base integer (big endian byte array)
 438  * @base_len: Length of base integer in bytes
 439  * @power: Power integer (big endian byte array)
 440  * @power_len: Length of power integer in bytes
 441  * @modulus: Modulus integer (big endian byte array)
 442  * @modulus_len: Length of modulus integer in bytes
 443  * @result: Buffer for the result
 444  * @result_len: Result length (max buffer size on input, real len on output)
 445  * Returns: 0 on success, -1 on failure
 446  *
 447  * This function calculates result = base ^ power mod modulus. modules_len is
 448  * used as the maximum size of modulus buffer. It is set to the used size on
 449  * success.
 450  *
 451  * This function is only used with internal TLSv1 implementation
 452  * (CONFIG_TLS=internal). If that is not used, the crypto wrapper does not need
 453  * to implement this.
 454  */
 455 int __must_check crypto_mod_exp(const u8 *base, size_t base_len,
 456                                 const u8 *power, size_t power_len,
 457                                 const u8 *modulus, size_t modulus_len,
 458                                 u8 *result, size_t *result_len);
 459
 460 /**
 461  * rc4_skip - XOR RC4 stream to given data with skip-stream-start
 462  * @key: RC4 key
 463  * @keylen: RC4 key length
 464  * @skip: number of bytes to skip from the beginning of the RC4 stream
 465  * @data: data to be XOR'ed with RC4 stream
 466  * @data_len: buf length
 467  * Returns: 0 on success, -1 on failure
 468  *
 469  * Generate RC4 pseudo random stream for the given key, skip beginning of the
 470  * stream, and XOR the end result with the data buffer to perform RC4
 471  * encryption/decryption.
 472  */
 473 int rc4_skip(const u8 *key, size_t keylen, size_t skip,
 474              u8 *data, size_t data_len);
 475
 476 /**
 477  * crypto_get_random - Generate cryptographically strong pseudy-random bytes
 478  * @buf: Buffer for data
 479  * @len: Number of bytes to generate
 480  * Returns: 0 on success, -1 on failure
 481  *
 482  * If the PRNG does not have enough entropy to ensure unpredictable byte
 483  * sequence, this functions must return -1.
 484  */
 485 int crypto_get_random(void *buf, size_t len);
 486
 487
 488 /**
 489  * struct crypto_bignum - bignum
 490  *
 491  * Internal data structure for bignum implementation. The contents is specific
 492  * to the used crypto library.
 493  */
 494 struct crypto_bignum;
 495
 496 /**
 497  * crypto_bignum_init - Allocate memory for bignum
 498  * Returns: Pointer to allocated bignum or %NULL on failure
 499  */
 500 struct crypto_bignum * crypto_bignum_init(void);
 501
 502 /**
 503  * crypto_bignum_init_set - Allocate memory for bignum and set the value
 504  * @buf: Buffer with unsigned binary value
 505  * @len: Length of buf in octets
 506  * Returns: Pointer to allocated bignum or %NULL on failure
 507  */
 508 struct crypto_bignum * crypto_bignum_init_set(const u8 *buf, size_t len);
 509
 510 /**
 511  * crypto_bignum_deinit - Free bignum
 512  * @n: Bignum from crypto_bignum_init() or crypto_bignum_init_set()
 513  * @clear: Whether to clear the value from memory
 514  */
 515 void crypto_bignum_deinit(struct crypto_bignum *n, int clear);
 516
 517 /**
 518  * crypto_bignum_to_bin - Set binary buffer to unsigned bignum
 519  * @a: Bignum
 520  * @buf: Buffer for the binary number
 521  * @len: Length of @buf in octets
 522  * @padlen: Length in octets to pad the result to or 0 to indicate no padding
 523  * Returns: Number of octets written on success, -1 on failure
 524  */
 525 int crypto_bignum_to_bin(const struct crypto_bignum *a,
 526                          u8 *buf, size_t buflen, size_t padlen);
 527
 528 /**
 529  * crypto_bignum_add - c = a + b
 530  * @a: Bignum
 531  * @b: Bignum
 532  * @c: Bignum; used to store the result of a + b
 533  * Returns: 0 on success, -1 on failure
 534  */
 535 int crypto_bignum_add(const struct crypto_bignum *a,
 536                       const struct crypto_bignum *b,
 537                       struct crypto_bignum *c);
 538
 539 /**
 540  * crypto_bignum_mod - c = a % b
 541  * @a: Bignum
 542  * @b: Bignum
 543  * @c: Bignum; used to store the result of a % b
 544  * Returns: 0 on success, -1 on failure
 545  */
 546 int crypto_bignum_mod(const struct crypto_bignum *a,
 547                       const struct crypto_bignum *b,
 548                       struct crypto_bignum *c);
 549
 550 /**
 551  * crypto_bignum_exptmod - Modular exponentiation: d = a^b (mod c)
 552  * @a: Bignum; base
 553  * @b: Bignum; exponent
 554  * @c: Bignum; modulus
 555  * @d: Bignum; used to store the result of a^b (mod c)
 556  * Returns: 0 on success, -1 on failure
 557  */
 558 int crypto_bignum_exptmod(const struct crypto_bignum *a,
 559                           const struct crypto_bignum *b,
 560                           const struct crypto_bignum *c,
 561                           struct crypto_bignum *d);
 562
 563 /**
 564  * crypto_bignum_inverse - Inverse a bignum so that a * c = 1 (mod b)
 565  * @a: Bignum
 566  * @b: Bignum
 567  * @c: Bignum; used to store the result
 568  * Returns: 0 on success, -1 on failure
 569  */
 570 int crypto_bignum_inverse(const struct crypto_bignum *a,
 571                           const struct crypto_bignum *b,
 572                           struct crypto_bignum *c);
 573
 574 /**
 575  * crypto_bignum_sub - c = a - b
 576  * @a: Bignum
 577  * @b: Bignum
 578  * @c: Bignum; used to store the result of a - b
 579  * Returns: 0 on success, -1 on failure
 580  */
 581 int crypto_bignum_sub(const struct crypto_bignum *a,
 582                       const struct crypto_bignum *b,
 583                       struct crypto_bignum *c);
 584
 585 /**
 586  * crypto_bignum_div - c = a / b
 587  * @a: Bignum
 588  * @b: Bignum
 589  * @c: Bignum; used to store the result of a / b
 590  * Returns: 0 on success, -1 on failure
 591  */
 592 int crypto_bignum_div(const struct crypto_bignum *a,
 593                       const struct crypto_bignum *b,
 594                       struct crypto_bignum *c);
 595
 596 /**
 597  * crypto_bignum_mulmod - d = a * b (mod c)
 598  * @a: Bignum
 599  * @b: Bignum
 600  * @c: Bignum
 601  * @d: Bignum; used to store the result of (a * b) % c
 602  * Returns: 0 on success, -1 on failure
 603  */
 604 int crypto_bignum_mulmod(const struct crypto_bignum *a,
 605                          const struct crypto_bignum *b,
 606                          const struct crypto_bignum *c,
 607                          struct crypto_bignum *d);
 608
 609 /**
 610  * crypto_bignum_cmp - Compare two bignums
 611  * @a: Bignum
 612  * @b: Bignum
 613  * Returns: -1 if a < b, 0 if a == b, or 1 if a > b
 614  */
 615 int crypto_bignum_cmp(const struct crypto_bignum *a,
 616                       const struct crypto_bignum *b);
 617
 618 /**
 619  * crypto_bignum_bits - Get size of a bignum in bits
 620  * @a: Bignum
 621  * Returns: Number of bits in the bignum
 622  */
 623 int crypto_bignum_bits(const struct crypto_bignum *a);
 624
 625 /**
 626  * crypto_bignum_is_zero - Is the given bignum zero
 627  * @a: Bignum
 628  * Returns: 1 if @a is zero or 0 if not
 629  */
 630 int crypto_bignum_is_zero(const struct crypto_bignum *a);
 631
 632 /**
 633  * crypto_bignum_is_one - Is the given bignum one
 634  * @a: Bignum
 635  * Returns: 1 if @a is one or 0 if not
 636  */
 637 int crypto_bignum_is_one(const struct crypto_bignum *a);
 638
 639 /**
 640  * crypto_bignum_legendre - Compute the Legendre symbol (a/p)
 641  * @a: Bignum
 642  * @p: Bignum
 643  * Returns: Legendre symbol -1,0,1 on success; -2 on calculation failure
 644  */
 645 int crypto_bignum_legendre(const struct crypto_bignum *a,
 646                            const struct crypto_bignum *p);
 647
 648 /**
 649  * struct crypto_ec - Elliptic curve context
 650  *
 651  * Internal data structure for EC implementation. The contents is specific
 652  * to the used crypto library.
 653  */
 654 struct crypto_ec;
 655
 656 /**
 657  * crypto_ec_init - Initialize elliptic curve context
 658  * @group: Identifying number for the ECC group (IANA "Group Description"
 659  *      attribute registrty for RFC 2409)
 660  * Returns: Pointer to EC context or %NULL on failure
 661  */
 662 struct crypto_ec * crypto_ec_init(int group);
 663
 664 /**
 665  * crypto_ec_deinit - Deinitialize elliptic curve context
 666  * @e: EC context from crypto_ec_init()
 667  */
 668 void crypto_ec_deinit(struct crypto_ec *e);
 669
 670 /**
 671  * crypto_ec_prime_len - Get length of the prime in octets
 672  * @e: EC context from crypto_ec_init()
 673  * Returns: Length of the prime defining the group
 674  */
 675 size_t crypto_ec_prime_len(struct crypto_ec *e);
 676
 677 /**
 678  * crypto_ec_prime_len_bits - Get length of the prime in bits
 679  * @e: EC context from crypto_ec_init()
 680  * Returns: Length of the prime defining the group in bits
 681  */
 682 size_t crypto_ec_prime_len_bits(struct crypto_ec *e);
 683
 684 /**
 685  * crypto_ec_get_prime - Get prime defining an EC group
 686  * @e: EC context from crypto_ec_init()
 687  * Returns: Prime (bignum) defining the group
 688  */
 689 const struct crypto_bignum * crypto_ec_get_prime(struct crypto_ec *e);
 690
 691 /**
 692  * crypto_ec_get_order - Get order of an EC group
 693  * @e: EC context from crypto_ec_init()
 694  * Returns: Order (bignum) of the group
 695  */
 696 const struct crypto_bignum * crypto_ec_get_order(struct crypto_ec *e);
 697
 698 /**
 699  * struct crypto_ec_point - Elliptic curve point
 700  *
 701  * Internal data structure for EC implementation to represent a point. The
 702  * contents is specific to the used crypto library.
 703  */
 704 struct crypto_ec_point;
 705
 706 /**
 707  * crypto_ec_point_init - Initialize data for an EC point
 708  * @e: EC context from crypto_ec_init()
 709  * Returns: Pointer to EC point data or %NULL on failure
 710  */
 711 struct crypto_ec_point * crypto_ec_point_init(struct crypto_ec *e);
 712
 713 /**
 714  * crypto_ec_point_deinit - Deinitialize EC point data
 715  * @p: EC point data from crypto_ec_point_init()
 716  * @clear: Whether to clear the EC point value from memory
 717  */
 718 void crypto_ec_point_deinit(struct crypto_ec_point *p, int clear);
 719
 720 /**
 721  * crypto_ec_point_to_bin - Write EC point value as binary data
 722  * @e: EC context from crypto_ec_init()
 723  * @p: EC point data from crypto_ec_point_init()
 724  * @x: Buffer for writing the binary data for x coordinate or %NULL if not used
 725  * @y: Buffer for writing the binary data for y coordinate or %NULL if not used
 726  * Returns: 0 on success, -1 on failure
 727  *
 728  * This function can be used to write an EC point as binary data in a format
 729  * that has the x and y coordinates in big endian byte order fields padded to
 730  * the length of the prime defining the group.
 731  */
 732 int crypto_ec_point_to_bin(struct crypto_ec *e,
 733                            const struct crypto_ec_point *point, u8 *x, u8 *y);
 734
 735 /**
 736  * crypto_ec_point_from_bin - Create EC point from binary data
 737  * @e: EC context from crypto_ec_init()
 738  * @val: Binary data to read the EC point from
 739  * Returns: Pointer to EC point data or %NULL on failure
 740  *
 741  * This function readers x and y coordinates of the EC point from the provided
 742  * buffer assuming the values are in big endian byte order with fields padded to
 743  * the length of the prime defining the group.
 744  */
 745 struct crypto_ec_point * crypto_ec_point_from_bin(struct crypto_ec *e,
 746                                                   const u8 *val);
 747
 748 /**
 749  * crypto_bignum_add - c = a + b
 750  * @e: EC context from crypto_ec_init()
 751  * @a: Bignum
 752  * @b: Bignum
 753  * @c: Bignum; used to store the result of a + b
 754  * Returns: 0 on success, -1 on failure
 755  */
 756 int crypto_ec_point_add(struct crypto_ec *e, const struct crypto_ec_point *a,
 757                         const struct crypto_ec_point *b,
 758                         struct crypto_ec_point *c);
 759
 760 /**
 761  * crypto_bignum_mul - res = b * p
 762  * @e: EC context from crypto_ec_init()
 763  * @p: EC point
 764  * @b: Bignum
 765  * @res: EC point; used to store the result of b * p
 766  * Returns: 0 on success, -1 on failure
 767  */
 768 int crypto_ec_point_mul(struct crypto_ec *e, const struct crypto_ec_point *p,
 769                         const struct crypto_bignum *b,
 770                         struct crypto_ec_point *res);
 771
 772 /**
 773  * crypto_ec_point_invert - Compute inverse of an EC point
 774  * @e: EC context from crypto_ec_init()
 775  * @p: EC point to invert (and result of the operation)
 776  * Returns: 0 on success, -1 on failure
 777  */
 778 int crypto_ec_point_invert(struct crypto_ec *e, struct crypto_ec_point *p);
 779
 780 /**
 781  * crypto_ec_point_solve_y_coord - Solve y coordinate for an x coordinate
 782  * @e: EC context from crypto_ec_init()
 783  * @p: EC point to use for the returning the result
 784  * @x: x coordinate
 785  * @y_bit: y-bit (0 or 1) for selecting the y value to use
 786  * Returns: 0 on success, -1 on failure
 787  */
 788 int crypto_ec_point_solve_y_coord(struct crypto_ec *e,
 789                                   struct crypto_ec_point *p,
 790                                   const struct crypto_bignum *x, int y_bit);
 791
 792 /**
 793  * crypto_ec_point_compute_y_sqr - Compute y^2 = x^3 + ax + b
 794  * @e: EC context from crypto_ec_init()
 795  * @x: x coordinate
 796  * Returns: y^2 on success, %NULL failure
 797  */
 798 struct crypto_bignum *
 799 crypto_ec_point_compute_y_sqr(struct crypto_ec *e,
 800                               const struct crypto_bignum *x);
 801
 802 /**
 803  * crypto_ec_point_is_at_infinity - Check whether EC point is neutral element
 804  * @e: EC context from crypto_ec_init()
 805  * @p: EC point
 806  * Returns: 1 if the specified EC point is the neutral element of the group or
 807  *      0 if not
 808  */
 809 int crypto_ec_point_is_at_infinity(struct crypto_ec *e,
 810                                    const struct crypto_ec_point *p);
 811
 812 /**
 813  * crypto_ec_point_is_on_curve - Check whether EC point is on curve
 814  * @e: EC context from crypto_ec_init()
 815  * @p: EC point
 816  * Returns: 1 if the specified EC point is on the curve or 0 if not
 817  */
 818 int crypto_ec_point_is_on_curve(struct crypto_ec *e,
 819                                 const struct crypto_ec_point *p);
 820
 821 /**
 822  * crypto_ec_point_cmp - Compare two EC points
 823  * @e: EC context from crypto_ec_init()
 824  * @a: EC point
 825  * @b: EC point
 826  * Returns: 0 on equal, non-zero otherwise
 827  */
 828 int crypto_ec_point_cmp(const struct crypto_ec *e,
 829                         const struct crypto_ec_point *a,
 830                         const struct crypto_ec_point *b);
 831
 832 #endif /* CRYPTO_H */