|
Packit |
c4476c |
=pod
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NAME
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
EC_GROUP_get_ecparameters,
|
|
Packit |
c4476c |
EC_GROUP_get_ecpkparameters,
|
|
Packit |
c4476c |
EC_GROUP_new,
|
|
Packit |
c4476c |
EC_GROUP_new_from_ecparameters,
|
|
Packit |
c4476c |
EC_GROUP_new_from_ecpkparameters,
|
|
Packit |
c4476c |
EC_GROUP_free,
|
|
Packit |
c4476c |
EC_GROUP_clear_free,
|
|
Packit |
c4476c |
EC_GROUP_new_curve_GFp,
|
|
Packit |
c4476c |
EC_GROUP_new_curve_GF2m,
|
|
Packit |
c4476c |
EC_GROUP_new_by_curve_name,
|
|
Packit |
c4476c |
EC_GROUP_set_curve,
|
|
Packit |
c4476c |
EC_GROUP_get_curve,
|
|
Packit |
c4476c |
EC_GROUP_set_curve_GFp,
|
|
Packit |
c4476c |
EC_GROUP_get_curve_GFp,
|
|
Packit |
c4476c |
EC_GROUP_set_curve_GF2m,
|
|
Packit |
c4476c |
EC_GROUP_get_curve_GF2m,
|
|
Packit |
c4476c |
EC_get_builtin_curves - Functions for creating and destroying EC_GROUP
|
|
Packit |
c4476c |
objects
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SYNOPSIS
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
#include <openssl/ec.h>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
|
|
Packit |
c4476c |
EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params)
|
|
Packit |
c4476c |
EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params)
|
|
Packit |
c4476c |
void EC_GROUP_free(EC_GROUP *group);
|
|
Packit |
c4476c |
void EC_GROUP_clear_free(EC_GROUP *group);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a,
|
|
Packit |
c4476c |
const BIGNUM *b, BN_CTX *ctx);
|
|
Packit |
c4476c |
EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a,
|
|
Packit |
c4476c |
const BIGNUM *b, BN_CTX *ctx);
|
|
Packit |
c4476c |
EC_GROUP *EC_GROUP_new_by_curve_name(int nid);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
int EC_GROUP_set_curve(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a,
|
|
Packit |
c4476c |
const BIGNUM *b, BN_CTX *ctx);
|
|
Packit |
c4476c |
int EC_GROUP_get_curve(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b,
|
|
Packit |
c4476c |
BN_CTX *ctx);
|
|
Packit |
c4476c |
int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p,
|
|
Packit |
c4476c |
const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
|
|
Packit |
c4476c |
int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p,
|
|
Packit |
c4476c |
BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
|
|
Packit |
c4476c |
int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p,
|
|
Packit |
c4476c |
const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
|
|
Packit |
c4476c |
int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p,
|
|
Packit |
c4476c |
BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
ECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group, ECPARAMETERS *params)
|
|
Packit |
c4476c |
ECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group, ECPKPARAMETERS *params)
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 DESCRIPTION
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Within the library there are two forms of elliptic curve that are of interest.
|
|
Packit |
c4476c |
The first form is those defined over the prime field Fp. The elements of Fp are
|
|
Packit |
c4476c |
the integers 0 to p-1, where p is a prime number. This gives us a revised
|
|
Packit |
c4476c |
elliptic curve equation as follows:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
y^2 mod p = x^3 +ax + b mod p
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The second form is those defined over a binary field F2^m where the elements of
|
|
Packit |
c4476c |
the field are integers of length at most m bits. For this form the elliptic
|
|
Packit |
c4476c |
curve equation is modified to:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
y^2 + xy = x^3 + ax^2 + b (where b != 0)
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Operations in a binary field are performed relative to an B
|
|
Packit |
c4476c |
polynomial>. All such curves with OpenSSL use a trinomial or a pentanomial for
|
|
Packit |
c4476c |
this parameter.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
A new curve can be constructed by calling EC_GROUP_new(), using the
|
|
Packit |
c4476c |
implementation provided by B<meth> (see L<EC_GFp_simple_method(3)>). It is then
|
|
Packit |
c4476c |
necessary to call EC_GROUP_set_curve() to set the curve parameters.
|
|
Packit |
c4476c |
EC_GROUP_new_from_ecparameters() will create a group from the specified
|
|
Packit |
c4476c |
B<params> and EC_GROUP_new_from_ecpkparameters() will create a group from the
|
|
Packit |
c4476c |
specific PK B<params>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
EC_GROUP_set_curve() sets the curve parameters B, B and B. For a curve
|
|
Packit |
c4476c |
over Fp B is the prime for the field. For a curve over F2^m B represents
|
|
Packit |
c4476c |
the irreducible polynomial - each bit represents a term in the polynomial.
|
|
Packit |
c4476c |
Therefore there will either be three or five bits set dependent on whether the
|
|
Packit |
c4476c |
polynomial is a trinomial or a pentanomial.
|
|
Packit |
c4476c |
In either case, B and B represents the coefficients a and b from the
|
|
Packit |
c4476c |
relevant equation introduced above.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
EC_group_get_curve() obtains the previously set curve parameters.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
EC_GROUP_set_curve_GFp() and EC_GROUP_set_curve_GF2m() are synonyms for
|
|
Packit |
c4476c |
EC_GROUP_set_curve(). They are defined for backwards compatibility only and
|
|
Packit |
c4476c |
should not be used.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
EC_GROUP_get_curve_GFp() and EC_GROUP_get_curve_GF2m() are synonyms for
|
|
Packit |
c4476c |
EC_GROUP_get_curve(). They are defined for backwards compatibility only and
|
|
Packit |
c4476c |
should not be used.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The functions EC_GROUP_new_curve_GFp() and EC_GROUP_new_curve_GF2m() are
|
|
Packit |
c4476c |
shortcuts for calling EC_GROUP_new() and then the EC_GROUP_set_curve() function.
|
|
Packit |
c4476c |
An appropriate default implementation method will be used.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Whilst the library can be used to create any curve using the functions described
|
|
Packit |
c4476c |
above, there are also a number of predefined curves that are available. In order
|
|
Packit |
c4476c |
to obtain a list of all of the predefined curves, call the function
|
|
Packit |
c4476c |
EC_get_builtin_curves(). The parameter B<r> should be an array of
|
|
Packit |
c4476c |
EC_builtin_curve structures of size B<nitems>. The function will populate the
|
|
Packit |
c4476c |
B<r> array with information about the builtin curves. If B<nitems> is less than
|
|
Packit |
c4476c |
the total number of curves available, then the first B<nitems> curves will be
|
|
Packit |
c4476c |
returned. Otherwise the total number of curves will be provided. The return
|
|
Packit |
c4476c |
value is the total number of curves available (whether that number has been
|
|
Packit |
c4476c |
populated in B<r> or not). Passing a NULL B<r>, or setting B<nitems> to 0 will
|
|
Packit |
c4476c |
do nothing other than return the total number of curves available.
|
|
Packit |
c4476c |
The EC_builtin_curve structure is defined as follows:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
typedef struct {
|
|
Packit |
c4476c |
int nid;
|
|
Packit |
c4476c |
const char *comment;
|
|
Packit |
c4476c |
} EC_builtin_curve;
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Each EC_builtin_curve item has a unique integer id (B<nid>), and a human
|
|
Packit |
c4476c |
readable comment string describing the curve.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
In order to construct a builtin curve use the function
|
|
Packit |
c4476c |
EC_GROUP_new_by_curve_name() and provide the B<nid> of the curve to
|
|
Packit |
c4476c |
be constructed.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
EC_GROUP_free() frees the memory associated with the EC_GROUP.
|
|
Packit |
c4476c |
If B<group> is NULL nothing is done.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
EC_GROUP_clear_free() destroys any sensitive data held within the EC_GROUP and
|
|
Packit |
c4476c |
then frees its memory. If B<group> is NULL nothing is done.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 RETURN VALUES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
All EC_GROUP_new* functions return a pointer to the newly constructed group, or
|
|
Packit |
c4476c |
NULL on error.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
EC_get_builtin_curves() returns the number of builtin curves that are available.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
EC_GROUP_set_curve_GFp(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(),
|
|
Packit |
c4476c |
EC_GROUP_get_curve_GF2m() return 1 on success or 0 on error.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SEE ALSO
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
L<crypto(7)>, L<EC_GROUP_copy(3)>,
|
|
Packit |
c4476c |
L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
|
|
Packit |
c4476c |
L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 COPYRIGHT
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Copyright 2013-2019 The OpenSSL Project Authors. All Rights Reserved.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Licensed under the OpenSSL license (the "License"). You may not use
|
|
Packit |
c4476c |
this file except in compliance with the License. You can obtain a copy
|
|
Packit |
c4476c |
in the file LICENSE in the source distribution or at
|
|
Packit |
c4476c |
L<https://www.openssl.org/source/license.html>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=cut
|