EC_GROUP_NEW_CURVE_GFP(3) | Library Functions Manual | EC_GROUP_NEW_CURVE_GFP(3)

# 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.

# SEE ALSO

BN_new(3), BN_num_bits(3), crypto(3), d2i_ECPKParameters(3), EC_GROUP_check(3), EC_GROUP_get_curve_name(3), EC_GROUP_new_by_curve_name(3), EC_KEY_METHOD_new(3), EC_KEY_new(3), EC_POINT_add(3), EC_POINT_get_affine_coordinates(3), EC_POINT_new(3), EC_POINT_point2oct(3), ECDH_compute_key(3), ECDSA_SIG_new(3)

# 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.

August 31, 2025 | Debian