Sortix nightly manual
This manual documents Sortix nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.
EC_GROUP_NEW(3) | Library Functions Manual | EC_GROUP_NEW(3) |
NAME
EC_GROUP_new
,
EC_GROUP_free
,
EC_GROUP_clear_free
,
EC_GROUP_new_curve_GFp
,
EC_GROUP_new_curve_GF2m
,
EC_GROUP_new_by_curve_name
,
EC_GROUP_set_curve
,
EC_GROUP_get_curve
,
EC_GROUP_set_curve_GFp
,
EC_GROUP_get_curve_GFp
,
EC_GROUP_set_curve_GF2m
,
EC_GROUP_get_curve_GF2m
,
EC_get_builtin_curves
—
create and destroy EC_GROUP objects
SYNOPSIS
#include
<openssl/ec.h>
#include
<openssl/bn.h>
EC_GROUP *
EC_GROUP_new
(const
EC_METHOD *meth);
void
EC_GROUP_free
(EC_GROUP
*group);
void
EC_GROUP_clear_free
(EC_GROUP
*group);
EC_GROUP *
EC_GROUP_new_curve_GFp
(const
BIGNUM *p, const BIGNUM *a,
const BIGNUM *b,
BN_CTX *ctx);
EC_GROUP *
EC_GROUP_new_curve_GF2m
(const
BIGNUM *p, const BIGNUM *a,
const BIGNUM *b,
BN_CTX *ctx);
EC_GROUP *
EC_GROUP_new_by_curve_name
(int
nid);
int
EC_GROUP_set_curve
(EC_GROUP
*group, const BIGNUM *p,
const BIGNUM *a,
const BIGNUM *b,
BN_CTX *ctx);
int
EC_GROUP_get_curve
(const
EC_GROUP *group, BIGNUM *p,
BIGNUM *a, BIGNUM
*b, BN_CTX *ctx);
int
EC_GROUP_set_curve_GFp
(EC_GROUP
*group, const BIGNUM *p,
const BIGNUM *a,
const BIGNUM *b,
BN_CTX *ctx);
int
EC_GROUP_get_curve_GFp
(const
EC_GROUP *group, BIGNUM *p,
BIGNUM *a, BIGNUM
*b, BN_CTX *ctx);
int
EC_GROUP_set_curve_GF2m
(EC_GROUP
*group, const BIGNUM *p,
const BIGNUM *a,
const BIGNUM *b,
BN_CTX *ctx);
int
EC_GROUP_get_curve_GF2m
(const
EC_GROUP *group, BIGNUM *p,
BIGNUM *a, BIGNUM
*b, BN_CTX *ctx);
size_t
EC_get_builtin_curves
(EC_builtin_curve
*r, size_t nitems);
DESCRIPTION
The EC library provides functions for performing operations on elliptic curves over finite fields. In general, an elliptic curve satisfies an equation of the form:y^2 = x^3 + ax + b
y^2 mod p = x^3 + ax + b mod
p
y^2 + xy = x^3 + ax^2 + b (where b !=
0)
EC_GROUP_new
(), using the implementation
provided by meth (see
EC_GFp_simple_method(3)).
It is then necessary to call
EC_GROUP_set_curve
() to set the curve
parameters.
EC_GROUP_set_curve
() sets the curve
parameters p,
a, and b.
For a curve over Fp, p is the prime for the
field. For a curve over F2^m p represents the
irreducible polynomial - each bit represents a term in the polynomial.
Therefore, there will either be three or five bits set dependent on whether
the polynomial is a trinomial or a pentanomial. In either case,
a and b
represent the coefficients of the curve equation.
EC_GROUP_set_curve_GFp
() and
EC_GROUP_set_curve_GF2m
() are deprecated
synonyms for EC_GROUP_set_curve
().
EC_GROUP_get_curve
() obtains the previously
set curve parameters.
EC_GROUP_get_curve_GFp
() and
EC_GROUP_get_curve_GF2m
() are deprecated
synonyms for EC_GROUP_get_curve
().
The functions EC_GROUP_new_curve_GFp
() and
EC_GROUP_new_curve_GF2m
() are shortcuts for
calling EC_GROUP_new
() and the appropriate
EC_GROUP_set_curve_*
() function. An
appropriate default implementation method will be used.
Whilst the library can be used to create any curve using the functions described
above, there are also a number of predefined curves that are available. In
order to obtain a list of all of the predefined curves, call the function
EC_get_builtin_curves
(). The parameter
r should be an array of
EC_builtin_cure structures of size
nitems. The function will populate the
r array with information about the builtin
curves. If nitems is less than the total
number of curves available, then the first
nitems curves will be returned. Otherwise the
total number of curves will be provided. The return value is the total number
of curves available (whether that number has been populated in
r or not). Passing a
NULL
r, or
setting nitems to 0, will do nothing other
than return the total number of curves available. The
EC_builtin_curve structure is defined as
follows:
typedef struct { int nid; const char *comment; } EC_builtin_curve;
EC_GROUP_new_by_curve_name
() and provide
the nid of the curve to be constructed.
EC_GROUP_free
() frees the memory associated
with the EC_GROUP. If
group is a
NULL
pointer, no action occurs.
EC_GROUP_clear_free
() destroys any sensitive
data held within the EC_GROUP and then frees
its memory. If group is a
NULL
pointer, no action occurs.
RETURN VALUES
AllEC_GROUP_new*
() functions return a
pointer to the newly constructed group or
NULL
on error.
EC_get_builtin_curves
() returns the number of
builtin curves that are available.
EC_GROUP_set_curve
(),
EC_GROUP_get_curve
(),
EC_GROUP_set_curve_GFp
(),
EC_GROUP_get_curve_GFp
(),
EC_GROUP_set_curve_GF2m
(), and
EC_GROUP_get_curve_GF2m
() return 1 on
success or 0 on error.
SEE ALSO
crypto(3), d2i_ECPKParameters(3), EC_GFp_simple_method(3), EC_GROUP_copy(3), EC_KEY_new(3), EC_POINT_add(3), EC_POINT_new(3), ECDH_compute_key(3), ECDSA_SIG_new(3)HISTORY
EC_GROUP_new
(),
EC_GROUP_free
(),
EC_GROUP_clear_free
(),
EC_GROUP_new_curve_GFp
(),
EC_GROUP_set_curve_GFp
(), and
EC_GROUP_get_curve_GFp
() first appeared in
OpenSSL 0.9.7 and have been available since OpenBSD
3.2.
EC_GROUP_new_curve_GF2m
(),
EC_GROUP_new_by_curve_name
(),
EC_GROUP_set_curve_GF2m
(),
EC_GROUP_get_curve_GF2m
(), and
EC_get_builtin_curves
() first appeared in
OpenSSL 0.9.8 and have been available since OpenBSD
4.5. EC_GROUP_set_curve
() and
EC_GROUP_get_curve
() first appeared in
OpenSSL 1.1.1 and have been available since OpenBSD
7.0.March 31, 2022 | Debian |