Add documentation for the new non-curve type specific EC functions

Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/6815)

diff --git a/doc/man3/EC_GROUP_new.pod b/doc/man3/EC_GROUP_new.pod
index e36c3cb33f2eedc6c85b285a5a6abff52ca502c5..02caba8823e567ce5fb5d665bef2d2202513e711 100644 (file)
--- a/doc/man3/EC_GROUP_new.pod
+++ b/doc/man3/EC_GROUP_new.pod
@@ -2,12 +2,22 @@
 
 =head1 NAME
 
 
 =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_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
 
 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);
 
                                    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,
  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<irreducible polynomi
 use a trinomial or a pentanomial for this parameter.
 
 A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B<meth> (see
 use a trinomial or a pentanomial for this parameter.
 
 A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B<meth> (see

-L<EC_GFp_simple_method(3)>). 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<EC_GFp_simple_method(3)>). 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<params> and
 EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B<params>.
 
 EC_GROUP_new_from_ecparameters() will create a group from the
 specified B<params> and
 EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B<params>.
 

-EC_GROUP_set_curve_GFp sets the curve parameters B<p>, B<a> and B<b> for a curve over Fp stored in B<group>.
-EC_group_get_curve_GFp obtains the previously set curve parameters.
+EC_GROUP_set_curve() sets the curve parameters B<p>, B<a> and B<b>. For a curve over Fp B<b>
+is the prime for the field. For a curve over F2^m B<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.

 
 

-EC_GROUP_set_curve_GF2m sets the equivalent curve parameters for a curve over F2^m. In this case B<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.
-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
 
 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 2d86777206df0ea9496940d5eb29e03ef128f20e..b4faf4d021f7885db8f13c7ba8e0e034559f313b 100644 (file)
--- a/doc/man3/EC_POINT_new.pod
+++ b/doc/man3/EC_POINT_new.pod
@@ -2,16 +2,30 @@
 
 =head1 NAME
 
 
 =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_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_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
 
 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);
                                               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);
  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
 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<x> and B<y> co-ordinates for
-the point B<p> defined over the curve given in B<group>. The functions
-EC_POINT_get_affine_coordinates_GFp() and
-EC_POINT_get_affine_coordinates_GF2m() set B<x> and B<y>, either of which may
-be NULL, to the corresponding coordinates of B<p>.
+position. The function EC_POINT_set_affine_coordinates() sets the B<x> and B<y>
+co-ordinates for the point B<p> defined over the curve given in B<group>. The
+function EC_POINT_get_affine_coordinates() sets B<x> and B<y>, either of which
+may be NULL, to the corresponding coordinates of B<p>.
+
+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
 
 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
 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<x> is the x
+using the EC_POINT_set_compressed_coordinates() function where B<x> is the x

 co-ordinate and B<y_bit> is a value 0 or 1 to identify which of the two
 possible values for y should be used.
 
 co-ordinate and B<y_bit> 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<EC_POINT> can be converted to and from various external
 representations. The octet form is the binary encoding of the B<ECPoint>
 structure (as defined in RFC5480 and used in certificates and TLS records):
 In addition B<EC_POINT> can be converted to and from various external
 representations. The octet form is the binary encoding of the B<ECPoint>
 structure (as defined in RFC5480 and used in certificates and TLS records):