Merge documentation of EC_GROUP_order_bits(3) from the OpenSSL 1.1.1

branch, which is still under a free license.
While here, also merge a few other improvements, mostly regarding
EC_GROUP_get_order(3) and EC_GROUP_get_cofactor(3); in particular,
some statements below RETURN VALUES were outright wrong.
This patch includes a few minor tweaks and an addition to HISTORY by me.
Feedback and OK tb@.

diff --git a/lib/libcrypto/man/EC_GROUP_copy.3 b/lib/libcrypto/man/EC_GROUP_copy.3
index bdbd72c..a69017f 100644 (file)
--- a/lib/libcrypto/man/EC_GROUP_copy.3
+++ b/lib/libcrypto/man/EC_GROUP_copy.3
@@ -1,8 +1,10 @@
-.\"    $OpenBSD: EC_GROUP_copy.3,v 1.10 2018/03/23 23:18:17 schwarze Exp $
-.\"    OpenSSL aafbe1cc Jun 12 23:42:08 2013 +0100
+.\" $OpenBSD: EC_GROUP_copy.3,v 1.11 2021/09/11 17:59:04 schwarze Exp $
+.\" full merge up to: OpenSSL aafbe1cc Jun 12 23:42:08 2013 +0100
+.\" selective merge up to: OpenSSL 24c23e1f Aug 22 10:51:25 2019 +0530
 .\"
-.\" This file was written by Matt Caswell <matt@openssl.org>.
-.\" Copyright (c) 2013, 2015 The OpenSSL Project.  All rights reserved.
+.\" This file was written by Matt Caswell <matt@openssl.org>
+.\" and Jayaram X Matta <jayaramx.matta@intel.com>.
+.\" Copyright (c) 2013, 2015, 2019 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -48,7 +50,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 23 2018 $
+.Dd $Mdocdate: September 11 2021 $
 .Dt EC_GROUP_COPY 3
 .Os
 .Sh NAME
@@ -58,6 +60,7 @@
 .Nm EC_GROUP_set_generator ,
 .Nm EC_GROUP_get0_generator ,
 .Nm EC_GROUP_get_order ,
+.Nm EC_GROUP_order_bits ,
 .Nm EC_GROUP_get_cofactor ,
 .Nm EC_GROUP_set_curve_name ,
 .Nm EC_GROUP_get_curve_name ,
@@ -110,6 +113,10 @@
 .Fa "BN_CTX *ctx"
 .Fc
 .Ft int
+.Fo EC_GROUP_order_bits
+.Fa "const EC_GROUP *group"
+.Fc
+.Ft int
 .Fo EC_GROUP_get_cofactor
 .Fa "const EC_GROUP *group"
 .Fa "BIGNUM *cofactor"
@@ -250,16 +257,23 @@ gives the number of points on the curve.
 returns the generator for the identified
 .Fa group .
 .Pp
-The functions
 .Fn EC_GROUP_get_order
-and
+retrieves the order of the
+.Fa group
+and copies its value into
+.Fa order .
+It fails if the order of the
+.Fa group
+is not set or set to zero.
+.Pp
 .Fn EC_GROUP_get_cofactor
-populate the provided
-.Fa order
-and
-.Fa cofactor
-parameters with the respective order and cofactors for the
-.Fa group .
+retrieves the cofactor of the
+.Fa group
+and copies its value into
+.Fa cofactor .
+It fails if the cofactor of the
+.Fa group
+is not set or set to zero.
 .Pp
 The functions
 .Fn EC_GROUP_set_curve_name
@@ -269,7 +283,8 @@ set and get the NID for the curve, respectively (see
 .Xr EC_GROUP_new 3 ) .
 If a curve does not have a NID associated with it, then
 .Fn EC_GROUP_get_curve_name
-will return 0.
+will return
+.Dv NID_undef .
 .Pp
 The asn1_flag value on a curve is used to determine whether there is a
 specific ASN.1 OID to describe the curve or not.
@@ -292,7 +307,7 @@ typedef enum {
        /** the point is encoded as z||x, where the octet z specifies
         *   which solution of the quadratic equation y is  */
        POINT_CONVERSION_COMPRESSED = 2,
-       /** the point is encoded as z||x||y, where z is the octet 0x02  */
+       /** the point is encoded as z||x||y, where z is the octet 0x04  */
        POINT_CONVERSION_UNCOMPRESSED = 4,
        /** the point is encoded as z||x||y, where the octet z specifies
          *  which solution of the quadratic equation y is  */
@@ -437,18 +452,43 @@ returns the generator for the given curve or
 .Dv NULL
 on error.
 .Pp
-.Fn EC_GROUP_get_order ,
-.Fn EC_GROUP_get_cofactor ,
-.Fn EC_GROUP_get_curve_name ,
-.Fn EC_GROUP_get_asn1_flag ,
-.Fn EC_GROUP_get_point_conversion_form ,
-and
-.Fn EC_GROUP_get_degree
-return the order, cofactor, curve name (NID), ASN.1 flag,
-point_conversion_form and degree for the specified curve, respectively.
-If there is no curve name associated with a curve then
+.Fn EC_GROUP_get_order
+returns 0 if the order is not set or set to zero for the
+.Fa group
+or if copying into
+.Fa order
+fails, or 1 otherwise.
+.Pp
+.Fn EC_GROUP_order_bits
+returns the number of bits in the group order.
+.Pp
+.Fn EC_GROUP_get_cofactor
+returns 0 if the cofactor is not set or set to zero for the
+.Fa group
+or if copying into
+.Fa cofactor
+fails, or 1 otherwise.
+.Pp
 .Fn EC_GROUP_get_curve_name
-returns 0.
+returns the curve name (NID) for the
+.Fa group
+or
+.Dv NID_undef
+if no curve name is associated.
+.Pp
+.Fn EC_GROUP_get_asn1_flag
+returns the ASN.1 flag for the specified
+.Fa group .
+.Pp
+.Fn EC_GROUP_get_point_conversion_form
+returns the point_conversion_form for the
+.Fa group .
+.Pp
+.Fn EC_GROUP_get_degree
+returns the degree for the
+.Fa group
+or 0 if the operation is not supported
+by the underlying group implementation.
 .Pp
 .Fn EC_GROUP_get0_seed
 returns a pointer to the seed that was used to generate the parameter
@@ -516,3 +556,7 @@ and
 .Fn EC_GROUP_get_pentanomial_basis
 first appeared in OpenSSL 0.9.8 and has been available since
 .Ox 4.5 .
+.Pp
+.Fn EC_GROUP_order_bits
+first appeared in OpenSSL 1.1.0 and has been available since
+.Ox 7.0 .