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, 157 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/EC_GROUP_check.3 b/src/lib/libcrypto/man/EC_GROUP_check.3
new file mode 100644
index 0000000000..e000be212b
--- /dev/null
+++ b/src/lib/libcrypto/man/EC_GROUP_check.3
@@ -0,0 +1,157 @@
+.\" $OpenBSD: EC_GROUP_check.3,v 1.1 2025/04/25 19:57:12 tb Exp $
+.\"
+.\" Copyright (c) 2025 Theo Buehler <tb@openbsd.org>
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.Dd $Mdocdate: April 25 2025 $
+.Dt EC_GROUP_CHECK 3
+.Os
+.Sh NAME
+.Nm EC_GROUP_check_discriminant ,
+.Nm EC_GROUP_check
+.Nd partially check validity of
+.Vt EC_GROUP
+objects
+.Sh SYNOPSIS
+.In openssl/bn.h
+.In openssl/ec.h
+.Pp
+Deprecated:
+.Pp
+.Ft "int"
+.Fo EC_GROUP_check_discriminant
+.Fa "const EC_GROUP *group"
+.Fa "BN_CTX *ctx"
+.Fc
+.Ft "int"
+.Fo EC_GROUP_check
+.Fa "const EC_GROUP *group"
+.Fa "BN_CTX *ctx"
+.Fc
+.Sh DESCRIPTION
+These functions are deprecated.
+Only standardized curves built into the library should be used, see
+.Xr EC_GROUP_new_by_curve_name 3 .
+For builtin curves far more thorough checks than the minimal checks
+performed by these functions have been performed.
+.Pp
+These functions have an optional
+.Fa ctx
+argument which is used to avoid the cost of repeated allocation of
+auxiliary
+.Vt BIGNUM
+objects.
+.Pp
+.Fn EC_GROUP_check_discriminant
+can be called after
+.Xr EC_GROUP_new_curve_GFp 3
+to verify that
+.Fa group Ns 's
+parameters have non-zero discriminant 4a^3 + 27b^2 modulo p.
+Assuming that
+.Fa p
+is a prime number larger than three
+this implies that the Weierstrass equation defines an elliptic curve.
+.Pp
+.Fn EC_GROUP_check
+partially verifies that
+.Fa group
+represents an an elliptic curve and that
+.Fa generator
+is a point on the curve whose order divides
+.Fa order .
+It checks with
+.Fn EC_GROUP_check_discriminant
+that the discriminant is non-zero
+and then verifies that that
+.Fa order
+is non-zero and that the product
+.Fa generator No * Fa order
+is the point at infinity.
+This implies that
+.Fa order
+is an integer multiple of the
+.Fa generator Ns 's
+.Fa order .
+The verification that
+.Fa p
+is a prime
+and that
+.Fa order
+is the
+.Fa generator Ns 's
+order are skipped because they are too expensive.
+.Sh RETURN VALUES
+.Fn EC_GROUP_check_discriminant
+returns 1 on success and 0 on failure.
+Failure modes include that the discriminant is zero modulo
+.Fa p
+and memory allocation failure.
+.Pp
+.Fn EC_GROUP_check
+returns 1 on success and 0 on failure.
+.Sh ERRORS
+Diagnostics for
+.Fn EC_GROUP_check
+that can be retrieved with
+.Xr ERR_get_error 3 ,
+.Xr ERR_GET_REASON 3 ,
+and
+.Xr ERR_reason_error_string 3
+include:
+.Bl -tag -width Ds
+.It Dv EC_R_DISCRIMINANT_IS_ZERO Qq "discriminant is zero"
+.Fn EC_GROUP_check_discriminant
+failed because the discriminant is zero or for some other reason.
+.It Dv EC_R_UNDEFINED_GENERATOR Qq "undefined generator"
+no generator is set on
+.Fa group ,
+for example because a call to
+.Xr EC_GROUP_set_generator 3
+is missing.
+.It Dv EC_R_POINT_IS_NOT_ON_CURVE Qq "point is not on curve"
+a generator is set, but it is not a point on the curve represented by
+.Fa group .
+.It Dv EC_R_UNDEFINED_ORDER Qq "undefined order"
+the
+.Fa order
+set on
+.Fa group
+is zero.
+.It Dv EC_R_INVALID_GROUP_ORDER Qq "invalid group order"
+.Fa generator No * Fa order
+is not the point at infinity.
+.El
+.Sh SEE ALSO
+.Xr BN_CTX_new 3 ,
+.Xr BN_is_zero 3 ,
+.Xr crypto 3 ,
+.Xr d2i_ECPKParameters 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 EC_POINT_get_affine_coordinates 3 ,
+.Xr EC_POINT_new 3 ,
+.Xr EC_POINT_point2oct 3 ,
+.Xr ECDH_compute_key 3 ,
+.Xr ECDSA_SIG_new 3
+.Sh HISTORY
+.Fn EC_GROUP_check
+and
+.Fn EC_GROUP_check_discriminant
+first appeared in OpenSSL 0.9.8 and have been available since
+.Ox 4.5 .