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