evp_rand: documentation

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

diff --git a/doc/man3/X509_STORE_add_cert.pod b/doc/man3/X509_STORE_add_cert.pod
index 4c80153f6fc411533c8feb4702c982f4c901dfaf..ce50e368e717501f31cff12e4653f52072682d87 100644 (file)
--- a/doc/man3/X509_STORE_add_cert.pod
+++ b/doc/man3/X509_STORE_add_cert.pod
@@ -2,16 +2,21 @@
 
 =head1 NAME
 
+X509_STORE,
 X509_STORE_add_cert, X509_STORE_add_crl, X509_STORE_set_depth,
 X509_STORE_set_flags, X509_STORE_set_purpose, X509_STORE_set_trust,
-X509_STORE_load_locations,
-X509_STORE_set_default_paths
+X509_STORE_add_lookup,
+X509_STORE_load_file, X509_STORE_load_path, X509_STORE_load_store,
+X509_STORE_set_default_paths,
+X509_STORE_load_locations
 - X509_STORE manipulation
 
 =head1 SYNOPSIS
 
  #include <openssl/x509_vfy.h>
 
+ typedef x509_store_st X509_STORE;
+
  int X509_STORE_add_cert(X509_STORE *ctx, X509 *x);
  int X509_STORE_add_crl(X509_STORE *ctx, X509_CRL *x);
  int X509_STORE_set_depth(X509_STORE *store, int depth);
@@ -19,9 +24,16 @@ X509_STORE_set_default_paths
  int X509_STORE_set_purpose(X509_STORE *ctx, int purpose);
  int X509_STORE_set_trust(X509_STORE *ctx, int trust);
 
+ X509_LOOKUP *X509_STORE_add_lookup(X509_STORE *store,
+                                    X509_LOOKUP_METHOD *meth);
+
+ int X509_STORE_set_default_paths(X509_STORE *ctx);
+ int X509_STORE_load_file(X509_STORE *ctx, const char *file);
+ int X509_STORE_load_path(X509_STORE *ctx, const char *dir);
+ int X509_STORE_load_store(X509_STORE *ctx, const char *uri);
+
  int X509_STORE_load_locations(X509_STORE *ctx,
                                const char *file, const char *dir);
- int X509_STORE_set_default_paths(X509_STORE *ctx);
 
 =head1 DESCRIPTION
 
@@ -55,7 +67,9 @@ operate on pointers to B<X509> objects, though.
 
 X509_STORE_add_cert() and X509_STORE_add_crl() add the respective object
 to the B<X509_STORE>'s local storage.  Untrusted objects should not be
-added in this way.
+added in this way.  The added object's reference count is incremented by one,
+hence the caller retains ownership of the object and needs to free it when it
+is no longer needed.
 
 X509_STORE_set_depth(), X509_STORE_set_flags(), X509_STORE_set_purpose(),
 X509_STORE_set_trust(), and X509_STORE_set1_param() set the default values
@@ -63,11 +77,26 @@ for the corresponding values used in certificate chain validation.  Their
 behavior is documented in the corresponding B<X509_VERIFY_PARAM> manual
 pages, e.g., L<X509_VERIFY_PARAM_set_depth(3)>.
 
-X509_STORE_load_locations() loads trusted certificate(s) into an
-B<X509_STORE> from a given file and/or directory path.  It is permitted
-to specify just a file, just a directory, or both paths.  The certificates
-in the directory must be in hashed form, as documented in
-L<X509_LOOKUP_hash_dir(3)>.
+X509_STORE_add_lookup() finds or creates a L<X509_LOOKUP(3)> with the
+L<X509_LOOKUP_METHOD(3)> I<meth> and adds it to the B<X509_STORE>
+I<store>.  This also associates the B<X509_STORE> with the lookup, so
+B<X509_LOOKUP> functions can look up objects in that store.
+
+X509_STORE_load_file() loads trusted certificate(s) into an
+B<X509_STORE> from a given file.
+
+X509_STORE_load_path() loads trusted certificate(s) into an
+B<X509_STORE> from a given directory path.
+The certificates in the directory must be in hashed form, as
+documented in L<X509_LOOKUP_hash_dir(3)>.
+
+X509_STORE_load_store() loads trusted certificate(s) into an
+B<X509_STORE> from a store at a given URI.
+
+X509_STORE_load_locations() combines X509_STORE_load_file() and
+X509_STORE_load_dir() for a given file and/or directory path.
+It is permitted to specify just a file, just a directory, or both
+paths.
 
 X509_STORE_set_default_paths() is somewhat misnamed, in that it does not
 set what default paths should be used for loading certificates.  Instead,
@@ -78,8 +107,13 @@ paths.
 
 X509_STORE_add_cert(), X509_STORE_add_crl(), X509_STORE_set_depth(),
 X509_STORE_set_flags(), X509_STORE_set_purpose(),
-X509_STORE_set_trust(), X509_STORE_load_locations(), and
-X509_STORE_set_default_paths() return 1 on success or 0 on failure.
+X509_STORE_set_trust(), X509_STORE_load_file(),
+X509_STORE_load_path(), X509_STORE_load_store(),
+X509_STORE_load_locations(), and X509_STORE_set_default_paths() return
+1 on success or 0 on failure.
+
+X509_STORE_add_lookup() returns the found or created
+L<X509_LOOKUP(3)>, or NULL on error.
 
 =head1 SEE ALSO
 
@@ -90,9 +124,9 @@ L<X509_STORE_get0_param(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-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>.