diff options
author | Matt Caswell <matt@openssl.org> | 2018-11-01 11:53:49 +0000 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2018-11-12 14:29:11 +0000 |
commit | 6e68dae85a8f91944370125561c7ec0d5da46c20 (patch) | |
tree | efddf088f026ded5a2e43a3c8cfae90b2a223838 | |
parent | fb8c83599e869516552f7c27bdc4dd26947fe657 (diff) |
Merge the CA list documentation for clarity
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/7503)
-rw-r--r-- | doc/man3/SSL_CTX_set0_CA_list.pod | 151 | ||||
-rw-r--r-- | doc/man3/SSL_CTX_set_client_CA_list.pod | 108 | ||||
-rw-r--r-- | doc/man3/SSL_get_client_CA_list.pod | 62 |
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 |