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, 129 insertions, 377 deletions

diff --git a/src/lib/libcrypto/man/EC_POINT_new.3 b/src/lib/libcrypto/man/EC_POINT_new.3
index db6280fce7..cfc988f294 100644
--- a/src/lib/libcrypto/man/EC_POINT_new.3
+++ b/src/lib/libcrypto/man/EC_POINT_new.3
@@ -1,54 +1,20 @@
-.\" $OpenBSD: EC_POINT_new.3,v 1.17 2025/03/08 17:04:07 tb Exp $
-.\" full merge up to: OpenSSL 50db8163 Jul 30 16:56:41 2018 +0100
+.\" $OpenBSD: EC_POINT_new.3,v 1.18 2025/04/25 19:57:12 tb Exp $
 .\"
-.\" This file was written by Matt Caswell <matt@openssl.org>.
-.\" Copyright (c) 2013, 2016 The OpenSSL Project.  All rights reserved.
+.\" Copyright (c) 2025 Theo Buehler <tb@openbsd.org>
 .\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
 .\"
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" 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 $
+.Dd $Mdocdate: April 25 2025 $
 .Dt EC_POINT_NEW 3
 .Os
 .Sh NAME
@@ -56,163 +22,56 @@
 .Nm EC_POINT_free ,
 .Nm EC_POINT_clear_free ,
 .Nm EC_POINT_copy ,
-.Nm EC_POINT_dup ,
-.Nm EC_POINT_set_to_infinity ,
-.Nm EC_POINT_set_affine_coordinates ,
-.Nm EC_POINT_set_affine_coordinates_GFp ,
-.Nm EC_POINT_get_affine_coordinates ,
-.Nm EC_POINT_get_affine_coordinates_GFp ,
-.Nm EC_POINT_set_compressed_coordinates ,
-.Nm EC_POINT_set_compressed_coordinates_GFp ,
-.Nm EC_POINT_point2oct ,
-.Nm EC_POINT_oct2point ,
-.Nm EC_POINT_point2bn ,
-.Nm EC_POINT_bn2point ,
-.Nm EC_POINT_point2hex ,
-.Nm EC_POINT_hex2point
-.Nd create, destroy, and manipulate EC_POINT objects
+.Nm EC_POINT_dup
+.Nd allocate, free and copy elliptic curve points
 .Sh SYNOPSIS
 .In openssl/ec.h
-.In openssl/bn.h
-.Ft EC_POINT *
+.Pp
+.Ft "EC_POINT *"
 .Fo EC_POINT_new
 .Fa "const EC_GROUP *group"
 .Fc
-.Ft void
+.Ft "void"
 .Fo EC_POINT_free
 .Fa "EC_POINT *point"
 .Fc
-.Ft void
+.Ft "void"
 .Fo EC_POINT_clear_free
 .Fa "EC_POINT *point"
 .Fc
-.Ft int
+.Ft "int"
 .Fo EC_POINT_copy
 .Fa "EC_POINT *dst"
 .Fa "const EC_POINT *src"
 .Fc
-.Ft EC_POINT *
+.Ft "EC_POINT *"
 .Fo EC_POINT_dup
-.Fa "const EC_POINT *src"
-.Fa "const EC_GROUP *group"
-.Fc
-.Ft int
-.Fo EC_POINT_set_to_infinity
-.Fa "const EC_GROUP *group"
-.Fa "EC_POINT *point"
-.Fc
-.Ft int
-.Fo EC_POINT_set_affine_coordinates
-.Fa "const EC_GROUP *group"
-.Fa "EC_POINT *p"
-.Fa "const BIGNUM *x"
-.Fa "const BIGNUM *y"
-.Fa "BN_CTX *ctx"
-.Fc
-.Ft int
-.Fo EC_POINT_set_affine_coordinates_GFp
-.Fa "const EC_GROUP *group"
-.Fa "EC_POINT *p"
-.Fa "const BIGNUM *x"
-.Fa "const BIGNUM *y"
-.Fa "BN_CTX *ctx"
-.Fc
-.Ft int
-.Fo EC_POINT_get_affine_coordinates
-.Fa "const EC_GROUP *group"
-.Fa "const EC_POINT *p"
-.Fa "BIGNUM *x"
-.Fa "BIGNUM *y"
-.Fa "BN_CTX *ctx"
-.Fc
-.Ft int
-.Fo EC_POINT_get_affine_coordinates_GFp
-.Fa "const EC_GROUP *group"
-.Fa "const EC_POINT *p"
-.Fa "BIGNUM *x"
-.Fa "BIGNUM *y"
-.Fa "BN_CTX *ctx"
-.Fc
-.Ft int
-.Fo EC_POINT_set_compressed_coordinates
-.Fa "const EC_GROUP *group"
-.Fa "EC_POINT *p"
-.Fa "const BIGNUM *x"
-.Fa "int y_bit"
-.Fa "BN_CTX *ctx"
-.Fc
-.Ft int
-.Fo EC_POINT_set_compressed_coordinates_GFp
-.Fa "const EC_GROUP *group"
-.Fa "EC_POINT *p"
-.Fa "const BIGNUM *x"
-.Fa "int y_bit"
-.Fa "BN_CTX *ctx"
-.Fc
-.Ft size_t
-.Fo EC_POINT_point2oct
+.Fa "const EC_POINT *point"
 .Fa "const EC_GROUP *group"
-.Fa "const EC_POINT *p"
-.Fa "point_conversion_form_t form"
-.Fa "unsigned char *buf"
-.Fa "size_t len"
-.Fa "BN_CTX *ctx"
-.Fc
-.Ft int
-.Fo EC_POINT_oct2point
-.Fa "const EC_GROUP *group"
-.Fa "EC_POINT *p"
-.Fa "const unsigned char *buf"
-.Fa "size_t len"
-.Fa "BN_CTX *ctx"
-.Fc
-.Ft BIGNUM *
-.Fo EC_POINT_point2bn
-.Fa "const EC_GROUP *"
-.Fa "const EC_POINT *"
-.Fa "point_conversion_form_t form"
-.Fa "BIGNUM *"
-.Fa "BN_CTX *"
-.Fc
-.Ft EC_POINT *
-.Fo EC_POINT_bn2point
-.Fa "const EC_GROUP *"
-.Fa "const BIGNUM *"
-.Fa "EC_POINT *"
-.Fa "BN_CTX *"
-.Fc
-.Ft char *
-.Fo EC_POINT_point2hex
-.Fa "const EC_GROUP *"
-.Fa "const EC_POINT *"
-.Fa "point_conversion_form_t form"
-.Fa "BN_CTX *"
-.Fc
-.Ft EC_POINT *
-.Fo EC_POINT_hex2point
-.Fa "const EC_GROUP *"
-.Fa "const char *"
-.Fa "EC_POINT *"
-.Fa "BN_CTX *"
 .Fc
 .Sh DESCRIPTION
 An
 .Vt EC_POINT
-represents a point on a curve.
-A curve is represented by an
-.Vt EC_GROUP
-object created by the functions described in
-.Xr EC_GROUP_new 3 .
+object holds a point on the elliptic curve represented by an
+.Vt EC_GROUP .
+The details of the internal representation depend on the group
+and should never be an application's concern since the EC library
+has API to set a point's coordinates,
+.Xr EC_POINT_set_affine_coordinates 3 .
 .Pp
-A new point is constructed by calling the function
 .Fn EC_POINT_new
-and providing the
-.Fa group
-object that the point relates to.
+allocates and initializes an
+.Vt EC_POINT
+object to be used with the
+.Fa group .
+Before explicitly setting its coordinates, the returned
+.Vt EC_POINT
+is invalid.
 .Pp
 .Fn EC_POINT_free
-frees the memory associated with the
-.Vt EC_POINT .
+frees
+.Fa point
+and all memory associated with it.
 If
 .Fa point
 is a
@@ -220,236 +79,129 @@ is a
 pointer, no action occurs.
 .Pp
 .Fn EC_POINT_clear_free
-destroys any sensitive data held within the
-.Vt EC_POINT
-and then frees its memory.
-If
+is intended to destroy sensitive data held in
 .Fa point
-is a
-.Dv NULL
-pointer, no action occurs.
+in addition to freeing all memory associated with it.
+Since elliptic curve points usually hold public data, this
+is rarely needed.
+In LibreSSL,
+.Fn EC_POINT_free
+and
+.Fn EC_POINT_clear_free
+behave identically.
 .Pp
 .Fn EC_POINT_copy
-copies the point
+copies the internal representation of
 .Fa src
 into
 .Fa dst .
-Both
+If
 .Fa src
 and
 .Fa dst
-must use the same
-.Vt EC_METHOD .
-.Pp
-.Fn EC_POINT_dup
-creates a new
-.Vt EC_POINT
-object and copies the content from
+are identical, no action occurs.
+Both
 .Fa src
-to the newly created
-.Vt EC_POINT
-object.
-.Pp
-A valid point on a curve is the special point at infinity.
-A point is set to be at infinity by calling
-.Fn EC_POINT_set_to_infinity .
-.Pp
-The affine coordinates for a point describe a point in terms of its
-.Fa x
-and
-.Fa y
-position.
-The function
-.Fn EC_POINT_set_affine_coordinates
-sets the
-.Fa x
-and
-.Fa y
-coordinates for the point
-.Fa p
-defined over the curve given in
-.Fa group .
-The function
-.Fn EC_POINT_get_affine_coordinates
-sets
-.Fa x
-and
-.Fa y ,
-either of which may be
-.Dv NULL ,
-to the corresponding coordinates of
-.Fa p .
-.Pp
-The functions
-.Fn EC_POINT_set_affine_coordinates_GFp
-is a deprecated synonym for
-.Fn EC_POINT_set_affine_coordinates
-and the function
-.Fn EC_POINT_get_affine_coordinates_GFp
-is a deprecated synonym for
-.Fn EC_POINT_get_affine_coordinates .
-.Pp
-Points can also be described in terms of their compressed coordinates.
-For a point
-.Pq Fa x , y ,
-for any given value for
-.Fa x
-such that the point is on the curve, there will only ever be two
-possible values for
-.Fa y .
-Therefore, a point can be set using the
-.Fn EC_POINT_set_compressed_coordinates
-function where
-.Fa x
-is the x coordinate and
-.Fa y_bit
-is a value 0 or 1 to identify which of the two possible values for y
-should be used.
-.Pp
-The functions
-.Fn EC_POINT_set_compressed_coordinates_GFp
-is a deprecated synonym for
-.Fn EC_POINT_set_compressed_coordinates .
-.Pp
-In addition
-.Vt EC_POINT Ns s
-can be converted to and from various external representations.
-Supported representations are octet strings,
-.Vt BIGNUM Ns s ,
-and hexadecimal.
-The format of the external representation is described by the
-point_conversion_form.
-See
-.Xr EC_GROUP_copy 3
-for a description of point_conversion_form.
-Octet strings are stored in a buffer along with an associated buffer
-length.
-A point held in a
-.Vt BIGNUM
-is calculated by converting the point to an octet string and then
-converting that octet string into a
-.Vt BIGNUM
-integer.
-Points in hexadecimal format are stored in a NUL terminated character
-string where each character is one of the printable values 0-9 or A-F
-(or a-f).
-.Pp
-The functions
-.Fn EC_POINT_point2oct ,
-.Fn EC_POINT_oct2point ,
-.Fn EC_POINT_point2bn ,
-.Fn EC_POINT_bn2point ,
-.Fn EC_POINT_point2hex ,
 and
-.Fn EC_POINT_hex2point
-convert from and to
-.Vt EC_POINT Ns s
-for the formats octet string,
-.Vt BIGNUM ,
-and hexadecimal, respectively.
-.Pp
-The function
-.Fn EC_POINT_point2oct
-must be supplied with a
-.Fa buf
-long enough to store the octet string.
-The return value provides the number of octets stored.
-Calling the function with a
-.Dv NULL
-.Fa buf
-will not perform the conversion but will still return the required
-buffer length.
+.Fa dst
+should be the result of
+.Fn EC_POINT_new
+with the same
+.Fa group
+argument, although
+.Fn EC_POINT_copy
+cannot check that.
 .Pp
-The function
-.Fn EC_POINT_point2hex
-will allocate sufficient memory to store the hexadecimal string.
-It is the caller's responsibility to free this memory with a subsequent
-call to
-.Xr free 3 .
+.Fn EC_POINT_dup
+creates a deep copy of
+.Fa point
+by combining
+.Fn EC_POINT_new
+with
+.Fn EC_GROUP_copy .
 .Sh RETURN VALUES
 .Fn EC_POINT_new
-and
-.Fn EC_POINT_dup
-return the newly allocated
+returns a newly allocated
 .Vt EC_POINT
 or
 .Dv NULL
-on error.
+on memory allocation failure.
 .Pp
-The following functions return 1 on success or 0 on error:
-.Fn EC_POINT_copy ,
-.Fn EC_POINT_set_to_infinity ,
-.Fn EC_POINT_set_affine_coordinates ,
-.Fn EC_POINT_set_affine_coordinates_GFp ,
-.Fn EC_POINT_get_affine_coordinates ,
-.Fn EC_POINT_get_affine_coordinates_GFp ,
-.Fn EC_POINT_set_compressed_coordinates ,
-.Fn EC_POINT_set_compressed_coordinates_GFp ,
-and
-.Fn EC_POINT_oct2point .
-.Pp
-.Fn EC_POINT_point2oct
-returns the length of the required buffer, or 0 on error.
-.Pp
-.Fn EC_POINT_point2bn
-returns the pointer to the
-.Vt BIGNUM
-supplied or
-.Dv NULL
-on error.
-.Pp
-.Fn EC_POINT_bn2point
-returns the pointer to the
-.Vt EC_POINT
-supplied or
-.Dv NULL
-on error.
-.Pp
-.Fn EC_POINT_point2hex
-returns a pointer to the hex string or
-.Dv NULL
-on error.
+.Fn EC_POINT_copy
+returns 1 on success or 0 on error.
+Error conditions include memory allocation failure and that
+.Fa dst
+is incompatible with the group on which
+.Fa src
+is defined.
 .Pp
-.Fn EC_POINT_hex2point
-returns the pointer to the
+.Fn EC_POINT_dup
+returns a newly allocated
 .Vt EC_POINT
-supplied or
+or
 .Dv NULL
-on error.
+on failure.
+Error conditions include memory allocation failure or that
+.Fa group
+is incompatible with
+.Fa src .
 .Sh SEE ALSO
+.Xr BN_CTX_new 3 ,
+.Xr BN_is_zero 3 ,
+.Xr crypto 3 ,
 .Xr d2i_ECPKParameters 3 ,
-.Xr EC_GROUP_copy 3 ,
-.Xr EC_GROUP_new 3 ,
+.Xr EC_GROUP_check 3 ,
+.Xr EC_GROUP_get_curve_name 3 ,
+.Xr EC_GROUP_new_by_curve_name 3 ,
+.Xr EC_GROUP_new_curve_GFp 3 ,
+.Xr EC_KEY_METHOD_new 3 ,
 .Xr EC_KEY_new 3 ,
 .Xr EC_POINT_add 3 ,
-.Xr ECDH_compute_key 3
+.Xr EC_POINT_get_affine_coordinates 3 ,
+.Xr EC_POINT_point2oct 3 ,
+.Xr ECDH_compute_key 3 ,
+.Xr ECDSA_SIG_new 3
 .Sh HISTORY
 .Fn EC_POINT_new ,
 .Fn EC_POINT_free ,
 .Fn EC_POINT_clear_free ,
-.Fn EC_POINT_copy ,
-.Fn EC_POINT_set_to_infinity ,
-.Fn EC_POINT_set_affine_coordinates_GFp ,
-.Fn EC_POINT_get_affine_coordinates_GFp ,
-.Fn EC_POINT_set_compressed_coordinates_GFp ,
-.Fn EC_POINT_point2oct ,
 and
-.Fn EC_POINT_oct2point
+.Fn EC_POINT_copy
 first appeared in OpenSSL 0.9.7 and have been available since
 .Ox 3.2 .
 .Pp
-.Fn EC_POINT_dup ,
-.Fn EC_POINT_point2bn ,
-.Fn EC_POINT_bn2point ,
-.Fn EC_POINT_point2hex ,
-and
-.Fn EC_POINT_hex2point
-first appeared in OpenSSL 0.9.8 and have been available since
+.Fn EC_POINT_dup
+first appeared in OpenSSL 0.9.8 and has been available since
 .Ox 4.5 .
-.Pp
-.Fn EC_POINT_set_affine_coordinates ,
-.Fn EC_POINT_get_affine_coordinates ,
+.Sh BUGS
+A fundamental flaw in the OpenSSL API toolkit is that
+.Fn *_new
+functions usually create invalid objects that are tricky to
+turn into valid objects.
+A fundamental flaw in the EC library is that
+.Vt EC_POINT
+objects do not hold a reference to the group they live on
+despite the fact that
+.Fn EC_POINT_new
+has a
+.Fa group
+argument.
+This is difficult to fix because
+.Vt EC_GROUP
+objects are not reference counted and
+because of const qualifiers in the API.
+This is the root cause for various contortions in the EC library
+and API.
+This has security implications because not
+only does the library not know whether an
+.Fa EC_POINT
+object represents a valid point,
+even if it did know that it would not know on what curve.
+.Pp
+The signature of
+.Fn EC_GROUP_dup
+is bizarre and the order of
+.Fa point
 and
-.Fn EC_POINT_set_compressed_coordinates
-first appeared in OpenSSL 1.1.1 and have been available since
-.Ox 7.0 .
+.Fa group
+is inconsistent with the rest of the EC API.