Add X509_STORE_get1_objects

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

diff --git a/doc/man3/X509_STORE_get0_param.pod b/doc/man3/X509_STORE_get0_param.pod
index 559c137285b83e0ad8e78b19aa8f5e80fae1fbfb..d9dfb1b656fea22e9935de9b7ac19b8e4f1ecaac 100644 (file)
--- a/doc/man3/X509_STORE_get0_param.pod
+++ b/doc/man3/X509_STORE_get0_param.pod
@@ -3,7 +3,7 @@
 =head1 NAME
 
 X509_STORE_get0_param, X509_STORE_set1_param,
-X509_STORE_get0_objects, X509_STORE_get1_all_certs
+X509_STORE_get1_objects, X509_STORE_get0_objects, X509_STORE_get1_all_certs
 - X509_STORE setter and getter functions
 
 =head1 SYNOPSIS
@@ -12,6 +12,7 @@ X509_STORE_get0_objects, X509_STORE_get1_all_certs
 
  X509_VERIFY_PARAM *X509_STORE_get0_param(const X509_STORE *xs);
  int X509_STORE_set1_param(X509_STORE *xs, const X509_VERIFY_PARAM *pm);
+ STACK_OF(X509_OBJECT) *X509_STORE_get1_objects(X509_STORE *xs);
  STACK_OF(X509_OBJECT) *X509_STORE_get0_objects(const X509_STORE *xs);
  STACK_OF(X509) *X509_STORE_get1_all_certs(X509_STORE *xs);
 
@@ -23,9 +24,15 @@ X509_STORE_get0_param() retrieves an internal pointer to the verification
 parameters for I<xs>. The returned pointer must not be freed by the
 calling application
 
+X509_STORE_get1_objects() returns a snapshot of all objects in the store's X509
+cache. The cache contains B<X509> and B<X509_CRL> objects. The caller is
+responsible for freeing the returned list.
+
 X509_STORE_get0_objects() retrieves an internal pointer to the store's
 X509 object cache. The cache contains B<X509> and B<X509_CRL> objects. The
-returned pointer must not be freed by the calling application.
+returned pointer must not be freed by the calling application. If the store is
+shared across multiple threads, it is not safe to use the result of this
+function. Use X509_STORE_get1_objects() instead, which avoids this problem.
 
 X509_STORE_get1_all_certs() returns a list of all certificates in the store.
 The caller is responsible for freeing the returned list.
@@ -37,6 +44,9 @@ B<X509_VERIFY_PARAM> structure.
 
 X509_STORE_set1_param() returns 1 for success and 0 for failure.
 
+X509_STORE_get1_objects() returns a pointer to a stack of the retrieved
+objects on success, else NULL.
+
 X509_STORE_get0_objects() returns a pointer to a stack of B<X509_OBJECT>.
 
 X509_STORE_get1_all_certs() returns a pointer to a stack of the retrieved
@@ -51,6 +61,7 @@ L<X509_STORE_new(3)>
 B<X509_STORE_get0_param> and B<X509_STORE_get0_objects> were added in
 OpenSSL 1.1.0.
 B<X509_STORE_get1_certs> was added in OpenSSL 3.0.
+B<X509_STORE_get1_objects> was added in OpenSSL 3.3.
 
 =head1 COPYRIGHT