Update per latest manual pages after running 'man-update'.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_load_verify_locations.3
CommitLineData
a7d27d5a
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
a7d27d5a 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
a7d27d5a 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
a7d27d5a 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
a7d27d5a 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
a7d27d5a
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
a7d27d5a
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
a7d27d5a
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
a7d27d5a
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
a7d27d5a
JR
93.nr % 0
94.rr F
984263bc 95.\}
a7d27d5a
JR
96.TH SSL_CTX_load_verify_locations 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
a7d27d5a
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
a7d27d5a 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
a7d27d5a
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
a7d27d5a
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
a7d27d5a 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
a7d27d5a
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
a7d27d5a
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
a7d27d5a 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
a7d27d5a
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
a7d27d5a
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
a7d27d5a 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
a7d27d5a
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc 190.SH "NAME"
a7d27d5a 191SSL_CTX_load_verify_locations \- set default locations for trusted CA
984263bc
MD
192certificates
193.SH "SYNOPSIS"
a7d27d5a 194.PP
984263bc
MD
195.Vb 1
196\& #include <openssl/ssl.h>
197.Ve
198.Vb 2
199\& int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,
200\& const char *CApath);
201.Ve
202.SH "DESCRIPTION"
a7d27d5a
JR
203\fISSL_CTX_load_verify_locations()\fR specifies the locations for \fBctx\fR, at
204which CA certificates for verification purposes are located. The certificates
984263bc
MD
205available via \fBCAfile\fR and \fBCApath\fR are trusted.
206.SH "NOTES"
a7d27d5a
JR
207If \fBCAfile\fR is not NULL, it points to a file of CA certificates in PEM
208format. The file can contain several CA certificates identified by
984263bc
MD
209.PP
210.Vb 3
211\& -----BEGIN CERTIFICATE-----
212\& ... (CA certificate in base64 encoding) ...
213\& -----END CERTIFICATE-----
214.Ve
215sequences. Before, between, and after the certificates text is allowed
216which can be used e.g. for descriptions of the certificates.
217.PP
218The \fBCAfile\fR is processed on execution of the \fISSL_CTX_load_verify_locations()\fR
219function.
220.PP
a7d27d5a
JR
221If \fBCApath\fR is not NULL, it points to a directory containing CA certificates
222in PEM format. The files each contain one CA certificate. The files are
223looked up by the CA subject name hash value, which must hence be available.
224If more than one CA certificate with the same name hash value exist, the
984263bc
MD
225extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search
226is performed in the ordering of the extension number, regardless of other
227properties of the certificates.
228Use the \fBc_rehash\fR utility to create the necessary links.
229.PP
230The certificates in \fBCApath\fR are only looked up when required, e.g. when
231building the certificate chain or when actually performing the verification
232of a peer certificate.
233.PP
a7d27d5a 234When looking up CA certificates, the OpenSSL library will first search the
984263bc
MD
235certificates in \fBCAfile\fR, then those in \fBCApath\fR. Certificate matching
236is done based on the subject name, the key identifier (if present), and the
237serial number as taken from the certificate to be verified. If these data
238do not match, the next certificate will be tried. If a first certificate
239matching the parameters is found, the verification process will be performed;
240no other certificates for the same parameters will be searched in case of
241failure.
242.PP
243In server mode, when requesting a client certificate, the server must send
244the list of CAs of which it will accept client certificates. This list
245is not influenced by the contents of \fBCAfile\fR or \fBCApath\fR and must
246explicitly be set using the
247SSL_CTX_set_client_CA_list(3)
248family of functions.
249.PP
250When building its own certificate chain, an OpenSSL client/server will
251try to fill in missing certificates from \fBCAfile\fR/\fBCApath\fR, if the
252certificate chain was not explicitly specified (see
253SSL_CTX_add_extra_chain_cert(3),
254SSL_CTX_use_certificate(3).
255.SH "WARNINGS"
a7d27d5a 256If several CA certificates matching the name, key identifier, and serial
984263bc 257number condition are available, only the first one will be examined. This
a7d27d5a 258may lead to unexpected results if the same CA certificate is available
984263bc
MD
259with different expiration dates. If a \*(L"certificate expired\*(R" verification
260error occurs, no other certificate will be searched. Make sure to not
261have expired certificates mixed with valid ones.
262.SH "EXAMPLES"
a7d27d5a 263Generate a CA certificate file with descriptive text from the CA certificates
984263bc
MD
264ca1.pem ca2.pem ca3.pem:
265.PP
266.Vb 5
267\& #!/bin/sh
268\& rm CAfile.pem
269\& for i in ca1.pem ca2.pem ca3.pem ; do
270\& openssl x509 -in $i -text >> CAfile.pem
271\& done
272.Ve
a7d27d5a 273Prepare the directory /some/where/certs containing several CA certificates
984263bc
MD
274for use as \fBCApath\fR:
275.PP
276.Vb 2
277\& cd /some/where/certs
278\& c_rehash .
279.Ve
280.SH "RETURN VALUES"
984263bc
MD
281The following return values can occur:
282.Ip "0" 4
283The operation failed because \fBCAfile\fR and \fBCApath\fR are \s-1NULL\s0 or the
284processing at one of the locations specified failed. Check the error
285stack to find out the reason.
286.Ip "1" 4
984263bc
MD
287The operation succeeded.
288.SH "SEE ALSO"
984263bc
MD
289ssl(3),
290SSL_CTX_set_client_CA_list(3),
291SSL_get_client_CA_list(3),
292SSL_CTX_use_certificate(3),
293SSL_CTX_add_extra_chain_cert(3),
294SSL_CTX_set_cert_store(3)
a7d27d5a
JR
295
296.rn }` ''
297.IX Title "SSL_CTX_load_verify_locations 3"
298.IX Name "SSL_CTX_load_verify_locations - set default locations for trusted CA
299certificates"
300
301.IX Header "NAME"
302
303.IX Header "SYNOPSIS"
304
305.IX Header "DESCRIPTION"
306
307.IX Header "NOTES"
308
309.IX Header "WARNINGS"
310
311.IX Header "EXAMPLES"
312
313.IX Header "RETURN VALUES"
314
315.IX Item "0"
316
317.IX Item "1"
318
319.IX Header "SEE ALSO"
320