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