diff options
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.3 | 161 |
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 | ||
18 | specifies the locations for | ||
19 | .Fa ctx , | ||
20 | at which CA certificates for verification purposes are located. | ||
21 | The certificates available via | ||
22 | .Fa CAfile | ||
23 | and | ||
24 | .Fa CApath | ||
25 | are trusted. | ||
26 | .Sh NOTES | ||
27 | If | ||
28 | .Fa CAfile | ||
29 | is not | ||
30 | .Dv NULL , | ||
31 | it points to a file of CA certificates in PEM format. | ||
32 | The 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 | ||
38 | Before, between, and after the certificates arbitrary text is allowed which can | ||
39 | be used, e.g., for descriptions of the certificates. | ||
40 | .Pp | ||
41 | The | ||
42 | .Fa CAfile | ||
43 | is processed on execution of the | ||
44 | .Fn SSL_CTX_load_verify_locations | ||
45 | function. | ||
46 | .Pp | ||
47 | If | ||
48 | .Fa CApath | ||
49 | is not NULL, it points to a directory containing CA certificates in PEM format. | ||
50 | The files each contain one CA certificate. | ||
51 | The files are looked up by the CA subject name hash value, | ||
52 | which must hence be available. | ||
53 | If more than one CA certificate with the same name hash value exist, | ||
54 | the extension must be different (e.g., | ||
55 | .Pa 9d66eef0.0 , | ||
56 | .Pa 9d66eef0.1 , | ||
57 | etc.). | ||
58 | The search is performed in the ordering of the extension number, | ||
59 | regardless of other properties of the certificates. | ||
60 | .Pp | ||
61 | The certificates in | ||
62 | .Fa CApath | ||
63 | are only looked up when required, e.g., when building the certificate chain or | ||
64 | when actually performing the verification of a peer certificate. | ||
65 | .Pp | ||
66 | When looking up CA certificates, the OpenSSL library will first search the | ||
67 | certificates in | ||
68 | .Fa CAfile , | ||
69 | then those in | ||
70 | .Fa CApath . | ||
71 | Certificate matching is done based on the subject name, the key identifier (if | ||
72 | present), and the serial number as taken from the certificate to be verified. | ||
73 | If these data do not match, the next certificate will be tried. | ||
74 | If a first certificate matching the parameters is found, | ||
75 | the verification process will be performed; | ||
76 | no other certificates for the same parameters will be searched in case of | ||
77 | failure. | ||
78 | .Pp | ||
79 | In server mode, when requesting a client certificate, the server must send | ||
80 | the list of CAs of which it will accept client certificates. | ||
81 | This list is not influenced by the contents of | ||
82 | .Fa CAfile | ||
83 | or | ||
84 | .Fa CApath | ||
85 | and must explicitly be set using the | ||
86 | .Xr SSL_CTX_set_client_CA_list 3 | ||
87 | family of functions. | ||
88 | .Pp | ||
89 | When building its own certificate chain, an OpenSSL client/server will try to | ||
90 | fill in missing certificates from | ||
91 | .Fa CAfile Ns / Fa CApath , | ||
92 | if the | ||
93 | certificate chain was not explicitly specified (see | ||
94 | .Xr SSL_CTX_add_extra_chain_cert 3 | ||
95 | and | ||
96 | .Xr SSL_CTX_use_certificate 3 ) . | ||
97 | .Sh WARNINGS | ||
98 | If several CA certificates matching the name, key identifier, and serial | ||
99 | number condition are available, only the first one will be examined. | ||
100 | This may lead to unexpected results if the same CA certificate is available | ||
101 | with different expiration dates. | ||
102 | If a | ||
103 | .Dq certificate expired | ||
104 | verification error occurs, no other certificate will be searched. | ||
105 | Make sure to not have expired certificates mixed with valid ones. | ||
106 | .Sh RETURN VALUES | ||
107 | The following return values can occur: | ||
108 | .Bl -tag -width Ds | ||
109 | .It 0 | ||
110 | The operation failed because | ||
111 | .Fa CAfile | ||
112 | and | ||
113 | .Fa CApath | ||
114 | are | ||
115 | .Dv NULL | ||
116 | or the processing at one of the locations specified failed. | ||
117 | Check the error stack to find out the reason. | ||
118 | .It 1 | ||
119 | The operation succeeded. | ||
120 | .El | ||
121 | .Sh EXAMPLES | ||
122 | Generate 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 | ||
128 | rm CAfile.pem | ||
129 | for i in ca1.pem ca2.pem ca3.pem; do | ||
130 | openssl x509 -in $i -text >> CAfile.pem | ||
131 | done | ||
132 | .Ed | ||
133 | .Pp | ||
134 | Prepare the directory /some/where/certs containing several CA certificates | ||
135 | for 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 | ||