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 8e6ecfa709fe06f0488f94649d186e92fa750656..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,7 +124,7 @@ L<X509_STORE_get0_param(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
 
 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