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 When a TLS/SSL server requests a client certificate (see
  38 B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which
  39 it will accept certificates, to the client.
  40
  41 This list must explicitly be set using SSL_CTX_set_client_CA_list() for
  42 B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list
  43 specified overrides the previous setting. The CAs listed do not become
  44 trusted (B<list> only contains the names, not the complete certificates); use
  45 L<SSL_CTX_load_verify_locations(3)>
  46 to additionally load them for verification.
  47
  48 If the list of acceptable CAs is compiled in a file, the
  49 L<SSL_load_client_CA_file(3)>
  50 function can be used to help importing the necessary data.
  51
  52 SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional
  53 items the list of client CAs. If no list was specified before using
  54 SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client
  55 CA list for B<ctx> or B<ssl> (as appropriate) is opened.
  56
  57 These functions are only useful for TLS/SSL servers.
  58
  59 =head1 RETURN VALUES
  60
  61 SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
  62 diagnostic information.
  63
  64 SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
  65 values:
  66
  67 =over 4
  68
  69 =item Z<>0
  70
  71 A failure while manipulating the STACK_OF(X509_NAME) object occurred or
  72 the X509_NAME could not be extracted from B<cacert>. Check the error stack
  73 to find out the reason.
  74
  75 =item Z<>1
  76
  77 The operation succeeded.
  78
  79 =back
  80
  81 =head1 EXAMPLES
  82
  83 Scan all certificates in B<CAfile> and list them as acceptable CAs:
  84
  85  SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
  86
  87 =head1 SEE ALSO
  88
  89 L<ssl(7)>,
  90 L<SSL_get_client_CA_list(3)>,
  91 L<SSL_load_client_CA_file(3)>,
  92 L<SSL_CTX_load_verify_locations(3)>
  93
  94 =head1 COPYRIGHT
  95
  96 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
  97
  98 Licensed under the OpenSSL license (the "License").  You may not use
  99 this file except in compliance with the License.  You can obtain a copy
 100 in the file LICENSE in the source distribution or at
 101 L<https://www.openssl.org/source/license.html>.
 102
 103 =cut