summaryrefslogtreecommitdiff
path: root/src/lib/libssl/doc/SSL_CTX_load_verify_locations.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libssl/doc/SSL_CTX_load_verify_locations.3')
-rw-r--r--src/lib/libssl/doc/SSL_CTX_load_verify_locations.3161
1 files changed, 0 insertions, 161 deletions
diff --git a/src/lib/libssl/doc/SSL_CTX_load_verify_locations.3 b/src/lib/libssl/doc/SSL_CTX_load_verify_locations.3
deleted file mode 100644
index 09884db5da..0000000000
--- a/src/lib/libssl/doc/SSL_CTX_load_verify_locations.3
+++ /dev/null
@@ -1,161 +0,0 @@
1.\"
2.\" $OpenBSD: SSL_CTX_load_verify_locations.3,v 1.2 2014/12/02 14:11:01 jmc Exp $
3.\"
4.Dd $Mdocdate: December 2 2014 $
5.Dt SSL_CTX_LOAD_VERIFY_LOCATIONS 3
6.Os
7.Sh NAME
8.Nm SSL_CTX_load_verify_locations
9.Nd set default locations for trusted CA certificates
10.Sh SYNOPSIS
11.In openssl/ssl.h
12.Ft int
13.Fo SSL_CTX_load_verify_locations
14.Fa "SSL_CTX *ctx" "const char *CAfile" "const char *CApath"
15.Fc
16.Sh DESCRIPTION
17.Fn SSL_CTX_load_verify_locations
18specifies the locations for
19.Fa ctx ,
20at which CA certificates for verification purposes are located.
21The certificates available via
22.Fa CAfile
23and
24.Fa CApath
25are trusted.
26.Sh NOTES
27If
28.Fa CAfile
29is not
30.Dv NULL ,
31it points to a file of CA certificates in PEM format.
32The file can contain several CA certificates identified by sequences of:
33.Bd -literal
34 -----BEGIN CERTIFICATE-----
35 ... (CA certificate in base64 encoding) ...
36 -----END CERTIFICATE-----
37.Ed
38Before, between, and after the certificates arbitrary text is allowed which can
39be used, e.g., for descriptions of the certificates.
40.Pp
41The
42.Fa CAfile
43is processed on execution of the
44.Fn SSL_CTX_load_verify_locations
45function.
46.Pp
47If
48.Fa CApath
49is not NULL, it points to a directory containing CA certificates in PEM format.
50The files each contain one CA certificate.
51The files are looked up by the CA subject name hash value,
52which must hence be available.
53If more than one CA certificate with the same name hash value exist,
54the extension must be different (e.g.,
55.Pa 9d66eef0.0 ,
56.Pa 9d66eef0.1 ,
57etc.).
58The search is performed in the ordering of the extension number,
59regardless of other properties of the certificates.
60.Pp
61The certificates in
62.Fa CApath
63are only looked up when required, e.g., when building the certificate chain or
64when actually performing the verification of a peer certificate.
65.Pp
66When looking up CA certificates, the OpenSSL library will first search the
67certificates in
68.Fa CAfile ,
69then those in
70.Fa CApath .
71Certificate matching is done based on the subject name, the key identifier (if
72present), and the serial number as taken from the certificate to be verified.
73If these data do not match, the next certificate will be tried.
74If a first certificate matching the parameters is found,
75the verification process will be performed;
76no other certificates for the same parameters will be searched in case of
77failure.
78.Pp
79In server mode, when requesting a client certificate, the server must send
80the list of CAs of which it will accept client certificates.
81This list is not influenced by the contents of
82.Fa CAfile
83or
84.Fa CApath
85and must explicitly be set using the
86.Xr SSL_CTX_set_client_CA_list 3
87family of functions.
88.Pp
89When building its own certificate chain, an OpenSSL client/server will try to
90fill in missing certificates from
91.Fa CAfile Ns / Fa CApath ,
92if the
93certificate chain was not explicitly specified (see
94.Xr SSL_CTX_add_extra_chain_cert 3
95and
96.Xr SSL_CTX_use_certificate 3 ) .
97.Sh WARNINGS
98If several CA certificates matching the name, key identifier, and serial
99number condition are available, only the first one will be examined.
100This may lead to unexpected results if the same CA certificate is available
101with different expiration dates.
102If a
103.Dq certificate expired
104verification error occurs, no other certificate will be searched.
105Make sure to not have expired certificates mixed with valid ones.
106.Sh RETURN VALUES
107The following return values can occur:
108.Bl -tag -width Ds
109.It 0
110The operation failed because
111.Fa CAfile
112and
113.Fa CApath
114are
115.Dv NULL
116or the processing at one of the locations specified failed.
117Check the error stack to find out the reason.
118.It 1
119The operation succeeded.
120.El
121.Sh EXAMPLES
122Generate a CA certificate file with descriptive text from the CA certificates
123.Pa ca1.pem
124.Pa ca2.pem
125.Pa ca3.pem :
126.Bd -literal
127#!/bin/sh
128rm CAfile.pem
129for i in ca1.pem ca2.pem ca3.pem; do
130 openssl x509 -in $i -text >> CAfile.pem
131done
132.Ed
133.Pp
134Prepare the directory /some/where/certs containing several CA certificates
135for use as
136.Fa CApath :
137.Bd -literal
138$ cd /some/where/certs
139$ rm -f *.[0-9]* *.r[0-9]*
140$ for c in *.pem; do
141> [ "$c" = "*.pem" ] && continue
142> hash=$(openssl x509 -noout -hash -in "$c")
143> if egrep -q -- '-BEGIN( X509 | TRUSTED | )CERTIFICATE-' "$c"; then
144> suf=0
145> while [ -e $hash.$suf ]; do suf=$(( $suf + 1 )); done
146> ln -s "$c" $hash.$suf
147> fi
148> if egrep -q -- '-BEGIN X509 CRL-' "$c"; then
149> suf=0
150> while [ -e $hash.r$suf ]; do suf=$(( $suf + 1 )); done
151> ln -s "$c" $hash.r$suf
152> fi
153> done
154.Ed
155.Sh SEE ALSO
156.Xr ssl 3 ,
157.Xr SSL_CTX_add_extra_chain_cert 3 ,
158.Xr SSL_CTX_set_cert_store 3 ,
159.Xr SSL_CTX_set_client_CA_list 3 ,
160.Xr SSL_CTX_use_certificate 3 ,
161.Xr SSL_get_client_CA_list 3