libressl-EC_GROUP_new_by_curve_name3

Usage

Overview

Most elliptic curves used in cryptographic protocols have a standardized representation as a named curve, where an ASN.1 Object Identifier (OID) is used instead of detailed domain parameters. This OID is represented internally by a Numerical Identifier (NID), and the parameters themselves must be built into the library. In the EC library the curve name refers to this NID.

EC_GROUP_new_by_curve_name() returns a new EC_GROUP object representing the named curve corresponding to nid, using the parameters built into the library. It is equivalent to passing the appropriate parameters to EC_GROUP_new_curve_GFp(3), EC_GROUP_set_curve_name(3), EC_GROUP_set_generator(3) and EC_GROUP_set_seed(3).

EC_GROUP_free() frees group and all the memory associated with it. If group is NULL, no action occurs.

EC_GROUP_dup() creates a deep copy of group.

EC_GROUP_cmp() is intended to determine whether group1 and group2 represent the same elliptic curve, making use of the optional ctx. If the curve name is set on both curves, they are compared as integers, then the prime field, the coefficients of the Weierstrass equation, the generators, their order and their cofactors are compared using BN_cmp(3) or EC_POINT_cmp(3), respectively.

EC_get_builtin_curves() returns the number of builtin curves. If curves is NULL or ncurves is zero, it performs no other action. Otherwise, after reducing ncurves to the number of builtin curves if necessary, it copies the nid and a pointer to the comment of the first ncurves built-in curves to the array of EC_builtin_curve objects pointed to by curves and leaves the remainder of the array uninitialized.

Some curves can be identified by their NIST name in addition to the numerical identifier (NID). EC_curve_nist2nid() and EC_curve_nid2nist() translate between the two. The builtin NIST curves over a prime field are:

EC_curve_nist2nid() and EC_curve_nid2nist() also accept the binary curves defined in FIPS 186-4 and deprecated in SP800-186, as well as "P-192" and NID_X9_62_prime192v1, although all these no longer correspond to builtin curves in LibreSSL.

Return values

EC_GROUP_new_by_curve_name() returns a newly allocated group or NULL if there is no built-in group with NID nid, or if memory allocation fails.

EC_GROUP_dup() returns a newly allocated group or NULL if memory allocation fails.

EC_GROUP_cmp() returns 1 if the groups are distinct, 0 if the groups are considered identical and -1 on memory allocation error.

EC_get_builtin_curves() returns the number of builtin curves.

EC_curve_nid2nist() returns a string constant containing the NIST name if nid identifies a NIST curve or NULL otherwise.

EC_curve_nist2nid() returns the NID corresponding to the NIST curve name, or NID_undef.

Examples

Print the list of builtin curves, their NIDs, their NIST name and a comment describing each curve:

#include <err.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <openssl/ec.h>
int
main(void)
{
	EC_builtin_curve *curves;
	size_t ncurves, i;
	if (pledge("stdio", NULL) == -1)
		err(1, "pledge");
	ncurves = EC_get_builtin_curves(NULL, 0);
	if ((curves = calloc(ncurves, sizeof(*curves))) == NULL)
		err(1, NULL);
	(void)EC_get_builtin_curves(curves, ncurves);
	printf("curve\tnid\tNIST\tcomment\n");
	for (i = 0; i < ncurves; i++) {
		const char *nist_name = EC_curve_nid2nist(curves[i].nid);
		printf("%2zu\t%d\t%s\t%s\n", i, curves[i].nid,
		    nist_name != NULL ? nist_name : "", curves[i].comment);
	}
	free(curves);
	return 0;
}