Split X509_NAME_hash(3) out of d2i_X509_NAME(3) and document

X509_issuer_name_hash(3), X509_subject_name_hash(3), and the _old variants.

Even though this is only tangentially related to decoding and encoding,
including a single function in d2i_X509_NAME(3) was probably OK,
but let's not bog down that page with six functions that are likely
to become obsolete at some point - even though right now, they are
still being used both internally and by external software.

4 files changed, 102 insertions, 25 deletions

diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 23a46ed318..c7375752bb 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.182 2021/07/19 13:16:43 schwarze Exp $
+# $OpenBSD: Makefile,v 1.183 2021/07/20 17:31:32 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -287,6 +287,7 @@ MAN=	\
         X509_NAME_ENTRY_get_object.3 \
         X509_NAME_add_entry_by_txt.3 \
         X509_NAME_get_index_by_NID.3 \
+        X509_NAME_hash.3 \
         X509_NAME_new.3 \
         X509_NAME_print_ex.3 \
         X509_OBJECT_get0_X509.3 \
diff --git a/src/lib/libcrypto/man/X509_NAME_hash.3 b/src/lib/libcrypto/man/X509_NAME_hash.3
new file mode 100644
index 0000000000..061de5c06c
--- /dev/null
+++ b/src/lib/libcrypto/man/X509_NAME_hash.3
@@ -0,0 +1,94 @@
+.\" $OpenBSD: X509_NAME_hash.3,v 1.1 2021/07/20 17:31:32 schwarze Exp $
+.\"
+.\" Copyright (c) 2017, 2021 Ingo Schwarze <schwarze@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: July 20 2021 $
+.Dt X509_NAME_HASH 3
+.Os
+.Sh NAME
+.Nm X509_NAME_hash ,
+.Nm X509_issuer_name_hash ,
+.Nm X509_subject_name_hash ,
+.Nm X509_NAME_hash_old ,
+.Nm X509_issuer_name_hash_old ,
+.Nm X509_subject_name_hash_old
+.\" In the following line, "X.501" and "Name" are not typos.
+.\" The "Name" type is defined in X.501, not in X.509.
+.\" The type is called "Name" with capital "N", not "name".
+.Nd calculate SHA-1 or MD5 hashes of X.501 Name objects
+.Sh SYNOPSIS
+.In openssl/x509.h
+.Ft unsigned long
+.Fn X509_NAME_hash "X509_NAME *name"
+.Ft unsigned long
+.Fn X509_issuer_name_hash "X509 *x"
+.Ft unsigned long
+.Fn X509_subject_name_hash "X509 *x"
+.Ft unsigned long
+.Fn X509_NAME_hash_old "X509_NAME *name"
+.Ft unsigned long
+.Fn X509_issuer_name_hash_old "X509 *x"
+.Ft unsigned long
+.Fn X509_subject_name_hash_old "X509 *x"
+.Sh DESCRIPTION
+.Fn X509_NAME_hash
+calculates an
+.Xr SHA1 3
+hash of the DER-encoded form of
+.Fa name .
+It is for example used by
+.Xr X509_LOOKUP_hash_dir 3
+to locate certificate files in the file system.
+.Pp
+.Fn X509_issuer_name_hash
+and
+.Fn X509_subject_name_hash
+are wrappers to calculate this hash of the issuer or subject name of
+.Fa x ,
+respectively.
+.Pp
+.Fn X509_NAME_hash_old ,
+.Fn X509_issuer_name_hash_old ,
+and
+.Fn X509_subject_name_hash_old
+are variants that use MD5 instead of SHA-1.
+.Sh RETURN VALUES
+These functions return the hash value or 0 if an error occurs.
+.Sh SEE ALSO
+.Xr i2d_X509_NAME 3 ,
+.Xr X509_get_subject_name 3 ,
+.Xr X509_NAME_digest 3 ,
+.Xr X509_NAME_new 3
+.Sh HISTORY
+.Fn X509_subject_name_hash
+first appeared in SSLeay 0.4.0,
+.Fn X509_issuer_name_hash
+in SSLeay 0.5.1, and
+.Fn X509_NAME_hash
+in SSLeay 0.8.0.
+They were switched to hashing the DER representation of the name
+rather than an ASCII rendering in SSLeay 0.9.0 and have all been
+available since
+.Ox 2.4 .
+.Pp
+They were switched to using SHA1 instead of MD5 in OpenSSL 1.0.0 and in
+.Ox 4.9 .
+.Pp
+.Fn X509_NAME_hash_old ,
+.Fn X509_issuer_name_hash_old ,
+and
+.Fn X509_subject_name_hash_old
+first appeared in OpenSSL 1.0.0 and have been available since
+.Ox 4.9 .
diff --git a/src/lib/libcrypto/man/X509_NAME_new.3 b/src/lib/libcrypto/man/X509_NAME_new.3
index 5895dd5a10..3a4786a9ae 100644
--- a/src/lib/libcrypto/man/X509_NAME_new.3
+++ b/src/lib/libcrypto/man/X509_NAME_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_NAME_new.3,v 1.8 2019/08/20 13:27:19 schwarze Exp $
+.\" $OpenBSD: X509_NAME_new.3,v 1.9 2021/07/20 17:31:32 schwarze Exp $
 .\"
 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: August 20 2019 $
+.Dd $Mdocdate: July 20 2021 $
 .Dt X509_NAME_NEW 3
 .Os
 .Sh NAME
@@ -85,6 +85,7 @@ if an error occurred.
 .Xr X509_NAME_digest 3 ,
 .Xr X509_NAME_ENTRY_new 3 ,
 .Xr X509_NAME_get_index_by_NID 3 ,
+.Xr X509_NAME_hash 3 ,
 .Xr X509_NAME_print_ex 3 ,
 .Xr X509_new 3
 .Sh STANDARDS
diff --git a/src/lib/libcrypto/man/d2i_X509_NAME.3 b/src/lib/libcrypto/man/d2i_X509_NAME.3
index c2d4b7d1cd..6e3e4a7f69 100644
--- a/src/lib/libcrypto/man/d2i_X509_NAME.3
+++ b/src/lib/libcrypto/man/d2i_X509_NAME.3
@@ -1,9 +1,9 @@
-.\" $OpenBSD: d2i_X509_NAME.3,v 1.15 2021/07/03 17:04:51 schwarze Exp $
+.\" $OpenBSD: d2i_X509_NAME.3,v 1.16 2021/07/20 17:31:32 schwarze Exp $
 .\" checked up to:
 .\" OpenSSL crypto/d2i_X509_NAME 4692340e Jun 7 15:49:08 2016 -0400 and
 .\" OpenSSL man3/X509_NAME_get0_der 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
-.\" Copyright (c) 2016, 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2016, 2018 Ingo Schwarze <schwarze@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
@@ -17,7 +17,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 3 2021 $
+.Dd $Mdocdate: July 20 2021 $
 .Dt D2I_X509_NAME 3
 .Os
 .Sh NAME
@@ -26,7 +26,6 @@
 .Nm X509_NAME_get0_der ,
 .Nm X509_NAME_dup ,
 .Nm X509_NAME_set ,
-.Nm X509_NAME_hash ,
 .Nm d2i_X509_NAME_ENTRY ,
 .Nm i2d_X509_NAME_ENTRY ,
 .Nm X509_NAME_ENTRY_dup
@@ -62,10 +61,6 @@
 .Fa "X509_NAME **val_out"
 .Fa "X509_NAME *val_in"
 .Fc
-.Ft unsigned long
-.Fo X509_NAME_hash
-.Fa "X509_NAME *val_in"
-.Fc
 .Ft X509_NAME_ENTRY *
 .Fo d2i_X509_NAME_ENTRY
 .Fa "X509_NAME_ENTRY **val_out"
@@ -142,15 +137,6 @@ remains valid and may or may not be the same pointer as
 .Pf * Fa val_out
 after the call.
 .Pp
-.Fn X509_NAME_hash
-calculates a
-.Xr SHA1 3
-hash of the DER-encoded form of the name
-.Pf * Fa val_in .
-It is for example used by
-.Xr X509_LOOKUP_hash_dir 3
-to locate certificate files in the file system.
-.Pp
 .Fn d2i_X509_NAME_ENTRY
 and
 .Fn i2d_X509_NAME_ENTRY
@@ -180,9 +166,6 @@ and
 .Fn X509_NAME_get0_der
 return 1 on success or 0 if an error occurs.
 .Pp
-.Fn X509_NAME_hash
-returns the hash value or 0 if an error occurs.
-.Pp
 .Fn d2i_X509_NAME_ENTRY
 and
 .Fn X509_NAME_ENTRY_dup
@@ -221,8 +204,6 @@ and
 .Fn X509_NAME_ENTRY_dup
 first appeared in SSLeay 0.5.1.
 .Fn X509_NAME_set
-and
-.Fn X509_NAME_hash
 first appeared in SSLeay 0.8.0.
 These functions have been available since
 .Ox 2.4 .