Document X509_get_default_cert_dir_env(3)

and X509_get_default_cert_file_env(3).

LibreSSL itself does not call getenv(3), but a few application programs
including epic5, fetchmail, fossil, slic3r call these functions, so in
case programmers find them in existing code, telling them what they do
seems useful.

1 files changed, 35 insertions, 8 deletions

diff --git a/src/lib/libcrypto/man/X509_LOOKUP_new.3 b/src/lib/libcrypto/man/X509_LOOKUP_new.3
index 2386e65de9..653ab6ca62 100644
--- a/src/lib/libcrypto/man/X509_LOOKUP_new.3
+++ b/src/lib/libcrypto/man/X509_LOOKUP_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_LOOKUP_new.3,v 1.2 2021/08/02 16:29:27 schwarze Exp $
+.\" $OpenBSD: X509_LOOKUP_new.3,v 1.3 2021/08/03 19:47:39 schwarze Exp $
 .\"
 .\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: August 2 2021 $
+.Dd $Mdocdate: August 3 2021 $
 .Dt X509_LOOKUP_NEW 3
 .Os
 .Sh NAME
@@ -31,7 +31,9 @@
 .Nm X509_LOOKUP_by_fingerprint ,
 .Nm X509_LOOKUP_by_alias ,
 .Nm X509_get_default_cert_dir ,
-.Nm X509_get_default_cert_file
+.Nm X509_get_default_cert_file ,
+.Nm X509_get_default_cert_dir_env ,
+.Nm X509_get_default_cert_file_env
 .Nd certificate lookup object
 .Sh SYNOPSIS
 .In openssl/x509_vfy.h
@@ -105,6 +107,10 @@
 .Fn X509_get_default_cert_dir void
 .Ft const char *
 .Fn X509_get_default_cert_file void
+.Ft const char *
+.Fn X509_get_default_cert_dir_env void
+.Ft const char *
+.Fn X509_get_default_cert_file_env void
 .Sh DESCRIPTION
 .Fn X509_LOOKUP_new
 allocates a new, empty
@@ -410,10 +416,29 @@ objects.
 .Fn X509_get_default_cert_dir
 returns a pointer to the constant string
 .Qq /etc/ssl/certs ,
-and
 .Fn X509_get_default_cert_file
-to the constant string
-.Qq /etc/ssl/certs.pem .
+to
+.Qq /etc/ssl/certs.pem ,
+.Fn X509_get_default_cert_dir_env
+to
+.Qq SSL_CERT_DIR ,
+and
+.Fn X509_get_default_cert_file_env
+to
+.Qq SSL_CERT_FILE .
+.Sh ENVIRONMENT
+For reasons of security and simplicity,
+LibreSSL ignores the environment variables
+.Ev SSL_CERT_DIR
+and
+.Ev SSL_CERT_FILE ,
+but other library implementations may use their contents instead
+of the standard locations for trusted certificates, and a few
+third-party application programs also inspect these variables
+directly and may pass their values to
+.Fn X509_LOOKUP_add_dir
+and
+.Fn X509_LOOKUP_load_file .
 .Sh FILES
 .Bl -tag -width /etc/ssl/certs.pem -compact
 .It Pa /etc/ssl/certs/
@@ -519,9 +544,11 @@ causes failure but provides no diagnostics.
 .Xr X509_STORE_add_cert 3 ,
 .Xr X509_STORE_get_by_subject 3
 .Sh HISTORY
-.Fn X509_get_default_cert_dir
+.Fn X509_get_default_cert_dir ,
+.Fn X509_get_default_cert_file ,
+.Fn X509_get_default_cert_dir_env ,
 and
-.Fn X509_get_default_cert_file
+.Fn X509_get_default_cert_file_env
 first appeared in SSLeay 0.4.1 and have been available since
 .Ox 2.4 .
 .Pp