Merge the CA list documentation for clarity

Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/7503)

3 files changed, 122 insertions, 199 deletions

diff --git a/doc/man3/SSL_CTX_set0_CA_list.pod b/doc/man3/SSL_CTX_set0_CA_list.pod
index 37a4cee9ca..d7ed89775b 100644
--- a/doc/man3/SSL_CTX_set0_CA_list.pod
+++ b/doc/man3/SSL_CTX_set0_CA_list.pod
@@ -2,14 +2,32 @@
 
 =head1 NAME
 
-SSL_set0_CA_list, SSL_CTX_set0_CA_list, SSL_get0_CA_list,
-SSL_CTX_get0_CA_list, SSL_add1_to_CA_list, SSL_CTX_add1_to_CA_list,
-SSL_get0_peer_CA_list - get or set CA list
+SSL_CTX_set_client_CA_list,
+SSL_set_client_CA_list,
+SSL_get_client_CA_list,
+SSL_CTX_get_client_CA_list,
+SSL_CTX_add_client_CA,
+SSL_add_client_CA,
+SSL_set0_CA_list,
+SSL_CTX_set0_CA_list,
+SSL_get0_CA_list,
+SSL_CTX_get0_CA_list,
+SSL_add1_to_CA_list,
+SSL_CTX_add1_to_CA_list,
+SSL_get0_peer_CA_list
+- get or set CA list
 
 =head1 SYNOPSIS
 
  #include <openssl/ssl.h>
 
+ void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
+ void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
+ STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s);
+ STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);
+ int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
+ int SSL_add_client_CA(SSL *ssl, X509 *cacert);
+
  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);
@@ -21,6 +39,70 @@ SSL_get0_peer_CA_list - get or set CA list
 
 =head1 DESCRIPTION
 
+The functions described here set and manage the list of CA names that are sent
+between two communicating peers.
+
+For TLS versions 1.2 and earlier the list of CA names is only sent from the
+server to the 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 may be sent by a client (in the ClientHello message) or by
+a server (when requesting a certificate).
+
+In most cases it is not necessary to set CA names on the client side. The list
+of CA names that are acceptable to the client will be sent in plaintext to the
+server. This has privacy implications and may also have performance implications
+if the list is large. This optional capability was introduced as part of TLSv1.3
+and therefore setting CA names on the client side will have no impact if that
+protocol version has been disabled. Most servers do not need this and so this
+should be avoided unless required.
+
+The "client CA list" functions below only have an effect when called on the
+server side.
+
+SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when
+requesting a client certificate for B<ctx>. Ownership of B<list> is transferred
+to B<ctx> and it should not be freed by the caller.
+
+SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when
+requesting a client certificate for the chosen B<ssl>, overriding the
+setting valid for B<ssl>'s SSL_CTX object. Ownership of B<list> is transferred
+to B<s> and it should not be freed by the caller.
+
+SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for
+B<ctx> using SSL_CTX_set_client_CA_list(). The returned list should not be freed
+by the caller.
+
+SSL_get_client_CA_list() returns the list of client CAs explicitly
+set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with
+SSL_CTX_set_client_CA_list(), when in server mode. In client mode,
+SSL_get_client_CA_list returns the list of client CAs sent from the server, if
+any. The returned list should not be freed by the caller.
+
+SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the
+list of CAs sent to the client when requesting a client certificate for
+B<ctx>.
+
+SSL_add_client_CA() adds the CA name extracted from B<cacert> to the
+list of CAs sent to the client when requesting a client certificate for
+the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object.
+
+SSL_get0_peer_CA_list() retrieves the list of CA names (if any) the peer
+has sent. This can be called on either the server or the client side. The
+returned list should not be freed by the caller.
+
+The "generic CA list" functions below are very similar to the "client CA
+list" functions except that they have an effect on both the server and client
+sides. The lists of CA names managed are separate - so you cannot (for example)
+set CA names using the "client CA list" functions and then get them using the
+"generic CA list" functions. Where a mix of the two types of functions has been
+used on the server side then the "client CA list" functions take precedence.
+Typically, on the server side, the "client CA list " functions should be used in
+preference. As noted above in most cases it is not necessary to set CA names on
+the client side. 
+
 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.
@@ -30,10 +112,11 @@ 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>.
+B<ctx>. The returned list should not be freed by the caller.
 
-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_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. The
+returned list should not be freed by the caller.
 
 SSL_CTX_add1_to_CA_list() appends the CA subject name extracted from B<x> to the
 list of CAs sent to peer for B<ctx>.
@@ -42,50 +125,60 @@ SSL_add1_to_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)>. If both these
-and L<SSL_CTX_set_client_CA_list(3)> or similar functions are used, then the
-latter functions take priority on the server side (they are ignored on the
-client side).
+When a TLS/SSL server requests a client certificate (see
+B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which it will accept
+certificates, to the client.
 
-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>.
+This list must explicitly be set using SSL_CTX_set_client_CA_list() or
+SSL_CTX_set0_CA_list() for B<ctx> and SSL_set_client_CA_list() or
+SSL_set0_CA_list() for the specific B<ssl>. The list specified
+overrides the previous setting. The CAs listed do not become trusted (B<list>
+only contains the names, not the complete certificates); use
+L<SSL_CTX_load_verify_locations(3)> to additionally load them for verification.
 
-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).
+If the list of acceptable CAs is compiled in a file, the
+L<SSL_load_client_CA_file(3)> function can be used to help to import the
+necessary data.
+
+SSL_CTX_add_client_CA(), SSL_CTX_add1_to_CA_list(), SSL_add_client_CA() and
+SSL_add1_to_CA_list() can be used to add additional items the list of CAs. If no
+list was specified before using SSL_CTX_set_client_CA_list(),
+SSL_CTX_set0_CA_list(), SSL_set_client_CA_list() or SSL_set0_CA_list(), a
+new CA list for B<ctx> or B<ssl> (as appropriate) is opened.
 
 =head1 RETURN VALUES
 
-SSL_CTX_set0_CA_list() and SSL_set0_CA_list() do not return a value.
+SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(),
+SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(), 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_get_client_CA_list(), SSL_get_client_CA_list(), 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_to_CA_list() and SSL_add1_to_CA_list() return 1 for success and 0
-for failure.
+SSL_CTX_add_client_CA(),SSL_add_client_CA(), SSL_CTX_add1_to_CA_list() and
+SSL_add1_to_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.
 
+=head1 EXAMPLES
+
+Scan all certificates in B<CAfile> and list them as acceptable CAs:
+
+ SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
+
 =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-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2018 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
diff --git a/doc/man3/SSL_CTX_set_client_CA_list.pod b/doc/man3/SSL_CTX_set_client_CA_list.pod
deleted file mode 100644
index e23999aaae..0000000000
--- a/doc/man3/SSL_CTX_set_client_CA_list.pod
+++ /dev/null
@@ -1,108 +0,0 @@
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
-SSL_add_client_CA - set list of CAs sent to the client when requesting a
-client certificate
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
- void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
- int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
- int SSL_add_client_CA(SSL *ssl, X509 *cacert);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when
-requesting a client certificate for B<ctx>.
-
-SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when
-requesting a client certificate for the chosen B<ssl>, overriding the
-setting valid for B<ssl>'s SSL_CTX object.
-
-SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the
-list of CAs sent to the client when requesting a client certificate for
-B<ctx>.
-
-SSL_add_client_CA() adds the CA name extracted from B<cacert> to the
-list of CAs sent to the client when requesting a client certificate for
-the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object.
-
-=head1 NOTES
-
-These functions are similar to L<SSL_CTX_set0_CA_list(3)> and similar functions
-but only have an effect on the server side. These functions are present for
-backwards compatibility. L<SSL_CTX_set0_CA_list(3)> and similar functions should
-be used in preference.
-
-When a TLS/SSL server requests a client certificate (see
-B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which
-it will accept certificates, to the client.
-
-This list must explicitly be set using SSL_CTX_set_client_CA_list() for
-B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list
-specified overrides the previous setting. The CAs listed do not become
-trusted (B<list> only contains the names, not the complete certificates); use
-L<SSL_CTX_load_verify_locations(3)>
-to additionally load them for verification.
-
-If the list of acceptable CAs is compiled in a file, the
-L<SSL_load_client_CA_file(3)>
-function can be used to help importing the necessary data.
-
-SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional
-items the list of client CAs. If no list was specified before using
-SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client
-CA list for B<ctx> or B<ssl> (as appropriate) is opened.
-
-These functions are only useful for TLS/SSL servers.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
-diagnostic information.
-
-SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
-values:
-
-=over 4
-
-=item Z<>0
-
-A failure while manipulating the STACK_OF(X509_NAME) object occurred or
-the X509_NAME could not be extracted from B<cacert>. Check the error stack
-to find out the reason.
-
-=item Z<>1
-
-The operation succeeded.
-
-=back
-
-=head1 EXAMPLES
-
-Scan all certificates in B<CAfile> and list them as acceptable CAs:
-
- SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
-
-=head1 SEE ALSO
-
-L<ssl(7)>,
-L<SSL_get_client_CA_list(3)>,
-L<SSL_load_client_CA_file(3)>,
-L<SSL_CTX_load_verify_locations(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 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
diff --git a/doc/man3/SSL_get_client_CA_list.pod b/doc/man3/SSL_get_client_CA_list.pod
deleted file mode 100644
index 40c3561efc..0000000000
--- a/doc/man3/SSL_get_client_CA_list.pod
+++ /dev/null
@@ -1,62 +0,0 @@
-=pod
-
-=head1 NAME
-
-SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s);
- STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);
-
-=head1 DESCRIPTION
-
-SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for
-B<ctx> using L<SSL_CTX_set_client_CA_list(3)>.
-
-SSL_get_client_CA_list() returns the list of client CAs explicitly
-set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with
-L<SSL_CTX_set_client_CA_list(3)>, when in
-server mode. In client mode, SSL_get_client_CA_list returns the list of
-client CAs sent from the server, if any.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
-diagnostic information.
-
-SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
-values:
-
-=over 4
-
-=item STACK_OF(X509_NAMES)
-
-List of CA names explicitly set (for B<ctx> or in server mode) or send
-by the server (client mode).
-
-=item NULL
-
-No client CA list was explicitly set (for B<ctx> or in server mode) or
-the server did not send a list of CAs (client mode).
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(7)>,
-L<SSL_CTX_set_client_CA_list(3)>,
-L<SSL_CTX_set_client_cert_cb(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 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