Update build for OpenSSL-0.9.8j upgrade.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_client_cert_cb.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_cert_cb 3"
e257b235
PA
135.TH SSL_CTX_set_client_cert_cb 3 "2009-01-11" "0.9.8j" "OpenSSL"
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_cert_cb, SSL_CTX_get_client_cert_cb \- handle client certificate callback function
142.SH "SYNOPSIS"
e056f0e0 143.IX Header "SYNOPSIS"
984263bc
MD
144.Vb 1
145\& #include <openssl/ssl.h>
e257b235 146\&
984263bc
MD
147\& void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));
148\& int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
149\& int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
150.Ve
151.SH "DESCRIPTION"
e056f0e0
JR
152.IX Header "DESCRIPTION"
153\&\fISSL_CTX_set_client_cert_cb()\fR sets the \fB\f(BIclient_cert_cb()\fB\fR callback, that is
984263bc 154called when a client certificate is requested by a server and no certificate
e056f0e0 155was yet set for the \s-1SSL\s0 object.
984263bc 156.PP
e056f0e0 157When \fB\f(BIclient_cert_cb()\fB\fR is \s-1NULL\s0, no callback function is used.
984263bc 158.PP
e056f0e0 159\&\fISSL_CTX_get_client_cert_cb()\fR returns a pointer to the currently set callback
984263bc
MD
160function.
161.PP
e056f0e0 162\&\fIclient_cert_cb()\fR is the application defined callback. If it wants to
984263bc
MD
163set a certificate, a certificate/private key combination must be set
164using the \fBx509\fR and \fBpkey\fR arguments and \*(L"1\*(R" must be returned. The
e056f0e0 165certificate will be installed into \fBssl\fR, see the \s-1NOTES\s0 and \s-1BUGS\s0 sections.
984263bc
MD
166If no certificate should be set, \*(L"0\*(R" has to be returned and no certificate
167will be sent. A negative return value will suspend the handshake and the
e056f0e0
JR
168handshake function will return immediatly. \fISSL_get_error\fR\|(3)
169will return \s-1SSL_ERROR_WANT_X509_LOOKUP\s0 to indicate, that the handshake was
984263bc
MD
170suspended. The next call to the handshake function will again lead to the call
171of \fIclient_cert_cb()\fR. It is the job of the \fIclient_cert_cb()\fR to store information
172about the state of the last call, if required to continue.
173.SH "NOTES"
e056f0e0 174.IX Header "NOTES"
984263bc
MD
175During a handshake (or renegotiation) a server may request a certificate
176from the client. A client certificate must only be sent, when the server
177did send the request.
178.PP
179When a certificate was set using the
e056f0e0
JR
180\&\fISSL_CTX_use_certificate\fR\|(3) family of functions,
181it will be sent to the server. The \s-1TLS\s0 standard requires that only a
984263bc
MD
182certificate is sent, if it matches the list of acceptable CAs sent by the
183server. This constraint is violated by the default behavior of the OpenSSL
184library. Using the callback function it is possible to implement a proper
185selection routine or to allow a user interaction to choose the certificate to
186be sent.
187.PP
188If a callback function is defined and no certificate was yet defined for the
e056f0e0 189\&\s-1SSL\s0 object, the callback function will be called.
984263bc 190If the callback function returns a certificate, the OpenSSL library
e056f0e0 191will try to load the private key and certificate data into the \s-1SSL\s0
984263bc 192object using the \fISSL_use_certificate()\fR and \fISSL_use_private_key()\fR functions.
e056f0e0
JR
193Thus it will permanently install the certificate and key for this \s-1SSL\s0
194object. It will not be reset by calling \fISSL_clear\fR\|(3).
984263bc
MD
195If the callback returns no certificate, the OpenSSL library will not send
196a certificate.
197.SH "BUGS"
e056f0e0 198.IX Header "BUGS"
984263bc
MD
199The \fIclient_cert_cb()\fR cannot return a complete certificate chain, it can
200only return one client certificate. If the chain only has a length of 2,
e056f0e0 201the root \s-1CA\s0 certificate may be omitted according to the \s-1TLS\s0 standard and
984263bc
MD
202thus a standard conforming answer can be sent to the server. For a
203longer chain, the client must send the complete chain (with the option
e056f0e0
JR
204to leave out the root \s-1CA\s0 certificate). This can only be accomplished by
205either adding the intermediate \s-1CA\s0 certificates into the trusted
206certificate store for the \s-1SSL_CTX\s0 object (resulting in having to add
207\&\s-1CA\s0 certificates that otherwise maybe would not be trusted), or by adding
984263bc 208the chain certificates using the
e056f0e0
JR
209\&\fISSL_CTX_add_extra_chain_cert\fR\|(3)
210function, which is only available for the \s-1SSL_CTX\s0 object as a whole and that
984263bc
MD
211therefore probably can only apply for one client certificate, making
212the concept of the callback function (to allow the choice from several
213certificates) questionable.
214.PP
e056f0e0
JR
215Once the \s-1SSL\s0 object has been used in conjunction with the callback function,
216the certificate will be set for the \s-1SSL\s0 object and will not be cleared
217even when \fISSL_clear\fR\|(3) is being called. It is therefore
218mandatory to destroy the \s-1SSL\s0 object using \fISSL_free\fR\|(3)
984263bc
MD
219and create a new one to return to the previous state.
220.SH "SEE ALSO"
a7d27d5a 221.IX Header "SEE ALSO"
e056f0e0
JR
222\&\fIssl\fR\|(3), \fISSL_CTX_use_certificate\fR\|(3),
223\&\fISSL_CTX_add_extra_chain_cert\fR\|(3),
224\&\fISSL_get_client_CA_list\fR\|(3),
225\&\fISSL_clear\fR\|(3), \fISSL_free\fR\|(3)