1=pod
2
3=head1 NAME
4
5X509_get_default_cert_file, X509_get_default_cert_file_env,
6X509_get_default_cert_dir, X509_get_default_cert_dir_env -
7retrieve default locations for trusted CA certificates
8
9=head1 SYNOPSIS
10
11 #include <openssl/x509.h>
12
13 const char *X509_get_default_cert_file(void);
14 const char *X509_get_default_cert_dir(void);
15
16 const char *X509_get_default_cert_file_env(void);
17 const char *X509_get_default_cert_dir_env(void);
18
19=head1 DESCRIPTION
20
21The X509_get_default_cert_file() function returns the default path
22to a file containing trusted CA certificates. OpenSSL will use this as
23the default path when it is asked to load trusted CA certificates
24from a file and no other path is specified. If the file exists, CA certificates
25are loaded from the file.
26
27The X509_get_default_cert_dir() function returns a default delimeter-separated
28list of paths to a directories containing trusted CA certificates named in the
29hashed format. OpenSSL will use this as the default list of paths when it is
30asked to load trusted CA certificates from a directory and no other path is
31specified. If a given directory in the list exists, OpenSSL attempts to lookup
32CA certificates in this directory by calculating a filename based on a hash of
33the certificate's subject name.
34
35X509_get_default_cert_file_env() returns an environment variable name which is
36recommended to specify a nondefault value to be used instead of the value
37returned by X509_get_default_cert_file(). The value returned by the latter
38function is not affected by these environment variables; you must check for this
39environment variable yourself, using this function to retrieve the correct
40environment variable name. If an environment variable is not set, the value
41returned by the X509_get_default_cert_file() should be used.
42
43X509_get_default_cert_dir_env() returns the environment variable name which is
44recommended to specify a nondefault value to be used instead of the value
45returned by X509_get_default_cert_dir(). The value specified by this environment
46variable can also be a store URI (but see BUGS below).
47
48=head1 BUGS
49
50By default (for example, when L<X509_STORE_set_default_paths(3)> is used), the
51environment variable name returned by X509_get_default_cert_dir_env() is
52interpreted both as a delimiter-separated list of paths, and as a store URI.
53This is ambiguous. For example, specifying a value of B<"file:///etc/certs">
54would cause instantiation of the "file" store provided as part of the default
55provider, but would also cause an L<X509_LOOKUP_hash_dir(3)> instance to look
56for certificates in the directory B<"file"> (relative to the current working
57directory) and the directory B<"///etc/certs">. This can be avoided by avoiding
58use of the environment variable mechanism and using other methods to construct
59X509_LOOKUP instances.
60
61=head1 RETURN VALUES
62
63These functions return pointers to constant strings with static storage
64duration.
65
66=head1 SEE ALSO
67
68L<X509_LOOKUP(3)>,
69L<SSL_CTX_set_default_verify_file(3)>,
70L<SSL_CTX_set_default_verify_dir(3)>,
71L<SSL_CTX_set_default_verify_store(3)>,
72L<SSL_CTX_load_verify_file(3)>,
73L<SSL_CTX_load_verify_dir(3)>,
74L<SSL_CTX_load_verify_store(3)>,
75L<SSL_CTX_load_verify_locations(3)>
76
77=head1 COPYRIGHT
78
79Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
80
81Licensed under the Apache License 2.0 (the "License").  You may not use
82this file except in compliance with the License.  You can obtain a copy
83in the file LICENSE in the source distribution or at
84L<https://www.openssl.org/source/license.html>.
85
86=cut
87