From 0c4652a22d8f07127593a31a97458e4615ee7c14 Mon Sep 17 00:00:00 2001
From: schwarze <schwarze@openbsd.org>
Date: Tue, 5 Sep 2023 14:54:21 +0000
Subject: [PATCH] document EVP_CIPHER_name(3)

---
 lib/libcrypto/man/EVP_CIPHER_nid.3 | 34 ++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/lib/libcrypto/man/EVP_CIPHER_nid.3 b/lib/libcrypto/man/EVP_CIPHER_nid.3
index 1c0683980bd..1feff4f34e9 100644
--- a/lib/libcrypto/man/EVP_CIPHER_nid.3
+++ b/lib/libcrypto/man/EVP_CIPHER_nid.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_CIPHER_nid.3,v 1.2 2023/09/01 17:28:21 schwarze Exp $
+.\" $OpenBSD: EVP_CIPHER_nid.3,v 1.3 2023/09/05 14:54:21 schwarze Exp $
 .\" full merge up to: OpenSSL man3/EVP_EncryptInit.pod
 .\"   0874d7f2 Oct 11 13:13:47 2022 +0100
 .\"
@@ -66,12 +66,13 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: September 1 2023 $
+.Dd $Mdocdate: September 5 2023 $
 .Dt EVP_CIPHER_NID 3
 .Os
 .Sh NAME
 .Nm EVP_CIPHER_nid ,
 .Nm EVP_CIPHER_CTX_nid ,
+.Nm EVP_CIPHER_name ,
 .Nm EVP_CIPHER_type ,
 .Nm EVP_CIPHER_CTX_type ,
 .Nm EVP_CIPHER_block_size ,
@@ -91,6 +92,10 @@
 .Fo EVP_CIPHER_CTX_nid
 .Fa "const EVP_CIPHER_CTX *ctx"
 .Fc
+.Ft const char *
+.Fo EVP_CIPHER_name
+.Fa "const EVP_CIPHER *cipher"
+.Fc
 .Ft int
 .Fo EVP_CIPHER_type
 .Fa "const EVP_CIPHER *ctx"
@@ -137,6 +142,12 @@ returns the NID of the cipher that
 .Fa ctx
 is configured to use.
 .Pp
+.Fn EVP_CIPHER_name
+converts the NID of the
+.Fa cipher
+to its short name with
+.Xr OBJ_nid2sn 3 .
+.Pp
 .Fn EVP_CIPHER_type
 returns the NID associated with the ASN.1 OBJECT IDENTIFIER of the
 .Fa cipher ,
@@ -196,12 +207,27 @@ and the return value of
 returns the cipher mode of the cipher that
 .Fa ctx
 is configured to use.
+.Pp
+.Fn EVP_CIPHER_name ,
+.Fn EVP_CIPHER_CTX_type ,
+.Fn EVP_CIPHER_mode ,
+and
+.Fn EVP_CIPHER_CTX_mode
+are implemented as macros.
 .Sh RETURN VALUES
 .Fn EVP_CIPHER_nid
 and
 .Fn EVP_CIPHER_CTX_nid
 return an NID.
 .Pp
+.Fn EVP_CIPHER_name
+returns a pointer to a string that is owned by an internal library object or
+.Dv NULL
+if the NID is neither built into the library nor added to the global
+object table by one of the functions documented in the manual page
+.Xr OBJ_create 3 ,
+of if the object does not contain a short name.
+.Pp
 .Fn EVP_CIPHER_type
 and
 .Fn EVP_CIPHER_CTX_type
@@ -264,6 +290,10 @@ and
 .Fn EVP_CIPHER_CTX_mode
 first appeared in OpenSSL 0.9.6 and have been available since
 .Ox 2.9 .
+.Pp
+.Fn EVP_CIPHER_name
+first appeared in OpenSSL 0.9.7 and has been available since
+.Ox 3.2 .
 .Sh CAVEATS
 The behaviour of the functions taking an
 .Vt EVP_CIPHER_CTX
-- 
2.20.1