SSL_CTX_set_client_CA_list.pod 3.2 KB

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