X509_get_default_cert_file.pod 3.5 KB

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