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, 12 insertions, 9 deletions

diff --git a/src/lib/libcrypto/man/EC_KEY_new.3 b/src/lib/libcrypto/man/EC_KEY_new.3
index c24cb080ef..a2592a20ae 100644
--- a/src/lib/libcrypto/man/EC_KEY_new.3
+++ b/src/lib/libcrypto/man/EC_KEY_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EC_KEY_new.3,v 1.21 2025/03/08 16:38:13 tb Exp $
+.\" $OpenBSD: EC_KEY_new.3,v 1.22 2025/04/25 19:57:12 tb Exp $
 .\" full merge up to: OpenSSL 3aef36ff Jan 5 13:06:03 2016 -0500
 .\" partial merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
 .\"
@@ -49,7 +49,7 @@
 .\" 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_KEY_NEW 3
 .Os
 .Sh NAME
@@ -234,7 +234,7 @@ and supplying the
 .Fa nid
 of the associated curve.
 Refer to
-.Xr EC_GROUP_new 3
+.Xr EC_GROUP_new_by_curve_name 3
 for a description of curve names.
 This function simply wraps calls to
 .Fn EC_KEY_new
@@ -357,7 +357,7 @@ The format of the external representation of the public key written by
 such as whether it is stored in a compressed form or not,
 is described by the point_conversion_form.
 See
-.Xr EC_GROUP_copy 3
+.Xr EC_POINT_point2oct 3
 for a description of point_conversion_form.
 .Pp
 When reading a private key encoded without an associated public key,
@@ -378,7 +378,7 @@ and
 get and set the point_conversion_form for the
 .Fa key .
 For a description of point_conversion_form refer to
-.Xr EC_GROUP_copy 3 .
+.Xr EC_POINT_point2oct 3 .
 .Pp
 .Fn EC_KEY_set_flags
 sets the flags in the
@@ -407,7 +407,7 @@ sets the asn1_flag on the underlying
 .Vt EC_GROUP
 object (if set).
 Refer to
-.Xr EC_GROUP_copy 3
+.Xr EC_GROUP_get_curve_name 3
 for further information on the asn1_flag.
 .Pp
 .Fn EC_KEY_precompute_mult
@@ -488,11 +488,14 @@ returns the point_conversion_form for the
 .Vt EC_KEY .
 .Sh SEE ALSO
 .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_POINT_add 3 ,
-.Xr EC_POINT_new 3 ,
+.Xr EC_POINT_get_affine_coordinates 3 ,
+.Xr EC_POINT_point2oct 3 ,
 .Xr ECDH_compute_key 3 ,
 .Xr ECDSA_SIG_new 3 ,
 .Xr EVP_PKEY_set1_EC_KEY 3