Merge branch 'vendor/LIBARCHIVE'
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_client_CA_list.3
CommitLineData
e257b235 1.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
e056f0e0
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
e056f0e0 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
e056f0e0 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
e056f0e0 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
e056f0e0
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
28.\" double quote, and \*(R" will give a right double quote. \*(C+ will
29.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31.\" nothing in troff, for use with C<>.
32.tr \(*W-
e056f0e0 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
e056f0e0
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
e056f0e0
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
e056f0e0 50.\"
e257b235
PA
51.\" Escape single quotes in literal strings from groff's Unicode transform.
52.ie \n(.g .ds Aq \(aq
53.el .ds Aq '
54.\"
e056f0e0
JR
55.\" If the F register is turned on, we'll generate index entries on stderr for
56.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57.\" entries marked with X<> in POD. Of course, you'll have to process the
58.\" output yourself in some meaningful fashion.
e257b235 59.ie \nF \{\
e056f0e0
JR
60. de IX
61. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 62..
e056f0e0
JR
63. nr % 0
64. rr F
984263bc 65.\}
e257b235
PA
66.el \{\
67. de IX
68..
69.\}
aac4ff6f 70.\"
e056f0e0
JR
71.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72.\" Fear. Run. Save yourself. No user-serviceable parts.
73. \" fudge factors for nroff and troff
984263bc 74.if n \{\
e056f0e0
JR
75. ds #H 0
76. ds #V .8m
77. ds #F .3m
78. ds #[ \f1
79. ds #] \fP
984263bc
MD
80.\}
81.if t \{\
e056f0e0
JR
82. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
83. ds #V .6m
84. ds #F 0
85. ds #[ \&
86. ds #] \&
984263bc 87.\}
e056f0e0 88. \" simple accents for nroff and troff
984263bc 89.if n \{\
e056f0e0
JR
90. ds ' \&
91. ds ` \&
92. ds ^ \&
93. ds , \&
94. ds ~ ~
95. ds /
984263bc
MD
96.\}
97.if t \{\
e056f0e0
JR
98. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 104.\}
e056f0e0 105. \" troff and (daisy-wheel) nroff accents
984263bc
MD
106.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113.ds ae a\h'-(\w'a'u*4/10)'e
114.ds Ae A\h'-(\w'A'u*4/10)'E
e056f0e0 115. \" corrections for vroff
984263bc
MD
116.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
e056f0e0 118. \" for low resolution devices (crt and lpr)
984263bc
MD
119.if \n(.H>23 .if \n(.V>19 \
120\{\
e056f0e0
JR
121. ds : e
122. ds 8 ss
123. ds o a
124. ds d- d\h'-1'\(ga
125. ds D- D\h'-1'\(hy
126. ds th \o'bp'
127. ds Th \o'LP'
128. ds ae ae
129. ds Ae AE
984263bc
MD
130.\}
131.rm #[ #] #H #V #F C
e056f0e0
JR
132.\" ========================================================================
133.\"
134.IX Title "SSL_CTX_set_client_CA_list 3"
405d0527 135.TH SSL_CTX_set_client_CA_list 3 "2009-04-11" "0.9.8k" "OpenSSL"
e257b235
PA
136.\" For nroff, turn off justification. Always turn off hyphenation; it makes
137.\" way too many mistakes in technical documents.
138.if n .ad l
139.nh
984263bc
MD
140.SH "NAME"
141SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
142SSL_add_client_CA \- set list of CAs sent to the client when requesting a
143client certificate
144.SH "SYNOPSIS"
e056f0e0
JR
145.IX Header "SYNOPSIS"
146.Vb 1
984263bc 147\& #include <openssl/ssl.h>
e257b235 148\&
984263bc
MD
149\& void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
150\& void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
151\& int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
152\& int SSL_add_client_CA(SSL *ssl, X509 *cacert);
153.Ve
154.SH "DESCRIPTION"
e056f0e0
JR
155.IX Header "DESCRIPTION"
156\&\fISSL_CTX_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when
984263bc
MD
157requesting a client certificate for \fBctx\fR.
158.PP
e056f0e0 159\&\fISSL_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when
984263bc 160requesting a client certificate for the chosen \fBssl\fR, overriding the
e056f0e0 161setting valid for \fBssl\fR's \s-1SSL_CTX\s0 object.
984263bc 162.PP
e056f0e0 163\&\fISSL_CTX_add_client_CA()\fR adds the \s-1CA\s0 name extracted from \fBcacert\fR to the
984263bc 164list of CAs sent to the client when requesting a client certificate for
e056f0e0 165\&\fBctx\fR.
984263bc 166.PP
e056f0e0 167\&\fISSL_add_client_CA()\fR adds the \s-1CA\s0 name extracted from \fBcacert\fR to the
984263bc 168list of CAs sent to the client when requesting a client certificate for
e056f0e0 169the chosen \fBssl\fR, overriding the setting valid for \fBssl\fR's \s-1SSL_CTX\s0 object.
984263bc 170.SH "NOTES"
e056f0e0
JR
171.IX Header "NOTES"
172When a \s-1TLS/SSL\s0 server requests a client certificate (see
173\&\fB\f(BISSL_CTX_set_verify_options()\fB\fR), it sends a list of CAs, for which
984263bc
MD
174it will accept certificates, to the client.
175.PP
176This list must explicitly be set using \fISSL_CTX_set_client_CA_list()\fR for
e056f0e0 177\&\fBctx\fR and \fISSL_set_client_CA_list()\fR for the specific \fBssl\fR. The list
984263bc
MD
178specified overrides the previous setting. The CAs listed do not become
179trusted (\fBlist\fR only contains the names, not the complete certificates); use
e056f0e0 180\&\fISSL_CTX_load_verify_locations\fR\|(3)
984263bc
MD
181to additionally load them for verification.
182.PP
183If the list of acceptable CAs is compiled in a file, the
e056f0e0 184\&\fISSL_load_client_CA_file\fR\|(3)
984263bc
MD
185function can be used to help importing the necessary data.
186.PP
e056f0e0 187\&\fISSL_CTX_add_client_CA()\fR and \fISSL_add_client_CA()\fR can be used to add additional
984263bc 188items the list of client CAs. If no list was specified before using
e056f0e0
JR
189\&\fISSL_CTX_set_client_CA_list()\fR or \fISSL_set_client_CA_list()\fR, a new client
190\&\s-1CA\s0 list for \fBctx\fR or \fBssl\fR (as appropriate) is opened.
984263bc 191.PP
e056f0e0 192These functions are only useful for \s-1TLS/SSL\s0 servers.
984263bc 193.SH "RETURN VALUES"
e056f0e0
JR
194.IX Header "RETURN VALUES"
195\&\fISSL_CTX_set_client_CA_list()\fR and \fISSL_set_client_CA_list()\fR do not return
984263bc
MD
196diagnostic information.
197.PP
e056f0e0 198\&\fISSL_CTX_add_client_CA()\fR and \fISSL_add_client_CA()\fR have the following return
984263bc 199values:
e257b235 200.IP "1." 4
984263bc 201The operation succeeded.
e257b235 202.IP "2." 4
e056f0e0 203A failure while manipulating the \s-1STACK_OF\s0(X509_NAME) object occurred or
984263bc
MD
204the X509_NAME could not be extracted from \fBcacert\fR. Check the error stack
205to find out the reason.
206.SH "EXAMPLES"
e056f0e0 207.IX Header "EXAMPLES"
984263bc
MD
208Scan all certificates in \fBCAfile\fR and list them as acceptable CAs:
209.PP
210.Vb 1
211\& SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(CAfile));
212.Ve
213.SH "SEE ALSO"
a7d27d5a 214.IX Header "SEE ALSO"
e056f0e0
JR
215\&\fIssl\fR\|(3),
216\&\fISSL_get_client_CA_list\fR\|(3),
217\&\fISSL_load_client_CA_file\fR\|(3),
218\&\fISSL_CTX_load_verify_locations\fR\|(3)
e257b235
PA
219.SH "POD ERRORS"
220.IX Header "POD ERRORS"
221Hey! \fBThe above document had some coding errors, which are explained below:\fR
222.IP "Around line 73:" 4
223.IX Item "Around line 73:"
224You have '=item 0' instead of the expected '=item 2'