From 849d91a62cede6787769389f40fc912db439bedb Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Fri, 8 Mar 2019 23:41:27 +0100 Subject: [PATCH] Document X509_LOOKUP_store Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/8442) --- doc/man3/X509_LOOKUP_hash_dir.pod | 28 ++++++++++++++++++---- doc/man3/X509_STORE_add_cert.pod | 39 +++++++++++++++++++++++-------- 2 files changed, 53 insertions(+), 14 deletions(-) diff --git a/doc/man3/X509_LOOKUP_hash_dir.pod b/doc/man3/X509_LOOKUP_hash_dir.pod index a9b837a308..30fbda8e03 100644 --- a/doc/man3/X509_LOOKUP_hash_dir.pod +++ b/doc/man3/X509_LOOKUP_hash_dir.pod @@ -2,7 +2,7 @@ =head1 NAME -X509_LOOKUP_hash_dir, X509_LOOKUP_file, +X509_LOOKUP_hash_dir, X509_LOOKUP_file, X509_LOOKUP_store, X509_load_cert_file, X509_load_crl_file, X509_load_cert_crl_file - Default OpenSSL certificate @@ -14,6 +14,7 @@ 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(X509_LOOKUP *ctx, const char *file, int type); int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type); @@ -111,10 +112,24 @@ Note that the hash algorithm used for subject name hashing changed in OpenSSL OpenSSL includes a L utility which creates symlinks with correct hashed names for all files with .pem suffix in a given directory. +=head2 OSSL_STORE Method + +B is a method that allows access to any store of +certificates and CRLs through any loader supported by +L. +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 and L +because of the 'file:' scheme loader. +It does no caching of its own, but can use a caching L +loader, and therefore depends on the loader's capability. + =head1 RETURN VALUES -X509_LOOKUP_hash_dir() and X509_LOOKUP_file() always return a valid -B structure. +X509_LOOKUP_hash_dir(), X509_LOOKUP_file() and X509_LOOKUP_store() +always return a valid B 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. @@ -126,10 +141,15 @@ L, L, L, L, +L + +=head1 HISTORY + +B was added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-2019 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 diff --git a/doc/man3/X509_STORE_add_cert.pod b/doc/man3/X509_STORE_add_cert.pod index c0940b96ed..dd3d389e22 100644 --- a/doc/man3/X509_STORE_add_cert.pod +++ b/doc/man3/X509_STORE_add_cert.pod @@ -4,8 +4,9 @@ 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_load_file, X509_STORE_load_path, X509_STORE_load_store, +X509_STORE_set_default_paths, +X509_STORE_load_locations - X509_STORE manipulation =head1 SYNOPSIS @@ -19,9 +20,15 @@ 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); + 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); + +Deprecated: + 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 @@ -65,11 +72,21 @@ for the corresponding values used in certificate chain validation. Their behavior is documented in the corresponding B manual pages, e.g., L. -X509_STORE_load_locations() loads trusted certificate(s) into an -B 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_STORE_load_file() loads trusted certificate(s) into an +B from a given file. + +X509_STORE_load_path() loads trusted certificate(s) into an +B from a given directory path. +The certificates in the directory must be in hashed form, as +documented in L. + +X509_STORE_load_store() loads trusted certificate(s) into an +B 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, @@ -80,8 +97,10 @@ 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. =head1 SEE ALSO -- 2.25.1