Remove my local patch again, it was still not meant to be commited.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_client_CA_list.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_set_client_CA_list 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
MD
190.SH "NAME"
191SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
192SSL_add_client_CA \- set list of CAs sent to the client when requesting a
193client certificate
194.SH "SYNOPSIS"
a7d27d5a
JR
195.PP
196.Vb 6
984263bc 197\& #include <openssl/ssl.h>
a7d27d5a 198\&
984263bc
MD
199\& void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
200\& void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
201\& int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
202\& int SSL_add_client_CA(SSL *ssl, X509 *cacert);
203.Ve
204.SH "DESCRIPTION"
a7d27d5a 205\fISSL_CTX_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when
984263bc
MD
206requesting a client certificate for \fBctx\fR.
207.PP
a7d27d5a 208\fISSL_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when
984263bc 209requesting a client certificate for the chosen \fBssl\fR, overriding the
a7d27d5a 210setting valid for \fBssl\fR's SSL_CTX object.
984263bc 211.PP
a7d27d5a 212\fISSL_CTX_add_client_CA()\fR adds the CA name extracted from \fBcacert\fR to the
984263bc 213list of CAs sent to the client when requesting a client certificate for
a7d27d5a 214\fBctx\fR.
984263bc 215.PP
a7d27d5a 216\fISSL_add_client_CA()\fR adds the CA name extracted from \fBcacert\fR to the
984263bc 217list of CAs sent to the client when requesting a client certificate for
a7d27d5a 218the chosen \fBssl\fR, overriding the setting valid for \fBssl\fR's SSL_CTX object.
984263bc 219.SH "NOTES"
a7d27d5a
JR
220When a TLS/SSL server requests a client certificate (see
221\fBSSL_CTX_set_verify_options()\fR), it sends a list of CAs, for which
984263bc
MD
222it will accept certificates, to the client.
223.PP
224This list must explicitly be set using \fISSL_CTX_set_client_CA_list()\fR for
a7d27d5a 225\fBctx\fR and \fISSL_set_client_CA_list()\fR for the specific \fBssl\fR. The list
984263bc
MD
226specified overrides the previous setting. The CAs listed do not become
227trusted (\fBlist\fR only contains the names, not the complete certificates); use
228SSL_CTX_load_verify_locations(3)
229to additionally load them for verification.
230.PP
231If the list of acceptable CAs is compiled in a file, the
232SSL_load_client_CA_file(3)
233function can be used to help importing the necessary data.
234.PP
a7d27d5a 235\fISSL_CTX_add_client_CA()\fR and \fISSL_add_client_CA()\fR can be used to add additional
984263bc 236items the list of client CAs. If no list was specified before using
a7d27d5a
JR
237\fISSL_CTX_set_client_CA_list()\fR or \fISSL_set_client_CA_list()\fR, a new client
238CA list for \fBctx\fR or \fBssl\fR (as appropriate) is opened.
984263bc 239.PP
a7d27d5a 240These functions are only useful for TLS/SSL servers.
984263bc 241.SH "RETURN VALUES"
a7d27d5a 242\fISSL_CTX_set_client_CA_list()\fR and \fISSL_set_client_CA_list()\fR do not return
984263bc
MD
243diagnostic information.
244.PP
a7d27d5a 245\fISSL_CTX_add_client_CA()\fR and \fISSL_add_client_CA()\fR have the following return
984263bc
MD
246values:
247.Ip "1" 4
984263bc
MD
248The operation succeeded.
249.Ip "0" 4
a7d27d5a 250A failure while manipulating the \fI\s-1STACK_OF\s0\fR\|(X509_NAME) object occurred or
984263bc
MD
251the X509_NAME could not be extracted from \fBcacert\fR. Check the error stack
252to find out the reason.
253.SH "EXAMPLES"
984263bc
MD
254Scan all certificates in \fBCAfile\fR and list them as acceptable CAs:
255.PP
256.Vb 1
257\& SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(CAfile));
258.Ve
259.SH "SEE ALSO"
984263bc
MD
260ssl(3),
261SSL_get_client_CA_list(3),
262SSL_load_client_CA_file(3),
263SSL_CTX_load_verify_locations(3)
a7d27d5a
JR
264
265.rn }` ''
266.IX Title "SSL_CTX_set_client_CA_list 3"
267.IX Name "SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
268SSL_add_client_CA - set list of CAs sent to the client when requesting a
269client certificate"
270
271.IX Header "NAME"
272
273.IX Header "SYNOPSIS"
274
275.IX Header "DESCRIPTION"
276
277.IX Header "NOTES"
278
279.IX Header "RETURN VALUES"
280
281.IX Item "1"
282
283.IX Item "0"
284
285.IX Header "EXAMPLES"
286
287.IX Header "SEE ALSO"
288