SSL_CTX_set_client_CA_list.pod revision 261037
172613Skris=pod 272613Skris 372613Skris=head1 NAME 472613Skris 572613SkrisSSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA, 672613SkrisSSL_add_client_CA - set list of CAs sent to the client when requesting a 772613Skrisclient certificate 872613Skris 972613Skris=head1 SYNOPSIS 1072613Skris 1172613Skris #include <openssl/ssl.h> 1272613Skris 1372613Skris void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list); 1472613Skris void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list); 1572613Skris int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert); 1672613Skris int SSL_add_client_CA(SSL *ssl, X509 *cacert); 1772613Skris 1872613Skris=head1 DESCRIPTION 1972613Skris 2072613SkrisSSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when 2172613Skrisrequesting a client certificate for B<ctx>. 2272613Skris 2372613SkrisSSL_set_client_CA_list() sets the B<list> of CAs sent to the client when 2472613Skrisrequesting a client certificate for the chosen B<ssl>, overriding the 2572613Skrissetting valid for B<ssl>'s SSL_CTX object. 2672613Skris 2772613SkrisSSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the 2872613Skrislist of CAs sent to the client when requesting a client certificate for 2972613SkrisB<ctx>. 3072613Skris 3172613SkrisSSL_add_client_CA() adds the CA name extracted from B<cacert> to the 3272613Skrislist of CAs sent to the client when requesting a client certificate for 3372613Skristhe chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object. 3472613Skris 3572613Skris=head1 NOTES 3672613Skris 3772613SkrisWhen a TLS/SSL server requests a client certificate (see 3872613SkrisB<SSL_CTX_set_verify_options()>), it sends a list of CAs, for which 3979998Skrisit will accept certificates, to the client. 4072613Skris 4179998SkrisThis list must explicitly be set using SSL_CTX_set_client_CA_list() for 4272613SkrisB<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list 4372613Skrisspecified overrides the previous setting. The CAs listed do not become 4472613Skristrusted (B<list> only contains the names, not the complete certificates); use 4572613SkrisL<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> 4672613Skristo additionally load them for verification. 4772613Skris 4879998SkrisIf the list of acceptable CAs is compiled in a file, the 4979998SkrisL<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)> 5079998Skrisfunction can be used to help importing the necessary data. 5179998Skris 5272613SkrisSSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional 5372613Skrisitems the list of client CAs. If no list was specified before using 5472613SkrisSSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client 5579998SkrisCA list for B<ctx> or B<ssl> (as appropriate) is opened. 5672613Skris 5772613SkrisThese functions are only useful for TLS/SSL servers. 5872613Skris 5972613Skris=head1 RETURN VALUES 6072613Skris 6172613SkrisSSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return 6272613Skrisdiagnostic information. 6372613Skris 6472613SkrisSSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return 6572613Skrisvalues: 6672613Skris 6772613Skris=over 4 6872613Skris 69261037Sjkim=item Z<>0 7072613Skris 7176866SkrisA failure while manipulating the STACK_OF(X509_NAME) object occurred or 7272613Skristhe X509_NAME could not be extracted from B<cacert>. Check the error stack 7372613Skristo find out the reason. 7472613Skris 75261037Sjkim=item Z<>1 76261037Sjkim 77261037SjkimThe operation succeeded. 78261037Sjkim 7972613Skris=back 8072613Skris 8179998Skris=head1 EXAMPLES 8279998Skris 8379998SkrisScan all certificates in B<CAfile> and list them as acceptable CAs: 8479998Skris 8579998Skris SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(CAfile)); 8679998Skris 8772613Skris=head1 SEE ALSO 8872613Skris 8972613SkrisL<ssl(3)|ssl(3)>, 9072613SkrisL<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, 9179998SkrisL<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>, 9272613SkrisL<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> 9372613Skris 9472613Skris=cut 95