crypto/ecc.h

   1 /*
   2  * Copyright (c) 2013, Kenneth MacKay
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions are
   7  * met:
   8  *  * Redistributions of source code must retain the above copyright
   9  *   notice, this list of conditions and the following disclaimer.
  10  *  * Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  *
  14  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  15  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  16  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  17  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  18  * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  19  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  20  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  24  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25  */
  26 #ifndef _CRYPTO_ECC_H
  27 #define _CRYPTO_ECC_H
  28
  29 #include <crypto/ecc_curve.h>
  30
  31 /* One digit is u64 qword. */
  32 #define ECC_CURVE_NIST_P192_DIGITS  3
  33 #define ECC_CURVE_NIST_P256_DIGITS  4
  34 #define ECC_CURVE_NIST_P384_DIGITS  6
  35 #define ECC_MAX_DIGITS              (512 / 64) /* due to ecrdsa */
  36
  37 #define ECC_DIGITS_TO_BYTES_SHIFT 3
  38
  39 #define ECC_MAX_BYTES (ECC_MAX_DIGITS << ECC_DIGITS_TO_BYTES_SHIFT)
  40
  41 #define ECC_POINT_INIT(x, y, ndigits)   (struct ecc_point) { x, y, ndigits }
  42
  43 /**
  44  * ecc_swap_digits() - Copy ndigits from big endian array to native array
  45  * @in:       Input array
  46  * @out:      Output array
  47  * @ndigits:  Number of digits to copy
  48  */
  49 static inline void ecc_swap_digits(const u64 *in, u64 *out, unsigned int ndigits)
  50 {
  51         const __be64 *src = (__force __be64 *)in;
  52         int i;
  53
  54         for (i = 0; i < ndigits; i++)
  55                 out[i] = be64_to_cpu(src[ndigits - 1 - i]);
  56 }
  57
  58 /**
  59  * ecc_is_key_valid() - Validate a given ECDH private key
  60  *
  61  * @curve_id:           id representing the curve to use
  62  * @ndigits:            curve's number of digits
  63  * @private_key:        private key to be used for the given curve
  64  * @private_key_len:    private key length
  65  *
  66  * Returns 0 if the key is acceptable, a negative value otherwise
  67  */
  68 int ecc_is_key_valid(unsigned int curve_id, unsigned int ndigits,
  69                      const u64 *private_key, unsigned int private_key_len);
  70
  71 /**
  72  * ecc_gen_privkey() -  Generates an ECC private key.
  73  * The private key is a random integer in the range 0 < random < n, where n is a
  74  * prime that is the order of the cyclic subgroup generated by the distinguished
  75  * point G.
  76  * @curve_id:           id representing the curve to use
  77  * @ndigits:            curve number of digits
  78  * @private_key:        buffer for storing the generated private key
  79  *
  80  * Returns 0 if the private key was generated successfully, a negative value
  81  * if an error occurred.
  82  */
  83 int ecc_gen_privkey(unsigned int curve_id, unsigned int ndigits, u64 *privkey);
  84
  85 /**
  86  * ecc_make_pub_key() - Compute an ECC public key
  87  *
  88  * @curve_id:           id representing the curve to use
  89  * @ndigits:            curve's number of digits
  90  * @private_key:        pregenerated private key for the given curve
  91  * @public_key:         buffer for storing the generated public key
  92  *
  93  * Returns 0 if the public key was generated successfully, a negative value
  94  * if an error occurred.
  95  */
  96 int ecc_make_pub_key(const unsigned int curve_id, unsigned int ndigits,
  97                      const u64 *private_key, u64 *public_key);
  98
  99 /**
 100  * crypto_ecdh_shared_secret() - Compute a shared secret
 101  *
 102  * @curve_id:           id representing the curve to use
 103  * @ndigits:            curve's number of digits
 104  * @private_key:        private key of part A
 105  * @public_key:         public key of counterpart B
 106  * @secret:             buffer for storing the calculated shared secret
 107  *
 108  * Note: It is recommended that you hash the result of crypto_ecdh_shared_secret
 109  * before using it for symmetric encryption or HMAC.
 110  *
 111  * Returns 0 if the shared secret was generated successfully, a negative value
 112  * if an error occurred.
 113  */
 114 int crypto_ecdh_shared_secret(unsigned int curve_id, unsigned int ndigits,
 115                               const u64 *private_key, const u64 *public_key,
 116                               u64 *secret);
 117
 118 /**
 119  * ecc_is_pubkey_valid_partial() - Partial public key validation
 120  *
 121  * @curve:              elliptic curve domain parameters
 122  * @pk:                 public key as a point
 123  *
 124  * Valdiate public key according to SP800-56A section 5.6.2.3.4 ECC Partial
 125  * Public-Key Validation Routine.
 126  *
 127  * Note: There is no check that the public key is in the correct elliptic curve
 128  * subgroup.
 129  *
 130  * Return: 0 if validation is successful, -EINVAL if validation is failed.
 131  */
 132 int ecc_is_pubkey_valid_partial(const struct ecc_curve *curve,
 133                                 struct ecc_point *pk);
 134
 135 /**
 136  * ecc_is_pubkey_valid_full() - Full public key validation
 137  *
 138  * @curve:              elliptic curve domain parameters
 139  * @pk:                 public key as a point
 140  *
 141  * Valdiate public key according to SP800-56A section 5.6.2.3.3 ECC Full
 142  * Public-Key Validation Routine.
 143  *
 144  * Return: 0 if validation is successful, -EINVAL if validation is failed.
 145  */
 146 int ecc_is_pubkey_valid_full(const struct ecc_curve *curve,
 147                              struct ecc_point *pk);
 148
 149 /**
 150  * vli_is_zero() - Determine is vli is zero
 151  *
 152  * @vli:                vli to check.
 153  * @ndigits:            length of the @vli
 154  */
 155 bool vli_is_zero(const u64 *vli, unsigned int ndigits);
 156
 157 /**
 158  * vli_cmp() - compare left and right vlis
 159  *
 160  * @left:               vli
 161  * @right:              vli
 162  * @ndigits:            length of both vlis
 163  *
 164  * Returns sign of @left - @right, i.e. -1 if @left < @right,
 165  * 0 if @left == @right, 1 if @left > @right.
 166  */
 167 int vli_cmp(const u64 *left, const u64 *right, unsigned int ndigits);
 168
 169 /**
 170  * vli_sub() - Subtracts right from left
 171  *
 172  * @result:             where to write result
 173  * @left:               vli
 174  * @right               vli
 175  * @ndigits:            length of all vlis
 176  *
 177  * Note: can modify in-place.
 178  *
 179  * Return: carry bit.
 180  */
 181 u64 vli_sub(u64 *result, const u64 *left, const u64 *right,
 182             unsigned int ndigits);
 183
 184 /**
 185  * vli_from_be64() - Load vli from big-endian u64 array
 186  *
 187  * @dest:               destination vli
 188  * @src:                source array of u64 BE values
 189  * @ndigits:            length of both vli and array
 190  */
 191 void vli_from_be64(u64 *dest, const void *src, unsigned int ndigits);
 192
 193 /**
 194  * vli_from_le64() - Load vli from little-endian u64 array
 195  *
 196  * @dest:               destination vli
 197  * @src:                source array of u64 LE values
 198  * @ndigits:            length of both vli and array
 199  */
 200 void vli_from_le64(u64 *dest, const void *src, unsigned int ndigits);
 201
 202 /**
 203  * vli_mod_inv() - Modular inversion
 204  *
 205  * @result:             where to write vli number
 206  * @input:              vli value to operate on
 207  * @mod:                modulus
 208  * @ndigits:            length of all vlis
 209  */
 210 void vli_mod_inv(u64 *result, const u64 *input, const u64 *mod,
 211                  unsigned int ndigits);
 212
 213 /**
 214  * vli_mod_mult_slow() - Modular multiplication
 215  *
 216  * @result:             where to write result value
 217  * @left:               vli number to multiply with @right
 218  * @right:              vli number to multiply with @left
 219  * @mod:                modulus
 220  * @ndigits:            length of all vlis
 221  *
 222  * Note: Assumes that mod is big enough curve order.
 223  */
 224 void vli_mod_mult_slow(u64 *result, const u64 *left, const u64 *right,
 225                        const u64 *mod, unsigned int ndigits);
 226
 227 /**
 228  * ecc_point_mult_shamir() - Add two points multiplied by scalars
 229  *
 230  * @result:             resulting point
 231  * @x:                  scalar to multiply with @p
 232  * @p:                  point to multiply with @x
 233  * @y:                  scalar to multiply with @q
 234  * @q:                  point to multiply with @y
 235  * @curve:              curve
 236  *
 237  * Returns result = x * p + x * q over the curve.
 238  * This works faster than two multiplications and addition.
 239  */
 240 void ecc_point_mult_shamir(const struct ecc_point *result,
 241                            const u64 *x, const struct ecc_point *p,
 242                            const u64 *y, const struct ecc_point *q,
 243                            const struct ecc_curve *curve);
 244 #endif