Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_client_cert_cb.3
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
e056f0e0
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
e056f0e0 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
e056f0e0 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
e056f0e0 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
e056f0e0
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
e056f0e0 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
e056f0e0
JR
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
984263bc
MD
35'br\}
36.el\{\
e056f0e0
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
984263bc 41'br\}
e056f0e0 42.\"
e257b235
PA
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
e056f0e0 47.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
e056f0e0
JR
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
e257b235 51.ie \nF \{\
e056f0e0
JR
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 54..
e056f0e0
JR
55. nr % 0
56. rr F
984263bc 57.\}
e257b235
PA
58.el \{\
59. de IX
60..
61.\}
aac4ff6f 62.\"
e056f0e0
JR
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff
984263bc 66.if n \{\
e056f0e0
JR
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
984263bc
MD
72.\}
73.if t \{\
e056f0e0
JR
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
984263bc 79.\}
e056f0e0 80. \" simple accents for nroff and troff
984263bc 81.if n \{\
e056f0e0
JR
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
984263bc
MD
88.\}
89.if t \{\
e056f0e0
JR
90. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 96.\}
e056f0e0 97. \" troff and (daisy-wheel) nroff accents
984263bc
MD
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
e056f0e0 107. \" corrections for vroff
984263bc
MD
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
e056f0e0 110. \" for low resolution devices (crt and lpr)
984263bc
MD
111.if \n(.H>23 .if \n(.V>19 \
112\{\
e056f0e0
JR
113. ds : e
114. ds 8 ss
115. ds o a
116. ds d- d\h'-1'\(ga
117. ds D- D\h'-1'\(hy
118. ds th \o'bp'
119. ds Th \o'LP'
120. ds ae ae
121. ds Ae AE
984263bc
MD
122.\}
123.rm #[ #] #H #V #F C
e056f0e0
JR
124.\" ========================================================================
125.\"
126.IX Title "SSL_CTX_set_client_cert_cb 3"
e3261593 127.TH SSL_CTX_set_client_cert_cb 3 "2012-01-04" "1.0.0f" "OpenSSL"
e257b235
PA
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
984263bc
MD
132.SH "NAME"
133SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb \- handle client certificate callback function
134.SH "SYNOPSIS"
e056f0e0 135.IX Header "SYNOPSIS"
984263bc
MD
136.Vb 1
137\& #include <openssl/ssl.h>
e257b235 138\&
984263bc
MD
139\& void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));
140\& int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
141\& int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
142.Ve
143.SH "DESCRIPTION"
e056f0e0
JR
144.IX Header "DESCRIPTION"
145\&\fISSL_CTX_set_client_cert_cb()\fR sets the \fB\f(BIclient_cert_cb()\fB\fR callback, that is
984263bc 146called when a client certificate is requested by a server and no certificate
e056f0e0 147was yet set for the \s-1SSL\s0 object.
984263bc 148.PP
e056f0e0 149When \fB\f(BIclient_cert_cb()\fB\fR is \s-1NULL\s0, no callback function is used.
984263bc 150.PP
e056f0e0 151\&\fISSL_CTX_get_client_cert_cb()\fR returns a pointer to the currently set callback
984263bc
MD
152function.
153.PP
e056f0e0 154\&\fIclient_cert_cb()\fR is the application defined callback. If it wants to
984263bc
MD
155set a certificate, a certificate/private key combination must be set
156using the \fBx509\fR and \fBpkey\fR arguments and \*(L"1\*(R" must be returned. The
e056f0e0 157certificate will be installed into \fBssl\fR, see the \s-1NOTES\s0 and \s-1BUGS\s0 sections.
984263bc
MD
158If no certificate should be set, \*(L"0\*(R" has to be returned and no certificate
159will be sent. A negative return value will suspend the handshake and the
e056f0e0
JR
160handshake function will return immediatly. \fISSL_get_error\fR\|(3)
161will return \s-1SSL_ERROR_WANT_X509_LOOKUP\s0 to indicate, that the handshake was
984263bc
MD
162suspended. The next call to the handshake function will again lead to the call
163of \fIclient_cert_cb()\fR. It is the job of the \fIclient_cert_cb()\fR to store information
164about the state of the last call, if required to continue.
165.SH "NOTES"
e056f0e0 166.IX Header "NOTES"
984263bc
MD
167During a handshake (or renegotiation) a server may request a certificate
168from the client. A client certificate must only be sent, when the server
169did send the request.
170.PP
171When a certificate was set using the
e056f0e0
JR
172\&\fISSL_CTX_use_certificate\fR\|(3) family of functions,
173it will be sent to the server. The \s-1TLS\s0 standard requires that only a
984263bc
MD
174certificate is sent, if it matches the list of acceptable CAs sent by the
175server. This constraint is violated by the default behavior of the OpenSSL
176library. Using the callback function it is possible to implement a proper
177selection routine or to allow a user interaction to choose the certificate to
178be sent.
179.PP
180If a callback function is defined and no certificate was yet defined for the
e056f0e0 181\&\s-1SSL\s0 object, the callback function will be called.
984263bc 182If the callback function returns a certificate, the OpenSSL library
e056f0e0 183will try to load the private key and certificate data into the \s-1SSL\s0
984263bc 184object using the \fISSL_use_certificate()\fR and \fISSL_use_private_key()\fR functions.
e056f0e0
JR
185Thus it will permanently install the certificate and key for this \s-1SSL\s0
186object. It will not be reset by calling \fISSL_clear\fR\|(3).
984263bc
MD
187If the callback returns no certificate, the OpenSSL library will not send
188a certificate.
189.SH "BUGS"
e056f0e0 190.IX Header "BUGS"
984263bc
MD
191The \fIclient_cert_cb()\fR cannot return a complete certificate chain, it can
192only return one client certificate. If the chain only has a length of 2,
e056f0e0 193the root \s-1CA\s0 certificate may be omitted according to the \s-1TLS\s0 standard and
984263bc
MD
194thus a standard conforming answer can be sent to the server. For a
195longer chain, the client must send the complete chain (with the option
e056f0e0
JR
196to leave out the root \s-1CA\s0 certificate). This can only be accomplished by
197either adding the intermediate \s-1CA\s0 certificates into the trusted
198certificate store for the \s-1SSL_CTX\s0 object (resulting in having to add
199\&\s-1CA\s0 certificates that otherwise maybe would not be trusted), or by adding
984263bc 200the chain certificates using the
e056f0e0
JR
201\&\fISSL_CTX_add_extra_chain_cert\fR\|(3)
202function, which is only available for the \s-1SSL_CTX\s0 object as a whole and that
984263bc
MD
203therefore probably can only apply for one client certificate, making
204the concept of the callback function (to allow the choice from several
205certificates) questionable.
206.PP
e056f0e0
JR
207Once the \s-1SSL\s0 object has been used in conjunction with the callback function,
208the certificate will be set for the \s-1SSL\s0 object and will not be cleared
209even when \fISSL_clear\fR\|(3) is being called. It is therefore
210mandatory to destroy the \s-1SSL\s0 object using \fISSL_free\fR\|(3)
984263bc
MD
211and create a new one to return to the previous state.
212.SH "SEE ALSO"
a7d27d5a 213.IX Header "SEE ALSO"
e056f0e0
JR
214\&\fIssl\fR\|(3), \fISSL_CTX_use_certificate\fR\|(3),
215\&\fISSL_CTX_add_extra_chain_cert\fR\|(3),
216\&\fISSL_get_client_CA_list\fR\|(3),
217\&\fISSL_clear\fR\|(3), \fISSL_free\fR\|(3)