doc/crypto/ec.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ec - Elliptic Curve functions
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/ec.h>
  10  #include <openssl/bn.h>
  11
  12  const EC_METHOD *EC_GFp_simple_method(void);
  13  const EC_METHOD *EC_GFp_mont_method(void);
  14  const EC_METHOD *EC_GFp_nist_method(void);
  15  const EC_METHOD *EC_GFp_nistp224_method(void);
  16  const EC_METHOD *EC_GFp_nistp256_method(void);
  17  const EC_METHOD *EC_GFp_nistp521_method(void);
  18
  19  const EC_METHOD *EC_GF2m_simple_method(void);
  20
  21  EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
  22  void EC_GROUP_free(EC_GROUP *group);
  23  void EC_GROUP_clear_free(EC_GROUP *group);
  24  int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src);
  25  EC_GROUP *EC_GROUP_dup(const EC_GROUP *src);
  26  const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group);
  27  int EC_METHOD_get_field_type(const EC_METHOD *meth);
  28  int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor);
  29  const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group);
  30  int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx);
  31  int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx);
  32  void EC_GROUP_set_curve_name(EC_GROUP *group, int nid);
  33  int EC_GROUP_get_curve_name(const EC_GROUP *group);
  34  void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag);
  35  int EC_GROUP_get_asn1_flag(const EC_GROUP *group);
  36  void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form);
  37  point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *);
  38  unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x);
  39  size_t EC_GROUP_get_seed_len(const EC_GROUP *);
  40  size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len);
  41  int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
  42  int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
  43  int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
  44  int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
  45  int EC_GROUP_get_degree(const EC_GROUP *group);
  46  int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx);
  47  int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx);
  48  int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx);
  49  EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
  50  EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
  51  EC_GROUP *EC_GROUP_new_by_curve_name(int nid);
  52
  53  size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);
  54
  55  EC_POINT *EC_POINT_new(const EC_GROUP *group);
  56  void EC_POINT_free(EC_POINT *point);
  57  void EC_POINT_clear_free(EC_POINT *point);
  58  int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src);
  59  EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group);
  60  const EC_METHOD *EC_POINT_method_of(const EC_POINT *point);
  61  int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point);
  62  int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,
  63         const BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *ctx);
  64  int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group,
  65         const EC_POINT *p, BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *ctx);
  66  int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,
  67         const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx);
  68  int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group,
  69         const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
  70  int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,
  71         const BIGNUM *x, int y_bit, BN_CTX *ctx);
  72  int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p,
  73         const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx);
  74  int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group,
  75         const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
  76  int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p,
  77         const BIGNUM *x, int y_bit, BN_CTX *ctx);
  78  size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p,
  79         point_conversion_form_t form,
  80         unsigned char *buf, size_t len, BN_CTX *ctx);
  81  int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p,
  82         const unsigned char *buf, size_t len, BN_CTX *ctx);
  83  BIGNUM *EC_POINT_point2bn(const EC_GROUP *, const EC_POINT *,
  84         point_conversion_form_t form, BIGNUM *, BN_CTX *);
  85  EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *,
  86         EC_POINT *, BN_CTX *);
  87  char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *,
  88         point_conversion_form_t form, BN_CTX *);
  89  EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *,
  90         EC_POINT *, BN_CTX *);
  91
  92  int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);
  93  int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx);
  94  int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx);
  95  int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p);
  96  int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx);
  97  int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);
  98  int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx);
  99  int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, EC_POINT *points[], BN_CTX *ctx);
 100  int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num, const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx);
 101  int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx);
 102  int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx);
 103  int EC_GROUP_have_precompute_mult(const EC_GROUP *group);
 104
 105  int EC_GROUP_get_basis_type(const EC_GROUP *);
 106  int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k);
 107  int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1,
 108         unsigned int *k2, unsigned int *k3);
 109  EC_GROUP *d2i_ECPKParameters(EC_GROUP **, const unsigned char **in, long len);
 110  int i2d_ECPKParameters(const EC_GROUP *, unsigned char **out);
 111  #define d2i_ECPKParameters_bio(bp,x) ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x)
 112  #define i2d_ECPKParameters_bio(bp,x) ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x)
 113  #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL, \
 114                 (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x))
 115  #define i2d_ECPKParameters_fp(fp,x) ASN1_i2d_fp(i2d_ECPKParameters,(fp), \
 116                 (unsigned char *)(x))
 117  int     ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off);
 118  int     ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off);
 119
 120  EC_KEY *EC_KEY_new(void);
 121  int EC_KEY_get_flags(const EC_KEY *key);
 122  void EC_KEY_set_flags(EC_KEY *key, int flags);
 123  void EC_KEY_clear_flags(EC_KEY *key, int flags);
 124  EC_KEY *EC_KEY_new_by_curve_name(int nid);
 125  void EC_KEY_free(EC_KEY *key);
 126  EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src);
 127  EC_KEY *EC_KEY_dup(const EC_KEY *src);
 128  int EC_KEY_up_ref(EC_KEY *key);
 129  const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key);
 130  int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group);
 131  const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key);
 132  int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv);
 133  const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key);
 134  int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub);
 135  unsigned EC_KEY_get_enc_flags(const EC_KEY *key);
 136  void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags);
 137  point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key);
 138  void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform);
 139  void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag);
 140  int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx);
 141  int EC_KEY_generate_key(EC_KEY *key);
 142  int EC_KEY_check_key(const EC_KEY *key);
 143  int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y);
 144
 145  EC_KEY *d2i_ECPrivateKey(EC_KEY **key, const unsigned char **in, long len);
 146  int i2d_ECPrivateKey(EC_KEY *key, unsigned char **out);
 147
 148  EC_KEY *d2i_ECParameters(EC_KEY **key, const unsigned char **in, long len);
 149  int i2d_ECParameters(EC_KEY *key, unsigned char **out);
 150
 151  EC_KEY *o2i_ECPublicKey(EC_KEY **key, const unsigned char **in, long len);
 152  int i2o_ECPublicKey(EC_KEY *key, unsigned char **out);
 153  int    ECParameters_print(BIO *bp, const EC_KEY *key);
 154  int    EC_KEY_print(BIO *bp, const EC_KEY *key, int off);
 155  int    ECParameters_print_fp(FILE *fp, const EC_KEY *key);
 156  int    EC_KEY_print_fp(FILE *fp, const EC_KEY *key, int off);
 157  #define ECParameters_dup(x) ASN1_dup_of(EC_KEY,i2d_ECParameters,d2i_ECParameters,x)
 158  #define EVP_PKEY_CTX_set_ec_paramgen_curve_nid(ctx, nid) \
 159         EVP_PKEY_CTX_ctrl(ctx, EVP_PKEY_EC, EVP_PKEY_OP_PARAMGEN, \
 160                                 EVP_PKEY_CTRL_EC_PARAMGEN_CURVE_NID, nid, NULL)
 161  const EC_KEY_METHOD *EC_KEY_get_method(const EC_KEY *key);
 162  int EC_KEY_set_method(EC_KEY *key, const EC_KEY_METHOD *meth);
 163
 164 =head1 DESCRIPTION
 165
 166 This library provides an extensive set of functions for performing operations on elliptic curves over finite fields.
 167 In general an elliptic curve is one with an equation of the form:
 168
 169 y^2 = x^3 + ax + b
 170
 171 An B<EC_GROUP> structure is used to represent the definition of an elliptic curve. Points on a curve are stored using an
 172 B<EC_POINT> structure. An B<EC_KEY> is used to hold a private/public key pair, where a private key is simply a BIGNUM and a
 173 public key is a point on a curve (represented by an B<EC_POINT>).
 174
 175 The library contains a number of alternative implementations of the different functions. Each implementation is optimised
 176 for different scenarios. No matter which implementation is being used, the interface remains the same. The library
 177 handles calling the correct implementation when an interface function is invoked. An implementation is represented by
 178 an B<EC_METHOD> structure.
 179
 180 The creation and destruction of B<EC_GROUP> objects is described in L<EC_GROUP_new(3)>. Functions for
 181 manipulating B<EC_GROUP> objects are described in L<EC_GROUP_copy(3)>.
 182
 183 Functions for creating, destroying and manipulating B<EC_POINT> objects are explained in L<EC_POINT_new(3)>,
 184 whilst functions for performing mathematical operations and tests on B<EC_POINTs> are covered in L<EC_POINT_add(3)>.
 185
 186 For working with private and public keys refer to L<EC_KEY_new(3)>. Implementations are covered in
 187 L<EC_GFp_simple_method(3)>.
 188
 189 For information on encoding and decoding curve parameters to and from ASN1 see L<d2i_ECPKParameters(3)>.
 190
 191 =head1 SEE ALSO
 192
 193 L<crypto(3)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
 194 L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
 195 L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
 196
 197
 198 =head1 COPYRIGHT
 199
 200 Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
 201
 202 Licensed under the OpenSSL license (the "License").  You may not use
 203 this file except in compliance with the License.  You can obtain a copy
 204 in the file LICENSE in the source distribution or at
 205 L<https://www.openssl.org/source/license.html>.
 206
 207 =cut