Sortix cross-volatile manual

This manual documents Sortix cross-volatile. You can instead view this document in the latest official manual.

NAME

EC_GROUP_new_curve_GFp, EC_GROUP_set_curve, EC_GROUP_get_curve, EC_GROUP_set_generator, EC_GROUP_get0_generator, EC_GROUP_get_degree, EC_GROUP_get_order, EC_GROUP_order_bits, EC_GROUP_get_cofactor, EC_GROUP_clear_free, EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp — define elliptic curves and retrieve information from them

SYNOPSIS

library “libcrypto”
#include <openssl/bn.h>
#include <openssl/ec.h>

EC_GROUP *
EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);

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_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor);

const EC_POINT *
EC_GROUP_get0_generator(const EC_GROUP *group);

int
EC_GROUP_get_degree(const EC_GROUP *);

int
EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx);

int
EC_GROUP_order_bits(const EC_GROUP *group);

int
EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx);

Deprecated:

void
EC_GROUP_clear_free(EC_GROUP *group);

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);

DESCRIPTION

With the exception of the getters the functions in this manual should not be used. Use EC_GROUP_new_by_curve_name(3) instead.

The EC library uses EC_GROUP objects to represent elliptic curves in Weierstrass form. These curves are defined over the prime field of order p via the Weierstrass equation

y^2 = x^3 + ax + b

where a and b are such that the discriminant 4a^3 - 27b^2 is non-zero. They consist of affine points, which are pairs of field elements (x, y) satisfying the Weierstrass equation, and an extra point at infinity.

The points on an elliptic curve form a group. Cryptographic applications usually depend on the choice of a generator whose multiples form a cyclic subgroup of a certain order. By Lagrange's theorem, the number of points on the elliptic curve is the product of order and another integer called the cofactor. Hasse's theorem is the inequality

|order * cofactor - (p + 1)| <= 2 sqrt(p)

which implies an upper bound on order in terms of p and allows the computation of cofactor provided that order is large enough.

EC_GROUP_new_curve_GFp() instantiates a new EC_GROUP object over the prime field of size p with Weierstrass equation given by the coefficients a and b. The optional ctx is used to transform the other arguments into internal representation. It is the caller's responsibility to ensure that p is a prime number greater than three and that the discriminant is non-zero. This can be done with EC_GROUP_check_discriminant(3) or as part of EC_GROUP_check(3) after EC_GROUP_set_generator().

EC_GROUP_set_curve() sets the curve parameters of group to p, a, b using the optional ctx and the comments in EC_GROUP_new_curve_GFp() apply. Existing generator, order, or cofactor on group are left unmodified and become most likely invalid. They must therefore be set to legitimate values using EC_GROUP_set_generator().

EC_GROUP_get_curve() copies the curve parameters of group into the caller-owned p, a, and b, possibly making use of the ctx for conversion from internal representations. Except for group, all arguments are optional.

EC_GROUP_set_generator() performs sanity checks based on Hasse's theorem and copies generator, order and the optional cofactor into group, replacing all existing entries. It is the caller's responsibility to ensure that generator is a point on the curve and that order is its order, which can partially be accomplished with a subsequent call to EC_GROUP_check(3). If cofactor is NULL, it can be computed on curves of cryptographic interest, in which case cofactor is set to the computed value, otherwise it is set to zero.

EC_GROUP_get0_generator() returns an internal pointer to the group's generator, which may be NULL if no generator was set.

EC_GROUP_get_degree() returns the bit length of the prime p set on group.

EC_GROUP_get_order() copies the value of the group's order into the caller-owned order, returning failure if the group's order is zero. The ctx argument is ignored.

EC_GROUP_order_bits() returns the number of bits in the group's order, which is the result of calling BN_num_bits(3) on order. Unlike EC_GROUP_get_order(), it does not fail if order is zero.

EC_GROUP_get_cofactor() copies the value of the group's cofactor into the caller-owned cofactor, returning failure if the group's cofactor is zero. The ctx argument is ignored.

The deprecated EC_GROUP_clear_free() uses explicit_bzero(3) and freezero(3) to clear and free all data associated with group. If group is NULL, no action occurs. Since there is no secret data in group, this API is useless. In LibreSSL, EC_GROUP_free(3) and EC_GROUP_clear_free() behave identically.

EC_GROUP_set_curve_GFp() and EC_GROUP_get_curve_GFp() are deprecated aliases for EC_GROUP_set_curve() and EC_GROUP_get_curve(), respectively.

RETURN VALUES

EC_GROUP_new_curve_GFp() returns a newly allocated group or NULL if memory allocation fails, or if some minimal sanity checks on p, a, and b fail.

EC_GROUP_set_curve() and EC_GROUP_set_curve_GFp() return 1 on success and 0 on failure. Failure conditions include that p is smaller than or equal to three, or even, or memory allocation failure.

EC_GROUP_get_curve() and EC_GROUP_get_curve_GFp() return 1 on success and 0 on memory allocation failure.

EC_GROUP_set_generator() returns 1 on success and 0 on memory allocation failure, or if order or cofactor are larger than Hasse's theorem allows.

EC_GROUP_get0_generator() returns an internal pointer to the generator or NULL if none was set on group.

EC_GROUP_get_order() returns 1 on success or 0 on memory allocation failure or if the order is zero.

EC_GROUP_get_cofactor() returns 1 on success or 0 on memory allocation failure or if the cofactor is zero.

EC_GROUP_get_degree(), and EC_GROUP_order_bits() return the number of bits in the group's p, and order, respectively.

STANDARDS

SEC 1: Elliptic Curve Cryptography, Version 2.0, https://www.secg.org/sec1-v2.pdf, May 21, 2009.

SEC 2: Recommended Elliptic Curve Domain Parameters, Version 2.0, https://www.secg.org/sec2-v2.pdf, Jan 27, 2010.

HISTORY

EC_GROUP_new_curve_GFp(), EC_GROUP_clear_free(), EC_GROUP_set_curve_GFp(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_generator(), EC_GROUP_get0_generator(), EC_GROUP_get_order(), and EC_GROUP_get_cofactor() first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 3.2.

EC_GROUP_get_degree() first appeared in OpenSSL 0.9.8 and has been available since OpenBSD 4.5.

EC_GROUP_set_curve(), EC_GROUP_get_curve(), and EC_GROUP_order_bits() first appeared in OpenSSL 1.1.1 and have been available since OpenBSD 7.0

BUGS

Too many. The API is unergonomic and the design is very poor even by OpenSSL's standards. Naming is inconsistent, especially in regard to the _GFp suffix and the _get_ infix. Function signatures are inconsistent. In particular, functions that should have a BN_CTX argument don't have one and functions that don't need it have one.