Rework EC documentation

This replaces the giant, poor quality and outdated EC_GROUP_copy.3,
EC_GROUP_new.3, and EC_POINT_new.3 manuals with seven new manuals
written from scratch.

* EC_GROUP_new_by_curve_name() is the entry point for builtin curves,
* EC_GROUP_new_curve_GFp() describes lower level API that should not
  usually be needed apart from a handful of accessors.
* EC_GROUP_check() contains two functions that applications should not
  need because either you know for certain something is an elliptic
  curve (so these checks are pointless) or you should not use it.
* EC_GROUP_get_curve_name() describes some low level ASN.1 footguns
  and corresponding getters.
* EC_POINT_new() contains the simple EC_POINT allocation and freeing API
* EC_POINT_get_affine_coordinates() contains the coordinate accessors
* EC_POINT_point2oct() is about encoding elliptic curve points

While all this is quite far from perfect, the diff is getting too big
and it will be easier to improve this in tree. It is definitely more
repetitive than I would like it to be.

Reviews, tweaks and general feedback are of course welcome.

discussed with jsing

1 files changed, 0 insertions, 353 deletions

diff --git a/src/lib/libcrypto/man/EC_GROUP_new.3 b/src/lib/libcrypto/man/EC_GROUP_new.3
deleted file mode 100644
index 83e3e4c870..0000000000
--- a/src/lib/libcrypto/man/EC_GROUP_new.3
+++ /dev/null
@@ -1,353 +0,0 @@
-.\"     $OpenBSD: EC_GROUP_new.3,v 1.18 2025/03/08 16:38:13 tb Exp $
-.\"     OpenSSL 6328d367 Sat Jul 4 21:58:30 2020 +0200
-.\"
-.\" This file was written by Matt Caswell <matt@openssl.org>.
-.\" Copyright (c) 2013 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
-.\" are met:
-.\"
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\"
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in
-.\"    the documentation and/or other materials provided with the
-.\"    distribution.
-.\"
-.\" 3. All advertising materials mentioning features or use of this
-.\"    software must display the following acknowledgment:
-.\"    "This product includes software developed by the OpenSSL Project
-.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
-.\"
-.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
-.\"    endorse or promote products derived from this software without
-.\"    prior written permission. For written permission, please contact
-.\"    openssl-core@openssl.org.
-.\"
-.\" 5. Products derived from this software may not be called "OpenSSL"
-.\"    nor may "OpenSSL" appear in their names without prior written
-.\"    permission of the OpenSSL Project.
-.\"
-.\" 6. Redistributions of any form whatsoever must retain the following
-.\"    acknowledgment:
-.\"    "This product includes software developed by the OpenSSL Project
-.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
-.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
-.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
-.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
-.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
-.\" OF THE POSSIBILITY OF SUCH DAMAGE.
-.\"
-.Dd $Mdocdate: March 8 2025 $
-.Dt EC_GROUP_NEW 3
-.Os
-.Sh NAME
-.Nm EC_GROUP_new ,
-.Nm EC_GROUP_free ,
-.Nm EC_GROUP_clear_free ,
-.Nm EC_GROUP_new_curve_GFp ,
-.Nm EC_GROUP_new_by_curve_name ,
-.Nm EC_GROUP_set_curve ,
-.Nm EC_GROUP_get_curve ,
-.Nm EC_GROUP_set_curve_GFp ,
-.Nm EC_GROUP_get_curve_GFp ,
-.Nm EC_get_builtin_curves ,
-.Nm EC_curve_nid2nist ,
-.Nm EC_curve_nist2nid
-.Nd create and destroy EC_GROUP objects
-.Sh SYNOPSIS
-.In openssl/ec.h
-.In openssl/bn.h
-.Ft EC_GROUP *
-.Fo EC_GROUP_new
-.Fa "const EC_METHOD *meth"
-.Fc
-.Ft void
-.Fo EC_GROUP_free
-.Fa "EC_GROUP *group"
-.Fc
-.Ft void
-.Fo EC_GROUP_clear_free
-.Fa "EC_GROUP *group"
-.Fc
-.Ft EC_GROUP *
-.Fo EC_GROUP_new_curve_GFp
-.Fa "const BIGNUM *p"
-.Fa "const BIGNUM *a"
-.Fa "const BIGNUM *b"
-.Fa "BN_CTX *ctx"
-.Fc
-.Ft EC_GROUP *
-.Fo EC_GROUP_new_by_curve_name
-.Fa "int nid"
-.Fc
-.Ft int
-.Fo EC_GROUP_set_curve
-.Fa "EC_GROUP *group"
-.Fa "const BIGNUM *p"
-.Fa "const BIGNUM *a"
-.Fa "const BIGNUM *b"
-.Fa "BN_CTX *ctx"
-.Fc
-.Ft int
-.Fo EC_GROUP_get_curve
-.Fa "const EC_GROUP *group"
-.Fa "BIGNUM *p"
-.Fa "BIGNUM *a"
-.Fa "BIGNUM *b"
-.Fa "BN_CTX *ctx"
-.Fc
-.Ft int
-.Fo EC_GROUP_set_curve_GFp
-.Fa "EC_GROUP *group"
-.Fa "const BIGNUM *p"
-.Fa "const BIGNUM *a"
-.Fa "const BIGNUM *b"
-.Fa "BN_CTX *ctx"
-.Fc
-.Ft int
-.Fo EC_GROUP_get_curve_GFp
-.Fa "const EC_GROUP *group"
-.Fa "BIGNUM *p"
-.Fa "BIGNUM *a"
-.Fa "BIGNUM *b"
-.Fa "BN_CTX *ctx"
-.Fc
-.Ft size_t
-.Fo EC_get_builtin_curves
-.Fa "EC_builtin_curve *r"
-.Fa "size_t nitems"
-.Fc
-.Ft "const char *"
-.Fo EC_curve_nid2nist
-.Fa "int nid"
-.Fc
-.Ft int
-.Fo EC_curve_nist2nid
-.Fa "const char *name"
-.Fc
-.Sh DESCRIPTION
-The EC library provides functions for performing operations on
-elliptic curves in Weierstrass form.
-Such curves are defined over the prime field of order
-.Fa p
-and satisfy the Weierstrass equation with coefficients
-.Fa a
-and
-.Fa b
-.Pp
-.Dl y^2 = x^3 + ax + b
-.Pp
-An
-.Vt EC_GROUP
-structure is used to represent the definition of an elliptic curve.
-A new curve can be constructed by calling
-.Fn EC_GROUP_new ,
-using the implementation provided by
-.Fa meth .
-It is then necessary to call
-.Fn EC_GROUP_set_curve
-to set the curve parameters.
-.Pp
-.Fn EC_GROUP_set_curve
-sets the curve parameters
-.Fa p ,
-.Fa a ,
-and
-.Fa b ,
-where
-.Fa a
-and
-.Fa b
-represent the coefficients of the curve equation.
-.Pp
-.Fn EC_GROUP_set_curve_GFp
-is a deprecated synonym for
-.Fn EC_GROUP_set_curve .
-.Pp
-.Fn EC_GROUP_get_curve
-obtains the previously set curve parameters.
-.Pp
-.Fn EC_GROUP_get_curve_GFp
-is a deprecated synonym for
-.Fn EC_GROUP_get_curve .
-.Pp
-The function
-.Fn EC_GROUP_new_curve_GFp
-is a shortcut for calling
-.Fn EC_GROUP_new
-and
-.Fn EC_GROUP_set_curve .
-An appropriate default implementation method will be used.
-.Pp
-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
-.Fn EC_get_builtin_curves .
-The parameter
-.Fa r
-should be an array of
-.Vt EC_builtin_cure
-structures of size
-.Fa nitems .
-The function will populate the
-.Fa r
-array with information about the builtin curves.
-If
-.Fa nitems
-is less than the total number of curves available, then the first
-.Fa nitems
-curves will be returned.
-Otherwise the total number of curves will be provided.
-The return value is the total number of curves available (whether that
-number has been populated in
-.Fa r
-or not).
-Passing a
-.Dv NULL
-.Fa r ,
-or setting
-.Fa nitems
-to 0, will do nothing other than return the total number of curves
-available.
-The
-.Vt EC_builtin_curve
-structure is defined as follows:
-.Bd -literal
-typedef struct {
-        int nid;
-        const char *comment;
-} EC_builtin_curve;
-.Ed
-.Pp
-Each
-.Vt EC_builtin_curve
-item has a unique integer ID
-.Pq Fa nid
-and a human readable comment string describing the curve.
-.Pp
-In order to construct a builtin curve, use the function
-.Fn EC_GROUP_new_by_curve_name
-and provide the
-.Fa nid
-of the curve to be constructed.
-.Pp
-.Fn EC_GROUP_free
-frees the memory associated with the
-.Vt EC_GROUP .
-If
-.Fa group
-is a
-.Dv NULL
-pointer, no action occurs.
-.Pp
-.Fn EC_GROUP_clear_free
-destroys any sensitive data held within the
-.Vt EC_GROUP
-and then frees its memory.
-If
-.Fa group
-is a
-.Dv NULL
-pointer, no action occurs.
-.Pp
-Some builtin curves can be identified by their NIST name
-in addition to a numerical identifier (NID).
-.Fn EC_curve_nid2nist
-and
-.Fn EC_curve_nist2nid
-translate between the two.
-The five built-in prime curves are:
-.Pp
-.Bl -column "NIST name" NID_X9_62_prime256v1 "deprecated in SP800-186" -compact
-.It No NIST Fa name Ta Em ASN.1 NID       Ta Em notes
-.It Qq P-192   Ta Dv NID_X9_62_prime192v1 Ta No deprecated in SP800-186
-.It Qq P-224   Ta Dv NID_secp224r1        Ta
-.It Qq P-256   Ta Dv NID_X9_62_prime256v1 Ta
-.It Qq P-384   Ta Dv NID_secp384r1        Ta
-.It Qq P-521   Ta Dv NID_secp521r1        Ta
-.El
-.Pp
-.Fn EC_curve_nid2nist
-and
-.Fn EC_curve_nist2nid
-also accept the ten binary curves defined in FIPS\& 186-4
-and deprecated in SP800-186,
-although they no longer correspond to builtin curves in LibreSSL.
-.Sh RETURN VALUES
-All
-.Fn EC_GROUP_new*
-functions return a pointer to the newly constructed group or
-.Dv NULL
-on error.
-.Pp
-.Fn EC_get_builtin_curves
-returns the number of builtin curves that are available.
-.Pp
-.Fn EC_curve_nid2nist
-returns a string constant containing the NIST name if
-.Fa nid
-identifies a NIST curve or
-.Dv NULL
-otherwise.
-.Pp
-.Fn EC_curve_nist2nid
-returns the NID corresponding to the NIST curve
-.Fa name ,
-or
-.Dv NID_undef .
-.Pp
-.Fn EC_GROUP_set_curve ,
-.Fn EC_GROUP_get_curve ,
-.Fn EC_GROUP_set_curve_GFp ,
-and
-.Fn EC_GROUP_get_curve_GFp
-return 1 on success or 0 on error.
-.Sh SEE ALSO
-.Xr crypto 3 ,
-.Xr d2i_ECPKParameters 3 ,
-.Xr EC_GROUP_copy 3 ,
-.Xr EC_KEY_new 3 ,
-.Xr EC_POINT_add 3 ,
-.Xr EC_POINT_new 3 ,
-.Xr ECDH_compute_key 3 ,
-.Xr ECDSA_SIG_new 3
-.Sh HISTORY
-.Fn EC_GROUP_new ,
-.Fn EC_GROUP_free ,
-.Fn EC_GROUP_clear_free ,
-.Fn EC_GROUP_new_curve_GFp ,
-.Fn EC_GROUP_set_curve_GFp ,
-and
-.Fn EC_GROUP_get_curve_GFp
-first appeared in OpenSSL 0.9.7 and have been available since
-.Ox 3.2 .
-.Pp
-.Fn EC_GROUP_new_by_curve_name
-and
-.Fn EC_get_builtin_curves
-first appeared in OpenSSL 0.9.8 and have been available since
-.Ox 4.5 .
-.Fn EC_curve_nid2nist ,
-and
-.Fn EC_curve_nist2nid
-first appeared in OpenSSL 1.1.0 and have been available since
-.Ox 5.8 .
-.Pp
-.Fn EC_GROUP_set_curve
-and
-.Fn EC_GROUP_get_curve
-first appeared in OpenSSL 1.1.1 and have been available since
-.Ox 7.0 .