Add X509 related libctx changes.

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

diff --git a/doc/man3/X509_LOOKUP_hash_dir.pod b/doc/man3/X509_LOOKUP_hash_dir.pod
index 83703e26928c37fcd3fc9f72a77d50506e7dc2a7..7077b9b59eec39277251dbaee3a294a48b34826c 100644 (file)
--- a/doc/man3/X509_LOOKUP_hash_dir.pod
+++ b/doc/man3/X509_LOOKUP_hash_dir.pod
@@ -2,11 +2,11 @@
 
 =head1 NAME
 
-X509_LOOKUP_hash_dir, X509_LOOKUP_file,
-X509_load_cert_file,
+X509_LOOKUP_hash_dir, X509_LOOKUP_file, X509_LOOKUP_store,
+X509_load_cert_file_with_libctx, X509_load_cert_file,
 X509_load_crl_file,
-X509_load_cert_crl_file - Default OpenSSL certificate
-lookup methods
+X509_load_cert_crl_file_with_libctx, X509_load_cert_crl_file
+- Default OpenSSL certificate lookup methods
 
 =head1 SYNOPSIS
 
@@ -14,9 +14,16 @@ lookup methods
 
  X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void);
  X509_LOOKUP_METHOD *X509_LOOKUP_file(void);
+ X509_LOOKUP_METHOD *X509_LOOKUP_store(void);
 
+ int X509_load_cert_file_with_libctx(X509_LOOKUP *ctx, const char *file,
+                                     int type, OPENSSL_CTX *libctx,
+                                     const char *propq);
  int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type);
  int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type);
+ int X509_load_cert_crl_file_with_libctx(X509_LOOKUP *ctx, const char *file,
+                                         int type, OPENSSL_CTX *libctx,
+                                         const char *propq);
  int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type);
 
 =head1 DESCRIPTION
@@ -80,12 +87,12 @@ upon each lookup, so that newer CRLs are as soon as they appear in
 the directory.
 
 The directory should contain one certificate or CRL per file in PEM format,
-with a file name of the form I<hash>.I<N> for a certificate, or
+with a filename of the form I<hash>.I<N> for a certificate, or
 I<hash>.B<r>I<N> for a CRL.
 The I<hash> is the value returned by the L<X509_NAME_hash(3)> function applied
 to the subject name for certificates or issuer name for CRLs.
-The hash can also be obtained via the B<-hash> option of the L<x509(1)> or
-L<crl(1)> commands.
+The hash can also be obtained via the B<-hash> option of the
+L<openssl-x509(1)> or L<openssl-crl(1)> commands.
 
 The .I<N> or .B<r>I<N> suffix is a sequence number that starts at zero, and is
 incremented consecutively for each certificate or CRL with the same I<hash>
@@ -108,8 +115,30 @@ Note that the hash algorithm used for subject name hashing changed in OpenSSL
 1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL
 0.9.8 to 1.0.0.
 
-OpenSSL includes a L<rehash(1)> utility which creates symlinks with correct
-hashed names for all files with .pem suffix in a given directory.
+OpenSSL includes a L<openssl-rehash(1)> utility which creates symlinks with
+hashed names for all files with F<.pem> suffix in a given directory.
+
+=head2 OSSL_STORE Method
+
+B<X509_LOOKUP_store> is a method that allows access to any store of
+certificates and CRLs through any loader supported by
+L<ossl_store(7)>.
+It works with the help of URIs, which can be direct references to
+certificates or CRLs, but can also be references to catalogues of such
+objects (that behave like directories).
+
+This method overlaps the L</File Method> and L</Hashed Directory Method>
+because of the 'file:' scheme loader.
+It does no caching of its own, but can use a caching L<ossl_store(7)>
+loader, and therefore depends on the loader's capability.
+
+=head1 RETURN VALUES
+
+X509_LOOKUP_hash_dir(), X509_LOOKUP_file() and X509_LOOKUP_store()
+always return a valid B<X509_LOOKUP_METHOD> structure.
+
+X509_load_cert_file(), X509_load_crl_file() and X509_load_cert_crl_file() return
+the number of loaded objects or 0 on error.
 
 =head1 SEE ALSO
 
@@ -117,12 +146,20 @@ L<PEM_read_PrivateKey(3)>,
 L<X509_STORE_load_locations(3)>,
 L<X509_store_add_lookup(3)>,
 L<SSL_CTX_load_verify_locations(3)>,
+L<X509_LOOKUP_meth_new(3)>,
+L<ossl_store(7)>
+
+=head1 HISTORY
+
+The functions X509_load_cert_file_with_libctx(),
+X509_load_cert_crl_file_with_libctx() and X509_LOOKUP_store() were added in
+OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-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>.