From 5a185729a3b029845c4596657b4495b3a8ead6f0 Mon Sep 17 00:00:00 2001
From: "Dr. Stephen Henson" <steve@openssl.org>
Date: Fri, 31 Mar 2017 17:15:22 +0100
Subject: [PATCH] Document new ssl(3) functions and options.

Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3015)
---
 doc/man1/s_client.pod             |  7 +++
 doc/man3/SSL_CONF_cmd.pod         |  8 +++
 doc/man3/SSL_CTX_set0_CA_list.pod | 94 +++++++++++++++++++++++++++++++
 3 files changed, 109 insertions(+)
 create mode 100644 doc/man3/SSL_CTX_set0_CA_list.pod

diff --git a/doc/man1/s_client.pod b/doc/man1/s_client.pod
index e9794c4af7..272d997d98 100644
--- a/doc/man1/s_client.pod
+++ b/doc/man1/s_client.pod
@@ -25,6 +25,7 @@ B<openssl> B<s_client>
 [B<-CAfile filename>]
 [B<-no-CAfile>]
 [B<-no-CApath>]
+[B<-requestCAfile filename>]
 [B<-dane_tlsa_domain domain>]
 [B<-dane_tlsa_rrdata rrdata>]
 [B<-dane_ee_no_namechecks>]
@@ -218,6 +219,12 @@ Do not load the trusted CA certificates from the default file location
 
 Do not load the trusted CA certificates from the default directory location
 
+=item B<-requestCAfile file>
+
+A file containing a list of certificates whose subject names will be sent
+to the server in the B<certificate_authorities> extension. Only supported
+for TLS 1.3
+
 =item B<-dane_tlsa_domain domain>
 
 Enable RFC6698/RFC7671 DANE TLSA authentication and specify the
diff --git a/doc/man3/SSL_CONF_cmd.pod b/doc/man3/SSL_CONF_cmd.pod
index 6045a4f7d6..f5c6576ed0 100644
--- a/doc/man3/SSL_CONF_cmd.pod
+++ b/doc/man3/SSL_CONF_cmd.pod
@@ -217,6 +217,14 @@ These options indicate a file or directory used for building certificate
 chains or verifying certificate chains. These options are only supported
 if certificate operations are permitted.
 
+=item B<RequestCAFile>
+
+This option indicates a file containing a set of certificates in PEM form.
+The subject names of the certificates are sent to the peer in the
+B<certificate_authorities> extension for TLS 1.3 (in ClientHello or
+CertificateRequest) or in a certificate request for previous versions or
+TLS.
+
 =item B<ServerInfoFile>
 
 Attempts to use the file B<value> in the "serverinfo" extension using the
diff --git a/doc/man3/SSL_CTX_set0_CA_list.pod b/doc/man3/SSL_CTX_set0_CA_list.pod
new file mode 100644
index 0000000000..5e94f5c954
--- /dev/null
+++ b/doc/man3/SSL_CTX_set0_CA_list.pod
@@ -0,0 +1,94 @@
+=pod
+
+=head1 NAME
+
+SSL_set0_CA_list, SSL_CTX_set0_CA_list, SSL_get0_CA_list,
+SSL_CTX_get0_CA_list, SSL_add1_CA_list, SSL_CTX_add1_CA_list,
+SSL_get0_peer_CA_list - get or set CA list
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set0_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *name_list);
+ void SSL_set0_CA_list(SSL *s, STACK_OF(X509_NAME) *name_list);
+ const STACK_OF(X509_NAME) *SSL_CTX_get0_CA_list(const SSL_CTX *ctx);
+ const STACK_OF(X509_NAME) *SSL_get0_CA_list(const SSL *s);
+ int SSL_CTX_add1_CA_list(SSL_CTX *ctx, const X509 *x);
+ int SSL_add1_CA_list(SSL *ssl, const X509 *x);
+
+ const STACK_OF(X509_NAME) *SSL_get0_peer_CA_list(const SSL *s);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set0_CA_list() sets the list of CAs to be sent to the peer to
+B<name_list>. Ownership of B<name_list> is transferred to B<ctx> and
+it should not be freed by the caller.
+
+SSL_set0_CA_list() sets the list of CAs to be sent to the peer to B<name_list>
+overriding any list set in the parent B<SSL_CTX> of B<s>. Ownership of
+B<name_list> is transferred to B<s> and it should not be freed by the caller.
+
+SSL_CTX_get0_CA_list() retrieves any previously set list of CAs set for
+B<ctx>.
+
+SSL_CTX_get0_CA_list() retrieves any previously set list of CAs set for
+B<s> or if none are set the list from the parent B<SSL_CTX> is retrieved.
+
+SSL_CTX_add1_CA_list() appends the CA subject name extracted from B<x> to the
+list of CAs sent to peer for B<ctx>.
+
+SSL_add1_CA_list() appends the CA subject name extracted from B<x> to the
+list of CAs sent to the peer for B<s>, overriding the setting in the parent
+B<SSL_CTX>.
+
+SSL_get0_peer_CA_list() retrieves the list of CA names (if any) the peer
+has sent.
+
+=head1 NOTES
+
+These functions are generalised versions of the client authentication
+CA list functions such as L<SSL_CTX_set_client_CA_list(3)>.
+
+For TLS versions before 1.3 the list of CA names is only sent from the server
+to client when requesting a client certificate. So any list of CA names set
+is never sent from client to server and the list of CA names retrieved by
+SSL_get0_peer_CA_list() is always B<NULL>.
+
+For TLS 1.3 the list of CA names is sent using the B<certificate_authorities>
+extension and will be sent by a client (in the ClientHello message) or by
+a server (when requesting a certificate).
+
+=head1 RETURN VALUES
+
+SSL_CTX_set0_CA_list() and SSL_set0_CA_list() do not return a value.
+
+SSL_CTX_get0_CA_list() and SSL_get0_CA_list() return a stack of CA names
+or B<NULL> is no CA names are set.
+
+SSL_CTX_add1_CA_list() and SSL_add1_CA_list() return 1 for success and 0
+for failure.
+
+SSL_get0_peer_CA_list() returns a stack of CA names sent by the peer or
+B<NULL> or an empty stack if no list was sent.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(7)>,
+L<SSL_CTX_set_client_CA_list(3)>,
+L<SSL_get_client_CA_list(3)>,
+L<SSL_load_client_CA_file(3)>,
+L<SSL_CTX_load_verify_locations(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
-- 
2.25.1