Write a new manual page X509_STORE_load_locations(3) from scratch.

Not documented by OpenSSL, but listed in <openssl/x509_vfy.h>
and referenced from X509_LOOKUP_hash_dir(3), and clearly more
important than the latter.  Fixes three dead links reported by jmc@.

Most of the information from SSL_CTX_load_verify_locations(3) should
probably be moved here, but not all, since the SSL page also talks
about SSL servers and clients and the like.  As i'm not completely
sure regarding the boundaries, i'm leaving that as it is for now.

2 files changed, 119 insertions, 1 deletions

diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 42ec3807a2..46e8ba5739 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.111 2017/01/05 22:38:04 schwarze Exp $
+# $OpenBSD: Makefile,v 1.112 2017/01/07 00:45:04 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -212,6 +212,7 @@ MAN=	\
         X509_STORE_CTX_get_ex_new_index.3 \
         X509_STORE_CTX_new.3 \
         X509_STORE_CTX_set_verify_cb.3 \
+        X509_STORE_load_locations.3 \
         X509_STORE_set_verify_cb_func.3 \
         X509_STORE_set1_param.3 \
         X509_VERIFY_PARAM_set_flags.3 \
diff --git a/src/lib/libcrypto/man/X509_STORE_load_locations.3 b/src/lib/libcrypto/man/X509_STORE_load_locations.3
new file mode 100644
index 0000000000..fa24044a36
--- /dev/null
+++ b/src/lib/libcrypto/man/X509_STORE_load_locations.3
@@ -0,0 +1,117 @@
+.\"     $OpenBSD: X509_STORE_load_locations.3,v 1.1 2017/01/07 00:45:04 schwarze Exp $
+.\"
+.\" Copyright (c) 2017 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: January 7 2017 $
+.Dt X509_STORE_LOAD_LOCATIONS 3
+.Os
+.Sh NAME
+.Nm X509_STORE_load_locations ,
+.Nm X509_STORE_set_default_paths
+.Nd configure files and directories used by a certificate store
+.Sh SYNOPSIS
+.In openssl/x509_vfy.h
+.Ft int
+.Fo X509_STORE_load_locations
+.Fa "X509_STORE *store"
+.Fa "const char *file"
+.Fa "const char *dirs"
+.Fc
+.Ft int
+.Fo X509_STORE_set_default_paths
+.Fa "X509_STORE *store"
+.Fc
+.Sh DESCRIPTION
+.Fn X509_STORE_load_locations
+instructs the
+.Fa store
+to use the PEM file
+.Fa file
+and all the PEM files in the directories
+contained in the colon-separated list
+.Fa dirs
+for looking up certificates, in addition to files and directories
+that are already configured.
+Directories already in use are not added again.
+If
+.Dv NULL
+is passed for
+.Fa file
+or
+.Fa dirs ,
+no new file or no new directories are added, respectively.
+.Pp
+.Fn X509_STORE_load_locations
+is identical to
+.Xr SSL_CTX_load_verify_locations 3
+except that it operates directly on an
+.Vt X509_STORE
+object, rather than on the store used by an SSL context.
+See that manual page for more information.
+.Pp
+.Fn X509_STORE_set_default_paths
+is similar except that it instructs the
+.Fa store
+to use the default PEM file and directory, see
+.Sx FILES ,
+in addition to what is already configured.
+It ignores errors that occur while trying to load the file or to
+add the directory, but it may still fail for other reasons, for
+example when out of memory while trying to allocate the required
+.Vt X509_LOOKUP
+objects.
+.Pp
+.Fn X509_STORE_set_default_paths
+is identical to
+.Xr SSL_CTX_set_default_verify_paths 3
+except that it operates directly on an
+.Vt X509_STORE
+object, rather than on the store used by an SSL context.
+See that manual page for more information.
+.Sh RETURN VALUES
+.Fn X509_STORE_load_locations
+returns 1 if all files and directories specified were successfully
+added.
+It returns 0 for failure.
+That can happen if adding the file failed, if adding any of the
+directories failed, or if both arguments were
+.Dv NULL .
+.Pp
+.Fn X509_STORE_set_default_paths
+returns 0 for some error conditions and 1 otherwise, not just for
+success, but also for various cases of failure.
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa /etc/ssl/cert.pem
+default PEM file for
+.Fn X509_STORE_set_default_paths
+.It Pa /etc/ssl/certs/
+default directory for
+.Fn X509_STORE_set_default_paths
+.El
+.Sh SEE ALSO
+.Xr SSL_CTX_load_verify_locations 3 ,
+.Xr X509_LOOKUP_hash_dir 3 ,
+.Xr X509_STORE_set1_param 3 ,
+.Xr X509_STORE_set_verify_cb 3
+.Sh BUGS
+By the time adding a directory is found to fail, the file and some
+other directories may already have been successfully loaded, so
+these functions may change the state of the store even when they
+fail.
+.Pp
+.Fn X509_STORE_set_default_paths
+clears the error queue, deleting even error information that was
+already present when it was called.