doc/man3/SSL_CTX_set0_CA_list.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_set0_CA_list, SSL_CTX_set0_CA_list, SSL_get0_CA_list,
   6 SSL_CTX_get0_CA_list, SSL_add1_CA_list, SSL_CTX_add1_CA_list,
   7 SSL_get0_peer_CA_list - get or set CA list
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/ssl.h>
  12
  13  void SSL_CTX_set0_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *name_list);
  14  void SSL_set0_CA_list(SSL *s, STACK_OF(X509_NAME) *name_list);
  15  const STACK_OF(X509_NAME) *SSL_CTX_get0_CA_list(const SSL_CTX *ctx);
  16  const STACK_OF(X509_NAME) *SSL_get0_CA_list(const SSL *s);
  17  int SSL_CTX_add1_CA_list(SSL_CTX *ctx, const X509 *x);
  18  int SSL_add1_CA_list(SSL *ssl, const X509 *x);
  19
  20  const STACK_OF(X509_NAME) *SSL_get0_peer_CA_list(const SSL *s);
  21
  22 =head1 DESCRIPTION
  23
  24 SSL_CTX_set0_CA_list() sets the list of CAs to be sent to the peer to
  25 B<name_list>. Ownership of B<name_list> is transferred to B<ctx> and
  26 it should not be freed by the caller.
  27
  28 SSL_set0_CA_list() sets the list of CAs to be sent to the peer to B<name_list>
  29 overriding any list set in the parent B<SSL_CTX> of B<s>. Ownership of
  30 B<name_list> is transferred to B<s> and it should not be freed by the caller.
  31
  32 SSL_CTX_get0_CA_list() retrieves any previously set list of CAs set for
  33 B<ctx>.
  34
  35 SSL_CTX_get0_CA_list() retrieves any previously set list of CAs set for
  36 B<s> or if none are set the list from the parent B<SSL_CTX> is retrieved.
  37
  38 SSL_CTX_add1_CA_list() appends the CA subject name extracted from B<x> to the
  39 list of CAs sent to peer for B<ctx>.
  40
  41 SSL_add1_CA_list() appends the CA subject name extracted from B<x> to the
  42 list of CAs sent to the peer for B<s>, overriding the setting in the parent
  43 B<SSL_CTX>.
  44
  45 SSL_get0_peer_CA_list() retrieves the list of CA names (if any) the peer
  46 has sent.
  47
  48 =head1 NOTES
  49
  50 These functions are generalised versions of the client authentication
  51 CA list functions such as L<SSL_CTX_set_client_CA_list(3)>.
  52
  53 For TLS versions before 1.3 the list of CA names is only sent from the server
  54 to client when requesting a client certificate. So any list of CA names set
  55 is never sent from client to server and the list of CA names retrieved by
  56 SSL_get0_peer_CA_list() is always B<NULL>.
  57
  58 For TLS 1.3 the list of CA names is sent using the B<certificate_authorities>
  59 extension and will be sent by a client (in the ClientHello message) or by
  60 a server (when requesting a certificate).
  61
  62 =head1 RETURN VALUES
  63
  64 SSL_CTX_set0_CA_list() and SSL_set0_CA_list() do not return a value.
  65
  66 SSL_CTX_get0_CA_list() and SSL_get0_CA_list() return a stack of CA names
  67 or B<NULL> is no CA names are set.
  68
  69 SSL_CTX_add1_CA_list() and SSL_add1_CA_list() return 1 for success and 0
  70 for failure.
  71
  72 SSL_get0_peer_CA_list() returns a stack of CA names sent by the peer or
  73 B<NULL> or an empty stack if no list was sent.
  74
  75 =back
  76
  77 =head1 SEE ALSO
  78
  79 L<ssl(7)>,
  80 L<SSL_CTX_set_client_CA_list(3)>,
  81 L<SSL_get_client_CA_list(3)>,
  82 L<SSL_load_client_CA_file(3)>,
  83 L<SSL_CTX_load_verify_locations(3)>
  84
  85 =head1 COPYRIGHT
  86
  87 Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
  88
  89 Licensed under the OpenSSL license (the "License").  You may not use
  90 this file except in compliance with the License.  You can obtain a copy
  91 in the file LICENSE in the source distribution or at
  92 L<https://www.openssl.org/source/license.html>.
  93
  94 =cut