1 .\" $OpenBSD: SSL_CTX_set_tlsext_status_cb.3,v 1.6 2018/03/24 00:11:37 schwarze Exp $
2 .\" full merge up to: OpenSSL 43c34894 Nov 30 16:04:51 2015 +0000
3 .\" selective merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
5 .\" This file was written by Matt Caswell <matt@openssl.org>.
6 .\" Copyright (c) 2015, 2016 The OpenSSL Project. All rights reserved.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in
17 .\" the documentation and/or other materials provided with the
20 .\" 3. All advertising materials mentioning features or use of this
21 .\" software must display the following acknowledgment:
22 .\" "This product includes software developed by the OpenSSL Project
23 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26 .\" endorse or promote products derived from this software without
27 .\" prior written permission. For written permission, please contact
28 .\" openssl-core@openssl.org.
30 .\" 5. Products derived from this software may not be called "OpenSSL"
31 .\" nor may "OpenSSL" appear in their names without prior written
32 .\" permission of the OpenSSL Project.
34 .\" 6. Redistributions of any form whatsoever must retain the following
36 .\" "This product includes software developed by the OpenSSL Project
37 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
52 .Dd $Mdocdate: March 24 2018 $
53 .Dt SSL_CTX_SET_TLSEXT_STATUS_CB 3
56 .Nm SSL_CTX_set_tlsext_status_cb ,
57 .Nm SSL_CTX_get_tlsext_status_cb ,
58 .Nm SSL_CTX_set_tlsext_status_arg ,
59 .Nm SSL_CTX_get_tlsext_status_arg ,
60 .Nm SSL_set_tlsext_status_type ,
61 .Nm SSL_get_tlsext_status_ocsp_resp ,
62 .Nm SSL_set_tlsext_status_ocsp_resp
63 .Nd OCSP Certificate Status Request functions
67 .Fo SSL_CTX_set_tlsext_status_cb
69 .Fa "int (*callback)(SSL *, void *)"
72 .Fo SSL_CTX_get_tlsext_status_cb
74 .Fa "int (*callback)(SSL *, void *)"
77 .Fo SSL_CTX_set_tlsext_status_arg
82 .Fo SSL_CTX_get_tlsext_status_arg
87 .Fo SSL_set_tlsext_status_type
92 .Fo SSL_get_tlsext_status_ocsp_resp
94 .Fa "unsigned char **resp"
97 .Fo SSL_set_tlsext_status_ocsp_resp
99 .Fa "unsigned char *resp"
103 A client application may request that a server send back an OCSP status
104 response (also known as OCSP stapling).
105 To do so the client should call the
106 .Fn SSL_set_tlsext_status_type
107 function on an individual
109 object prior to the start of the handshake.
110 Currently the only supported type is
111 .Dv TLSEXT_STATUSTYPE_ocsp .
112 This value should be passed in the
116 The client should additionally provide a callback function to decide
117 what to do with the returned OCSP response by calling
118 .Fn SSL_CTX_set_tlsext_status_cb .
119 The callback function should determine whether the returned OCSP
120 response is acceptable or not.
121 The callback will be passed as an argument the value previously set via
123 .Fn SSL_CTX_set_tlsext_status_arg .
124 Note that the callback will not be called in the event of a handshake
125 where session resumption occurs (because there are no Certificates
126 exchanged in such a handshake).
128 The callback previously set via
129 .Fn SSL_CTX_set_tlsext_status_cb
130 can be retrieved by calling
131 .Fn SSL_CTX_get_tlsext_status_cb ,
132 and the argument by calling
133 .Fn SSL_CTX_get_tlsext_status_arg .
135 The response returned by the server can be obtained via a call to
136 .Fn SSL_get_tlsext_status_ocsp_resp .
139 will be updated to point to the OCSP response data and the return value
140 will be the length of that data.
141 If the server has not provided any response data, then
145 and the return value from
146 .Fn SSL_get_tlsext_status_ocsp_resp
149 A server application must also call the
150 .Fn SSL_CTX_set_tlsext_status_cb
151 function if it wants to be able to provide clients with OCSP Certificate
153 Typically the server callback would obtain the server certificate that
154 is being sent back to the client via a call to
155 .Xr SSL_get_certificate 3 ,
156 obtain the OCSP response to be sent back, and then set that response
158 .Fn SSL_set_tlsext_status_ocsp_resp .
159 A pointer to the response data should be provided in the
161 argument, and the length of that data should be in the
165 The callback when used on the client side should return a negative
166 value on error, 0 if the response is not acceptable (in which case
167 the handshake will fail), or a positive value if it is acceptable.
169 The callback when used on the server side should return with either
170 .Dv SSL_TLSEXT_ERR_OK
171 (meaning that the OCSP response that has been set should be returned),
172 .Dv SSL_TLSEXT_ERR_NOACK
173 (meaning that an OCSP response should not be returned), or
174 .Dv SSL_TLSEXT_ERR_ALERT_FATAL
175 (meaning that a fatal error has occurred).
177 .Fn SSL_CTX_set_tlsext_status_cb ,
178 .Fn SSL_CTX_get_tlsext_status_cb ,
179 .Fn SSL_CTX_set_tlsext_status_arg ,
180 .Fn SSL_CTX_get_tlsext_status_arg ,
181 .Fn SSL_set_tlsext_status_type ,
183 .Fn SSL_set_tlsext_status_ocsp_resp
184 always return 1, indicating success.
186 .Fn SSL_get_tlsext_status_ocsp_resp
187 returns the length of the OCSP response data
188 or \-1 if there is no OCSP response data.
190 .Xr SSL_CTX_callback_ctrl 3
192 .Fn SSL_CTX_set_tlsext_status_cb ,
193 .Fn SSL_CTX_set_tlsext_status_arg ,
194 .Fn SSL_set_tlsext_status_type ,
195 .Fn SSL_get_tlsext_status_ocsp_resp ,
197 .Fn SSL_set_tlsext_status_ocsp_resp
198 first appeared in OpenSSL 0.9.8h and have been available since
201 .Fn SSL_CTX_get_tlsext_status_cb
203 .Fn SSL_CTX_get_tlsext_status_arg
204 first appeared in OpenSSL 1.1.0 and have been available since