Update per latest manual pages after running 'man-update'.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_client_cert_cb.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_cert_cb 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_cert_cb, SSL_CTX_get_client_cert_cb \- handle client certificate callback function
192.SH "SYNOPSIS"
a7d27d5a 193.PP
984263bc
MD
194.Vb 1
195\& #include <openssl/ssl.h>
196.Ve
197.Vb 3
198\& void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));
199\& int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
200\& int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
201.Ve
202.SH "DESCRIPTION"
a7d27d5a 203\fISSL_CTX_set_client_cert_cb()\fR sets the \fBclient_cert_cb()\fR callback, that is
984263bc 204called when a client certificate is requested by a server and no certificate
a7d27d5a 205was yet set for the SSL object.
984263bc 206.PP
a7d27d5a 207When \fBclient_cert_cb()\fR is NULL, no callback function is used.
984263bc 208.PP
a7d27d5a 209\fISSL_CTX_get_client_cert_cb()\fR returns a pointer to the currently set callback
984263bc
MD
210function.
211.PP
a7d27d5a 212\fIclient_cert_cb()\fR is the application defined callback. If it wants to
984263bc
MD
213set a certificate, a certificate/private key combination must be set
214using the \fBx509\fR and \fBpkey\fR arguments and \*(L"1\*(R" must be returned. The
a7d27d5a 215certificate will be installed into \fBssl\fR, see the NOTES and BUGS sections.
984263bc
MD
216If no certificate should be set, \*(L"0\*(R" has to be returned and no certificate
217will be sent. A negative return value will suspend the handshake and the
218handshake function will return immediatly. SSL_get_error(3)
a7d27d5a 219will return SSL_ERROR_WANT_X509_LOOKUP to indicate, that the handshake was
984263bc
MD
220suspended. The next call to the handshake function will again lead to the call
221of \fIclient_cert_cb()\fR. It is the job of the \fIclient_cert_cb()\fR to store information
222about the state of the last call, if required to continue.
223.SH "NOTES"
984263bc
MD
224During a handshake (or renegotiation) a server may request a certificate
225from the client. A client certificate must only be sent, when the server
226did send the request.
227.PP
228When a certificate was set using the
229SSL_CTX_use_certificate(3) family of functions,
a7d27d5a 230it will be sent to the server. The TLS standard requires that only a
984263bc
MD
231certificate is sent, if it matches the list of acceptable CAs sent by the
232server. This constraint is violated by the default behavior of the OpenSSL
233library. Using the callback function it is possible to implement a proper
234selection routine or to allow a user interaction to choose the certificate to
235be sent.
236.PP
237If a callback function is defined and no certificate was yet defined for the
a7d27d5a 238SSL object, the callback function will be called.
984263bc 239If the callback function returns a certificate, the OpenSSL library
a7d27d5a 240will try to load the private key and certificate data into the SSL
984263bc 241object using the \fISSL_use_certificate()\fR and \fISSL_use_private_key()\fR functions.
a7d27d5a 242Thus it will permanently install the certificate and key for this SSL
984263bc
MD
243object. It will not be reset by calling SSL_clear(3).
244If the callback returns no certificate, the OpenSSL library will not send
245a certificate.
246.SH "BUGS"
984263bc
MD
247The \fIclient_cert_cb()\fR cannot return a complete certificate chain, it can
248only return one client certificate. If the chain only has a length of 2,
a7d27d5a 249the root CA certificate may be omitted according to the TLS standard and
984263bc
MD
250thus a standard conforming answer can be sent to the server. For a
251longer chain, the client must send the complete chain (with the option
a7d27d5a
JR
252to leave out the root CA certificate). This can only be accomplished by
253either adding the intermediate CA certificates into the trusted
254certificate store for the SSL_CTX object (resulting in having to add
255CA certificates that otherwise maybe would not be trusted), or by adding
984263bc
MD
256the chain certificates using the
257SSL_CTX_add_extra_chain_cert(3)
a7d27d5a 258function, which is only available for the SSL_CTX object as a whole and that
984263bc
MD
259therefore probably can only apply for one client certificate, making
260the concept of the callback function (to allow the choice from several
261certificates) questionable.
262.PP
a7d27d5a
JR
263Once the SSL object has been used in conjunction with the callback function,
264the certificate will be set for the SSL object and will not be cleared
984263bc 265even when SSL_clear(3) is being called. It is therefore
a7d27d5a 266mandatory to destroy the SSL object using SSL_free(3)
984263bc
MD
267and create a new one to return to the previous state.
268.SH "SEE ALSO"
984263bc
MD
269ssl(3), SSL_CTX_use_certificate(3),
270SSL_CTX_add_extra_chain_cert(3),
271SSL_get_client_CA_list(3),
272SSL_clear(3), SSL_free(3)
a7d27d5a
JR
273
274.rn }` ''
275.IX Title "SSL_CTX_set_client_cert_cb 3"
276.IX Name "SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client certificate callback function"
277
278.IX Header "NAME"
279
280.IX Header "SYNOPSIS"
281
282.IX Header "DESCRIPTION"
283
284.IX Header "NOTES"
285
286.IX Header "BUGS"
287
288.IX Header "SEE ALSO"
289