Split a new page X509_load_cert_file(3) with three functions

out of X509_LOOKUP_hash_dir(3) because both groups of functions
differ substantially in purpose and structure.

Rewrite the complete text of X509_load_cert_file(3) from scratch
for correctness and clarity.

This fixes several documentation errors:
1. The names of the constants were wrong, lacking the "X509_" prefix.
2. None of these functions support X509_FILETYPE_DEFAULT,
neither in OpenSSL nor in LibreSSL.
3. The memory cache does not contain X509_STORE objects;
instead, the X509_STORE object *is* the memory cache.

7 files changed, 157 insertions, 112 deletions

diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 53d20760eb6..6e8753b3791 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.209 2021/11/07 15:29:01 schwarze Exp $
+# $OpenBSD: Makefile,v 1.210 2021/11/09 16:23:04 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -348,6 +348,7 @@ MAN=	\
 	X509_get_subject_name.3 \
 	X509_get_version.3 \
 	X509_keyid_set1.3 \
+	X509_load_cert_file.3 \
 	X509_new.3 \
 	X509_ocspid_print.3 \
 	X509_policy_check.3 \
diff --git a/lib/libcrypto/man/X509_LOOKUP_hash_dir.3 b/lib/libcrypto/man/X509_LOOKUP_hash_dir.3
index 14e49f3a779..b1f6a175718 100644
--- a/lib/libcrypto/man/X509_LOOKUP_hash_dir.3
+++ b/lib/libcrypto/man/X509_LOOKUP_hash_dir.3
@@ -1,5 +1,6 @@
-.\" $OpenBSD: X509_LOOKUP_hash_dir.3,v 1.10 2021/07/31 14:54:33 schwarze Exp $
+.\" $OpenBSD: X509_LOOKUP_hash_dir.3,v 1.11 2021/11/09 16:23:04 schwarze Exp $
 .\" full merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
+.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
@@ -20,7 +21,7 @@
 .\"
 .\" The original file was written by Victor B. Wagner <vitus@cryptocom.ru>
 .\" and Claus Assmann.
-.\" Copyright (c) 2015, 2016, 2017 The OpenSSL Project.  All rights reserved.
+.\" Copyright (c) 2015, 2016 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -66,16 +67,13 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 31 2021 $
+.Dd $Mdocdate: November 9 2021 $
 .Dt X509_LOOKUP_HASH_DIR 3
 .Os
 .Sh NAME
 .Nm X509_LOOKUP_hash_dir ,
 .Nm X509_LOOKUP_file ,
-.Nm X509_LOOKUP_mem ,
-.Nm X509_load_cert_file ,
-.Nm X509_load_crl_file ,
-.Nm X509_load_cert_crl_file
+.Nm X509_LOOKUP_mem
 .Nd default certificate lookup methods
 .Sh SYNOPSIS
 .In openssl/x509_vfy.h
@@ -85,24 +83,6 @@
 .Fn X509_LOOKUP_file void
 .Ft X509_LOOKUP_METHOD *
 .Fn X509_LOOKUP_mem void
-.Ft int
-.Fo X509_load_cert_file
-.Fa "X509_LOOKUP *ctx"
-.Fa "const char *file"
-.Fa "int type"
-.Fc
-.Ft int
-.Fo X509_load_crl_file
-.Fa "X509_LOOKUP *ctx"
-.Fa "const char *file"
-.Fa "int type"
-.Fc
-.Ft int
-.Fo X509_load_cert_crl_file
-.Fa "X509_LOOKUP *ctx"
-.Fa "const char *file"
-.Fa "int type"
-.Fc
 .Sh DESCRIPTION
 .Fn X509_LOOKUP_hash_dir ,
 .Fn X509_LOOKUP_file ,
@@ -119,54 +99,6 @@ They are automatically used by the
 or
 .Xr SSL_CTX_load_verify_locations 3
 functions.
-.Pp
-Internally, loading of certificates and CRLs is implemented via the functions
-.Fn X509_load_cert_crl_file ,
-.Fn X509_load_cert_file
-and
-.Fn X509_load_crl_file .
-These functions support a parameter
-.Fa type ,
-which can be one of the constants
-.Dv FILETYPE_PEM ,
-.Dv FILETYPE_ASN1 ,
-and
-.Dv FILETYPE_DEFAULT .
-They load certificates and/or CRLs from the specified file into a
-memory cache of
-.Vt X509_STORE
-objects which the given
-.Fa ctx
-parameter is associated with.
-.Pp
-The functions
-.Fn X509_load_cert_file
-and
-.Fn X509_load_crl_file
-can load both PEM and DER formats depending on the
-.Fa type
-value.
-Because DER format cannot contain more than one certificate or CRL
-object (while PEM can contain several concatenated PEM objects),
-.Fn X509_load_cert_crl_file
-with
-.Dv FILETYPE_ASN1
-is equivalent to
-.Fn X509_load_cert_file .
-.Pp
-The constant
-.Dv FILETYPE_DEFAULT
-with
-.Dv NULL
-filename causes these functions to load the default certificate
-store file (see
-.Xr X509_STORE_set_default_paths 3 ) .
-.Pp
-All three methods support adding several certificate locations into one
-.Sy X509_STORE .
-.Pp
-This page documents certificate store formats used by these methods and
-caching policy.
 .Ss File Method
 The
 .Fn X509_LOOKUP_file
@@ -186,7 +118,7 @@ As of OpenSSL 1.0.0, it also checks for newer CRLs upon each lookup, so
 that newer CRLs are used as soon as they appear in the directory.
 .Pp
 The directory should contain one certificate or CRL per file in PEM
-format, with a file name of the form
+format, with a filename of the form
 .Ar hash . Ns Ar N
 for a certificate, or
 .Ar hash . Ns Sy r Ns Ar N
@@ -238,44 +170,19 @@ that are already stored in memory, using the function
 This is particularly useful in processes using
 .Xr chroot 2 .
 .Sh RETURN VALUES
-.Fn X509_LOOKUP_hash_dir ,
-.Fn X509_LOOKUP_file ,
-and
-.Fn X509_LOOKUP_mem
-always return a pointer to a static
-.Vt X509_LOOKUP_METHOD
-object.
-.Pp
-.Fn X509_load_cert_file ,
-.Fn X509_load_crl_file ,
-and
-.Fn X509_load_cert_crl_file
-return the number of objects loaded from the
-.Fa file
-or 0 on error.
+These functions always return a pointer to a static object.
 .Sh SEE ALSO
-.Xr d2i_X509_bio 3 ,
-.Xr PEM_read_PrivateKey 3 ,
 .Xr SSL_CTX_load_verify_locations 3 ,
 .Xr X509_LOOKUP_new 3 ,
-.Xr X509_OBJECT_get0_X509 3 ,
 .Xr X509_STORE_load_locations 3 ,
 .Xr X509_STORE_new 3
 .Sh HISTORY
-.Fn X509_LOOKUP_hash_dir ,
-.Fn X509_LOOKUP_file ,
+.Fn X509_LOOKUP_hash_dir
 and
-.Fn X509_load_cert_file
-first appeared in SSLeay 0.8.0.
-.Fn X509_load_crl_file
-first appeared in SSLeay 0.9.0.
-These functions have been available since
+.Fn X509_LOOKUP_file
+first appeared in SSLeay 0.8.0 and have been available since
 .Ox 2.4 .
 .Pp
-.Fn X509_load_cert_crl_file
-first appeared in OpenSSL 0.9.5 and has been available since
-.Ox 2.7 .
-.Pp
 .Fn X509_LOOKUP_mem
 first appeared in
 .Ox 5.7 .
diff --git a/lib/libcrypto/man/X509_LOOKUP_new.3 b/lib/libcrypto/man/X509_LOOKUP_new.3
index f9d81ec6f4e..6fa421b74f9 100644
--- a/lib/libcrypto/man/X509_LOOKUP_new.3
+++ b/lib/libcrypto/man/X509_LOOKUP_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_LOOKUP_new.3,v 1.6 2021/11/05 22:03:25 tb Exp $
+.\" $OpenBSD: X509_LOOKUP_new.3,v 1.7 2021/11/09 16:23:04 schwarze Exp $
 .\"
 .\" Copyright (c) 2021 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: November 5 2021 $
+.Dd $Mdocdate: November 9 2021 $
 .Dt X509_LOOKUP_NEW 3
 .Os
 .Sh NAME
@@ -533,6 +533,7 @@ causes failure but provides no diagnostics.
 .Xr d2i_X509_bio 3 ,
 .Xr PEM_read_bio_X509_AUX 3 ,
 .Xr PEM_X509_INFO_read_bio 3 ,
+.Xr X509_load_cert_file 3 ,
 .Xr X509_LOOKUP_hash_dir 3 ,
 .Xr X509_NAME_hash 3 ,
 .Xr X509_NAME_new 3 ,
diff --git a/lib/libcrypto/man/X509_STORE_load_locations.3 b/lib/libcrypto/man/X509_STORE_load_locations.3
index 4dbfb5fce4d..66d89507378 100644
--- a/lib/libcrypto/man/X509_STORE_load_locations.3
+++ b/lib/libcrypto/man/X509_STORE_load_locations.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_STORE_load_locations.3,v 1.8 2021/08/01 15:37:53 schwarze Exp $
+.\" $OpenBSD: X509_STORE_load_locations.3,v 1.9 2021/11/09 16:23:04 schwarze Exp $
 .\" full merge up to:
 .\" OpenSSL X509_STORE_add_cert b0edda11 Mar 20 13:00:17 2018 +0000
 .\"
@@ -16,7 +16,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 1 2021 $
+.Dd $Mdocdate: November 9 2021 $
 .Dt X509_STORE_LOAD_LOCATIONS 3
 .Os
 .Sh NAME
@@ -162,6 +162,7 @@ default directory for
 .El
 .Sh SEE ALSO
 .Xr SSL_CTX_load_verify_locations 3 ,
+.Xr X509_load_cert_file 3 ,
 .Xr X509_LOOKUP_hash_dir 3 ,
 .Xr X509_LOOKUP_new 3 ,
 .Xr X509_STORE_new 3 ,
diff --git a/lib/libcrypto/man/X509_STORE_new.3 b/lib/libcrypto/man/X509_STORE_new.3
index 71b88f999d3..c84be75cbb7 100644
--- a/lib/libcrypto/man/X509_STORE_new.3
+++ b/lib/libcrypto/man/X509_STORE_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_STORE_new.3,v 1.5 2019/06/06 01:06:59 schwarze Exp $
+.\" $OpenBSD: X509_STORE_new.3,v 1.6 2021/11/09 16:23:04 schwarze Exp $
 .\" full merge up to: OpenSSL 05ea606a May 20 20:52:46 2016 -0400
 .\" selective merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
@@ -67,7 +67,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 6 2019 $
+.Dd $Mdocdate: November 9 2021 $
 .Dt X509_STORE_NEW 3
 .Os
 .Sh NAME
@@ -124,6 +124,7 @@ returns 1 for success and 0 for failure.
 .Sh SEE ALSO
 .Xr PKCS7_verify 3 ,
 .Xr SSL_CTX_set_cert_store 3 ,
+.Xr X509_load_cert_file 3 ,
 .Xr X509_LOOKUP_hash_dir 3 ,
 .Xr X509_OBJECT_get0_X509 3 ,
 .Xr X509_STORE_CTX_new 3 ,
diff --git a/lib/libcrypto/man/X509_load_cert_file.3 b/lib/libcrypto/man/X509_load_cert_file.3
new file mode 100644
index 00000000000..95a83dd00ee
--- /dev/null
+++ b/lib/libcrypto/man/X509_load_cert_file.3
@@ -0,0 +1,133 @@
+.\" $OpenBSD: X509_load_cert_file.3,v 1.1 2021/11/09 16:23:04 schwarze Exp $
+.\"
+.\" Copyright (c) 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: November 9 2021 $
+.Dt X509_LOAD_CERT_FILE 3
+.Os
+.Sh NAME
+.Nm X509_load_cert_file ,
+.Nm X509_load_crl_file ,
+.Nm X509_load_cert_crl_file
+.Nd read, decode, and cache certificates and CRLs
+.Sh SYNOPSIS
+.In openssl/x509_vfy.h
+.Ft int
+.Fo X509_load_cert_file
+.Fa "X509_LOOKUP *ctx"
+.Fa "const char *file"
+.Fa "int type"
+.Fc
+.Ft int
+.Fo X509_load_crl_file
+.Fa "X509_LOOKUP *ctx"
+.Fa "const char *file"
+.Fa "int type"
+.Fc
+.Ft int
+.Fo X509_load_cert_crl_file
+.Fa "X509_LOOKUP *ctx"
+.Fa "const char *file"
+.Fa "int type"
+.Fc
+.Sh DESCRIPTION
+.Fn X509_load_cert_file
+with a
+.Fa type
+of
+.Dv X509_FILETYPE_PEM
+reads one or more certificates in PEM format from the given
+.Fa file
+using
+.Xr PEM_read_bio_X509_AUX 3 ;
+with a type of
+.Dv X509_FILETYPE_ASN1 ,
+if reads one certificate in DER format using
+.Xr d2i_X509_bio 3 .
+The certificates read are added to the
+.Vt X509_STORE
+memory cache object associated with the given
+.Fa ctx
+using
+.Xr X509_STORE_add_cert 3 .
+.Pp
+.Fn X509_load_crl_file
+with a
+.Fa type
+of
+.Dv X509_FILETYPE_PEM
+reads one or more certificate revocation lists in PEM format from the given
+.Fa file
+using
+.Xr PEM_read_bio_X509_CRL 3 ;
+with a type of
+.Dv X509_FILETYPE_ASN1 ,
+if reads one certificate revocation lists in DER format using
+.Xr d2i_X509_CRL_bio 3 .
+The certificate revocation lists read are added to the
+.Vt X509_STORE
+memory cache object associated with the given
+.Fa ctx
+using
+.Xr X509_STORE_add_crl 3 .
+.Pp
+.Fn X509_load_cert_crl_file
+with a
+.Fa type
+of
+.Dv X509_FILETYPE_PEM
+read one or more certificates and/or certificate revocation lists
+in PEM format from the given
+.Fa file
+using
+.Xr PEM_X509_INFO_read_bio 3
+and adds them to the
+.Vt X509_STORE
+memory cache object associated with the given
+.Fa ctx
+using
+.Xr X509_STORE_add_cert 3
+and
+.Xr X509_STORE_add_crl 3 ,
+respectively.
+.Pp
+.Fn X509_load_cert_crl_file
+with a
+.Fa type
+of
+.Dv X509_FILETYPE_ASN1
+is equivalent to
+.Fn X509_load_cert_file
+and cannot be used to read a certificate revocation list.
+.Sh RETURN VALUES
+These functions return the number of objects loaded or 0 on error.
+.Sh SEE ALSO
+.Xr d2i_X509_bio 3 ,
+.Xr PEM_read_PrivateKey 3 ,
+.Xr X509_LOOKUP_new 3 ,
+.Xr X509_OBJECT_get0_X509 3 ,
+.Xr X509_STORE_load_locations 3 ,
+.Xr X509_STORE_new 3
+.Sh HISTORY
+.Fn X509_load_cert_file
+first appeared in SSLeay 0.8.0 and
+.Fn X509_load_crl_file
+in SSLeay 0.9.0.
+These functions have been available since
+.Ox 2.4 .
+.Pp
+.Fn X509_load_cert_crl_file
+first appeared in OpenSSL 0.9.5 and has been available since
+.Ox 2.7 .
diff --git a/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3
index 581c954c1a4..296e9b8cfc3 100644
--- a/lib/libcrypto/man/X509_new.3
+++ b/lib/libcrypto/man/X509_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_new.3,v 1.34 2021/10/28 15:30:54 schwarze Exp $
+.\" $OpenBSD: X509_new.3,v 1.35 2021/11/09 16:23:04 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file is a derived work.
@@ -66,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: October 28 2021 $
+.Dd $Mdocdate: November 9 2021 $
 .Dt X509_NEW 3
 .Os
 .Sh NAME
@@ -223,6 +223,7 @@ if an error occurs.
 .Xr X509_get_subject_name 3 ,
 .Xr X509_get_version 3 ,
 .Xr X509_INFO_new 3 ,
+.Xr X509_load_cert_file 3 ,
 .Xr X509_LOOKUP_hash_dir 3 ,
 .Xr X509_LOOKUP_new 3 ,
 .Xr X509_NAME_new 3 ,