1 files changed, 103 insertions, 25 deletions

diff --git a/src/lib/libssl/man/SSL_load_client_CA_file.3 b/src/lib/libssl/man/SSL_load_client_CA_file.3
index ba08dff77f..4eab59ff6e 100644
--- a/src/lib/libssl/man/SSL_load_client_CA_file.3
+++ b/src/lib/libssl/man/SSL_load_client_CA_file.3
@@ -1,7 +1,24 @@
-.\"     $OpenBSD: SSL_load_client_CA_file.3,v 1.2 2016/12/04 12:20:54 schwarze Exp $
+.\"     $OpenBSD: SSL_load_client_CA_file.3,v 1.3 2016/12/07 14:38:43 schwarze Exp $
 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
-.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2016 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.
+.\"
+.\" The original file was written by Lutz Jaenicke <jaenicke@openssl.org>.
 .\" Copyright (c) 2000 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -48,42 +65,69 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 4 2016 $
+.Dd $Mdocdate: December 7 2016 $
 .Dt SSL_LOAD_CLIENT_CA_FILE 3
 .Os
 .Sh NAME
-.Nm SSL_load_client_CA_file
-.Nd load certificate names from file
+.Nm SSL_load_client_CA_file ,
+.Nm SSL_add_file_cert_subjects_to_stack ,
+.Nm SSL_add_dir_cert_subjects_to_stack
+.Nd load certificate names from files
 .Sh SYNOPSIS
 .In openssl/ssl.h
 .Ft STACK_OF(X509_NAME) *
 .Fn SSL_load_client_CA_file "const char *file"
+.Ft int
+.Fo SSL_add_file_cert_subjects_to_stack
+.Fa "STACK_OF(X509_NAME) *stack"
+.Fa "const char *file"
+.Fc
+.Ft int
+.Fo SSL_add_dir_cert_subjects_to_stack
+.Fa "STACK_OF(X509_NAME) *stack"
+.Fa "const char *dir"
+.Fc
 .Sh DESCRIPTION
 .Fn SSL_load_client_CA_file
-reads certificates from
+reads PEM formatted certificates from
 .Fa file
-and returns a
-.Dv STACK_OF Ns
-.Pq Vt X509_NAME
+and returns a new
+.Vt STACK_OF(X509_NAME)
 with the subject names found.
-.Pp
-.Fn SSL_load_client_CA_file
-reads a file of PEM formatted certificates and extracts the
-.Vt X509_NAME Ns s
-of the certificates found.
-While the name suggests the specific usage as support function for
+While the name suggests the specific usage as a support function for
 .Xr SSL_CTX_set_client_CA_list 3 ,
 it is not limited to CA certificates.
+.Pp
+.Fn SSL_add_file_cert_subjects_to_stack
+is similar except that the names are added to the existing
+.Fa stack .
+.Pp
+.Fn SSL_add_dir_cert_subjects_to_stack
+calls
+.Fn SSL_add_file_cert_subjects_to_stack
+on every file in the directory
+.Fa dir .
+.Pp
+If a name is already on the stack, all these functions skip it and
+do not add it again.
 .Sh RETURN VALUES
-The following return values can occur:
-.Bl -tag -width Ds
-.It Dv NULL
-The operation failed, check out the error stack for the reason.
-.It Pointer to Dv STACK_OF Ns Po Vt X509_NAME Pc
-Pointer to the subject names of the successfully read certificates.
-.El
+.Fn SSL_load_client_CA_file
+returns a pointer to the new
+.Vt STACK_OF(X509_NAME)
+or
+.Dv NULL on failure.
+.Pp
+.Fn SSL_add_file_cert_subjects_to_stack
+and
+.Fn SSL_add_dir_cert_subjects_to_stack
+return 1 for success or 0 for failure.
+.Pp
+All these functions treat empty files and directories as failures.
+.Pp
+In some cases of failure, the reason can be determined with
+.Xr ERR_get_error 3 .
 .Sh EXAMPLES
-Load names of CAs from file and use it as a client CA list:
+Load names of CAs from a file and use it as a client CA list:
 .Bd -literal
 SSL_CTX *ctx;
 STACK_OF(X509_NAME) *cert_names;
@@ -96,5 +140,39 @@ else
 \&...
 .Ed
 .Sh SEE ALSO
-.Xr ssl 3 ,
-.Xr SSL_CTX_set_client_CA_list 3
+.Xr PEM_read_bio_X509 3 ,
+.Xr SSL_CTX_set_client_CA_list 3 ,
+.Xr X509_get_subject_name 3
+.Sh HISTORY
+.Fn SSL_add_file_cert_subjects_to_stack
+and
+.Fn SSL_add_dir_cert_subjects_to_stack
+first appeared in OpenSSL 0.9.2b.
+.Sh AUTHORS
+.Fn SSL_add_file_cert_subjects_to_stack
+and
+.Fn SSL_add_dir_cert_subjects_to_stack
+were written by
+.An Ben Laurie Aq Mt ben@openssl.org
+in 1999.
+.Sh BUGS
+In some cases of failure, for example for empty files and directories,
+these functions fail to report an error, in the sense that
+.Xr ERR_get_error 3
+does not work.
+.Pp
+Even in case of failure, for example when parsing one of the
+files or certificates fails,
+.Fn SSL_add_file_cert_subjects_to_stack
+and
+.Fn SSL_add_dir_cert_subjects_to_stack
+may still have added some certificates to the stack.
+.Pp
+The behaviour of
+.Fn SSL_add_dir_cert_subjects_to_stack
+is non-deterministic.
+If parsing one file fails, parsing of the whole directory is aborted.
+Files in the directory are not parsed in any specific order.
+For example, adding an empty file to
+.Fa dir
+may or may not cause some of the other files to be ignored.