Rename OSSL_SERIALIZER / OSSL_DESERIALIZER to OSSL_ENCODE / OSSL_DECODE

[openssl.git] / doc / man3 / SSL_load_client_CA_file.pod

diff --git a/doc/man3/SSL_load_client_CA_file.pod b/doc/man3/SSL_load_client_CA_file.pod
index cc6a19cdea9043276503a3380aba007c7d62b58f..c3f0cd80f96c427096670a2966eb1d71365f1877 100644 (file)
--- a/doc/man3/SSL_load_client_CA_file.pod
+++ b/doc/man3/SSL_load_client_CA_file.pod
@@ -2,18 +2,47 @@
 
 =head1 NAME
 
-SSL_load_client_CA_file - load certificate names from file
+SSL_load_client_CA_file_with_libctx, SSL_load_client_CA_file,
+SSL_add_file_cert_subjects_to_stack,
+SSL_add_dir_cert_subjects_to_stack,
+SSL_add_store_cert_subjects_to_stack
+- load certificate names
 
 =head1 SYNOPSIS
 
  #include <openssl/ssl.h>
 
+ STACK_OF(X509_NAME) *SSL_load_client_CA_file_with_libctx(const char *file,
+                                                          OPENSSL_CTX *libctx,
+                                                          const char *propq);
  STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file);
 
+ int SSL_add_file_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
+                                         const char *file);
+ int SSL_add_dir_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
+                                        const char *dir);
+ int SSL_add_store_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
+                                          const char *store);
+
 =head1 DESCRIPTION
 
-SSL_load_client_CA_file() reads certificates from B<file> and returns
-a STACK_OF(X509_NAME) with the subject names found.
+SSL_load_client_CA_file_with_libctx() reads certificates from I<file> and returns
+a STACK_OF(X509_NAME) with the subject names found. The library context I<libctx>
+and property query <propq> are used when fetching algorithms from providers.
+
+SSL_load_client_CA_file() is similar to SSL_load_client_CA_file_with_libctx()
+but uses NULL for the library context I<libctx> and property query <propq>.
+
+SSL_add_file_cert_subjects_to_stack() reads certificates from I<file>,
+and adds their subject name to the already existing I<stack>.
+
+SSL_add_dir_cert_subjects_to_stack() reads certificates from every
+file in the directory I<dir>, and adds their subject name to the
+already existing I<stack>.
+
+SSL_add_store_cert_subjects_to_stack() loads certificates from the
+I<store> URI, and adds their subject name to the already existing
+I<stack>.
 
 =head1 NOTES
 
@@ -23,21 +52,6 @@ the specific usage as support function for
 L<SSL_CTX_set_client_CA_list(3)>,
 it is not limited to CA certificates.
 
-=head1 EXAMPLES
-
-Load names of CAs from file and use it as a client CA list:
-
- SSL_CTX *ctx;
- STACK_OF(X509_NAME) *cert_names;
-
- ...
- cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
- if (cert_names != NULL)
-   SSL_CTX_set_client_CA_list(ctx, cert_names);
- else
-   error_handling();
- ...
-
 =head1 RETURN VALUES
 
 The following return values can occur:
@@ -54,16 +68,37 @@ Pointer to the subject names of the successfully read certificates.
 
 =back
 
+=head1 EXAMPLES
+
+Load names of CAs from file and use it as a client CA list:
+
+ SSL_CTX *ctx;
+ STACK_OF(X509_NAME) *cert_names;
+
+ ...
+ cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
+ if (cert_names != NULL)
+     SSL_CTX_set_client_CA_list(ctx, cert_names);
+ else
+     /* error */
+ ...
+
 =head1 SEE ALSO
 
-L<ssl(3)>,
+L<ssl(7)>,
+L<ossl_store(7)>,
 L<SSL_CTX_set_client_CA_list(3)>
 
+=head1 HISTORY
+
+SSL_load_client_CA_file_with_libctx() and SSL_add_store_cert_subjects_to_stack()
+were added in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.