From de34e45a64f0865264b826255adbe7aee7470780 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Mon, 30 Jul 2018 16:06:12 +0100 Subject: [PATCH] Add documentation for the new non-curve type specific EC functions Reviewed-by: Rich Salz (Merged from https://github.com/openssl/openssl/pull/6815) --- doc/man3/EC_GROUP_new.pod | 46 +++++++++++++++++++---------- doc/man3/EC_POINT_new.pod | 61 +++++++++++++++++++++++++++++---------- 2 files changed, 77 insertions(+), 30 deletions(-) diff --git a/doc/man3/EC_GROUP_new.pod b/doc/man3/EC_GROUP_new.pod index e36c3cb33f..02caba8823 100644 --- a/doc/man3/EC_GROUP_new.pod +++ b/doc/man3/EC_GROUP_new.pod @@ -2,12 +2,22 @@ =head1 NAME -EC_GROUP_get_ecparameters, EC_GROUP_get_ecpkparameters, -EC_GROUP_new, EC_GROUP_new_from_ecparameters, +EC_GROUP_get_ecparameters, +EC_GROUP_get_ecpkparameters, +EC_GROUP_new, +EC_GROUP_new_from_ecparameters, EC_GROUP_new_from_ecpkparameters, -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_GFp, -EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m, +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 - Functions for creating and destroying EC_GROUP objects @@ -27,6 +37,10 @@ objects 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, @@ -58,22 +72,24 @@ Operations in a binary field are performed relative to an B (see -L). It is then necessary to call either EC_GROUP_set_curve_GFp or -EC_GROUP_set_curve_GF2m as appropriate to create a curve defined over Fp or over F2^m respectively. +L). It is then necessary to call EC_GROUP_set_curve() to set the curve parameters. EC_GROUP_new_from_ecparameters() will create a group from the specified B and EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B. -EC_GROUP_set_curve_GFp sets the curve parameters B

, B and B for a curve over Fp stored in B. -EC_group_get_curve_GFp obtains the previously set curve parameters. +EC_GROUP_set_curve() sets the curve parameters B

, B and B. For a curve over Fp B +is the prime for the field. For a curve over F2^m B

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. -EC_GROUP_set_curve_GF2m sets the equivalent curve parameters for a curve over F2^m. In this case B

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. -EC_group_get_curve_GF2m obtains the previously set curve parameters. +EC_group_get_curve() obtains the previously set curve parameters. -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. +EC_GROUP_set_curve_GFp() and EC_GROUP_set_curve_GF2m are synonyms for EC_GROUP_set_curve(). + +EC_GROUP_get_curve_GFp() and EC_GROUP_get_curve_GF2m are 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 then the +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 diff --git a/doc/man3/EC_POINT_new.pod b/doc/man3/EC_POINT_new.pod index 2d86777206..b4faf4d021 100644 --- a/doc/man3/EC_POINT_new.pod +++ b/doc/man3/EC_POINT_new.pod @@ -2,16 +2,30 @@ =head1 NAME -EC_POINT_set_Jprojective_coordinates_GFp, EC_POINT_point2buf, -EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, -EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of, +EC_POINT_set_Jprojective_coordinates_GFp, +EC_POINT_point2buf, +EC_POINT_new, +EC_POINT_free, +EC_POINT_clear_free, +EC_POINT_copy, +EC_POINT_dup, +EC_POINT_method_of, EC_POINT_set_to_infinity, EC_POINT_get_Jprojective_coordinates_GFp, +EC_POINT_set_affine_coordinates, +EC_POINT_get_affine_coordinates, +EC_POINT_set_compressed_coordinates, EC_POINT_set_affine_coordinates_GFp, -EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp, -EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, -EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct, -EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex, +EC_POINT_get_affine_coordinates_GFp, +EC_POINT_set_compressed_coordinates_GFp, +EC_POINT_set_affine_coordinates_GF2m, +EC_POINT_get_affine_coordinates_GF2m, +EC_POINT_set_compressed_coordinates_GF2m, +EC_POINT_point2oct, +EC_POINT_oct2point, +EC_POINT_point2bn, +EC_POINT_bn2point, +EC_POINT_point2hex, EC_POINT_hex2point - Functions for creating, destroying and manipulating EC_POINT objects @@ -34,6 +48,14 @@ EC_POINT_hex2point const EC_POINT *p, BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *ctx); + int EC_POINT_set_affine_coordinates(const EC_GROUP *group, EC_POINT *p, + const BIGNUM *x, const BIGNUM *y, + BN_CTX *ctx); + int EC_POINT_get_affine_coordinates(const EC_GROUP *group, const EC_POINT *p, + BIGNUM *x, BIGNUM *y, BN_CTX *ctx); + int EC_POINT_set_compressed_coordinates(const EC_GROUP *group, EC_POINT *p, + const BIGNUM *x, int y_bit, + BN_CTX *ctx); int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); @@ -97,12 +119,18 @@ A valid point on a curve is the special point at infinity. A point is set to be at infinity by calling EC_POINT_set_to_infinity(). The affine co-ordinates for a point describe a point in terms of its x and y -position. The functions EC_POINT_set_affine_coordinates_GFp() and -EC_POINT_set_affine_coordinates_GF2m() set the B and B co-ordinates for -the point B

defined over the curve given in B. The functions -EC_POINT_get_affine_coordinates_GFp() and -EC_POINT_get_affine_coordinates_GF2m() set B and B, either of which may -be NULL, to the corresponding coordinates of B

. +position. The function EC_POINT_set_affine_coordinates() sets the B and B +co-ordinates for the point B

defined over the curve given in B. The +function EC_POINT_get_affine_coordinates() sets B and B, either of which +may be NULL, to the corresponding coordinates of B

. + +The functions EC_POINT_set_affine_coordinates_GFp() and +EC_POINT_set_affine_coordinates_GF2m() are synonyms for +EC_POINT_set_affine_coordinates(). + +The functions EC_POINT_get_affine_coordinates_GFp() and +EC_POINT_get_affine_coordinates_GF2m() are synonyms for +EC_POINT_get_affine_coordinates(). As well as the affine co-ordinates, a point can alternatively be described in terms of its Jacobian projective co-ordinates (for Fp curves only). Jacobian @@ -119,11 +147,14 @@ EC_POINT_get_Jprojective_coordinates_GFp() respectively. Points can also be described in terms of their compressed co-ordinates. For a point (x, y), for any given value for x such that the point is on the curve there will only ever be two possible values for y. Therefore a point can be set -using the EC_POINT_set_compressed_coordinates_GFp() and -EC_POINT_set_compressed_coordinates_GF2m() functions where B is the x +using the EC_POINT_set_compressed_coordinates() function where B is the x co-ordinate and B is a value 0 or 1 to identify which of the two possible values for y should be used. +The functions EC_POINT_set_compressed_coordinates_GFp() and +EC_POINT_set_compressed_coordinates_GF2m() are synonyms for +EC_POINT_set_compressed_coordinates(). + In addition B can be converted to and from various external representations. The octet form is the binary encoding of the B structure (as defined in RFC5480 and used in certificates and TLS records): -- 2.34.1