doc/man3/SSL_CTX_set_client_CA_list.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
   6 SSL_add_client_CA - set list of CAs sent to the client when requesting a
   7 client certificate
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/ssl.h>
  12
  13  void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
  14  void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
  15  int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
  16  int SSL_add_client_CA(SSL *ssl, X509 *cacert);
  17
  18 =head1 DESCRIPTION
  19
  20 SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when
  21 requesting a client certificate for B<ctx>.
  22
  23 SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when
  24 requesting a client certificate for the chosen B<ssl>, overriding the
  25 setting valid for B<ssl>'s SSL_CTX object.
  26
  27 SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the
  28 list of CAs sent to the client when requesting a client certificate for
  29 B<ctx>.
  30
  31 SSL_add_client_CA() adds the CA name extracted from B<cacert> to the
  32 list of CAs sent to the client when requesting a client certificate for
  33 the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object.
  34
  35 =head1 NOTES
  36
  37 These functions are similar to L<SSL_CTX_set0_CA_list(3)> and similar functions
  38 but only have an effect on the server side. These functions are present for
  39 backwards compatibility. L<SSL_CTX_set0_CA_list(3)> and similar functions should
  40 be used in preference.
  41
  42 When a TLS/SSL server requests a client certificate (see
  43 B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which
  44 it will accept certificates, to the client.
  45
  46 This list must explicitly be set using SSL_CTX_set_client_CA_list() for
  47 B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list
  48 specified overrides the previous setting. The CAs listed do not become
  49 trusted (B<list> only contains the names, not the complete certificates); use
  50 L<SSL_CTX_load_verify_locations(3)>
  51 to additionally load them for verification.
  52
  53 If the list of acceptable CAs is compiled in a file, the
  54 L<SSL_load_client_CA_file(3)>
  55 function can be used to help importing the necessary data.
  56
  57 SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional
  58 items the list of client CAs. If no list was specified before using
  59 SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client
  60 CA list for B<ctx> or B<ssl> (as appropriate) is opened.
  61
  62 These functions are only useful for TLS/SSL servers.
  63
  64 =head1 RETURN VALUES
  65
  66 SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
  67 diagnostic information.
  68
  69 SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
  70 values:
  71
  72 =over 4
  73
  74 =item Z<>0
  75
  76 A failure while manipulating the STACK_OF(X509_NAME) object occurred or
  77 the X509_NAME could not be extracted from B<cacert>. Check the error stack
  78 to find out the reason.
  79
  80 =item Z<>1
  81
  82 The operation succeeded.
  83
  84 =back
  85
  86 =head1 EXAMPLES
  87
  88 Scan all certificates in B<CAfile> and list them as acceptable CAs:
  89
  90  SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
  91
  92 =head1 SEE ALSO
  93
  94 L<ssl(7)>,
  95 L<SSL_get_client_CA_list(3)>,
  96 L<SSL_load_client_CA_file(3)>,
  97 L<SSL_CTX_load_verify_locations(3)>
  98
  99 =head1 COPYRIGHT
 100
 101 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
 102
 103 Licensed under the OpenSSL license (the "License").  You may not use
 104 this file except in compliance with the License.  You can obtain a copy
 105 in the file LICENSE in the source distribution or at
 106 L<https://www.openssl.org/source/license.html>.
 107
 108 =cut