From 22bab8566a4f25e3a1868f3850baf372236b2b2d Mon Sep 17 00:00:00 2001
From: tb <tb@openbsd.org>
Date: Fri, 26 Apr 2024 14:23:03 +0000
Subject: [PATCH] Document EC_curve_{nid2nist,nist2nid}()

---
 lib/libcrypto/man/EC_GROUP_new.3 | 61 +++++++++++++++++++++++++++++---
 1 file changed, 57 insertions(+), 4 deletions(-)

diff --git a/lib/libcrypto/man/EC_GROUP_new.3 b/lib/libcrypto/man/EC_GROUP_new.3
index 7a539eb92ac..d0e95c98589 100644
--- a/lib/libcrypto/man/EC_GROUP_new.3
+++ b/lib/libcrypto/man/EC_GROUP_new.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: EC_GROUP_new.3,v 1.15 2023/04/27 09:35:20 tb Exp $
+.\"	$OpenBSD: EC_GROUP_new.3,v 1.16 2024/04/26 14:23:03 tb Exp $
 .\"	OpenSSL 6328d367 Sat Jul 4 21:58:30 2020 +0200
 .\"
 .\" This file was written by Matt Caswell <matt@openssl.org>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: April 27 2023 $
+.Dd $Mdocdate: April 26 2024 $
 .Dt EC_GROUP_NEW 3
 .Os
 .Sh NAME
@@ -61,7 +61,9 @@
 .Nm EC_GROUP_get_curve ,
 .Nm EC_GROUP_set_curve_GFp ,
 .Nm EC_GROUP_get_curve_GFp ,
-.Nm EC_get_builtin_curves
+.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
@@ -126,6 +128,14 @@
 .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 over finite fields.
@@ -249,6 +259,30 @@ If
 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*
@@ -259,6 +293,19 @@ on error.
 .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 ,
@@ -286,11 +333,17 @@ and
 first appeared in OpenSSL 0.9.7 and have been available since
 .Ox 3.2 .
 .Pp
-.Fn EC_GROUP_new_by_curve_name ,
+.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
-- 
2.20.1