| blob | b57c28b5a94622a37b89d2bcb08af61ae5083574 |
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
4 .\"
5 .\" This file was written by Matt Caswell <matt@openssl.org>.
6 .\" Copyright (c) 2015, 2016 The OpenSSL Project. All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\"
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
18 .\" distribution.
19 .\"
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/)"
24 .\"
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.
29 .\"
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.
33 .\"
34 .\" 6. Redistributions of any form whatsoever must retain the following
35 .\" acknowledgment:
36 .\" "This product includes software developed by the OpenSSL Project
37 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38 .\"
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.
51 .\"
52 .Dd $Mdocdate: March 24 2018 $
53 .Dt SSL_CTX_SET_TLSEXT_STATUS_CB 3
54 .Os
55 .Sh NAME
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
64 .Sh SYNOPSIS
65 .In openssl/tls1.h
66 .Ft long
67 .Fo SSL_CTX_set_tlsext_status_cb
68 .Fa "SSL_CTX *ctx"
69 .Fa "int (*callback)(SSL *, void *)"
70 .Fc
71 .Ft long
72 .Fo SSL_CTX_get_tlsext_status_cb
73 .Fa "SSL_CTX *ctx"
74 .Fa "int (*callback)(SSL *, void *)"
75 .Fc
76 .Ft long
77 .Fo SSL_CTX_set_tlsext_status_arg
78 .Fa "SSL_CTX *ctx"
79 .Fa "void *arg"
80 .Fc
81 .Ft long
82 .Fo SSL_CTX_get_tlsext_status_arg
83 .Fa "SSL_CTX *ctx"
84 .Fa "void **arg"
85 .Fc
86 .Ft long
87 .Fo SSL_set_tlsext_status_type
88 .Fa "SSL *s"
89 .Fa "int type"
90 .Fc
91 .Ft long
92 .Fo SSL_get_tlsext_status_ocsp_resp
93 .Fa ssl
94 .Fa "unsigned char **resp"
95 .Fc
96 .Ft long
97 .Fo SSL_set_tlsext_status_ocsp_resp
98 .Fa ssl
99 .Fa "unsigned char *resp"
100 .Fa "int len"
101 .Fc
102 .Sh DESCRIPTION
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
108 .Vt SSL
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
113 .Fa type
114 argument.
115 .Pp
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
122 a call to
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).
127 .Pp
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 .
134 .Pp
135 The response returned by the server can be obtained via a call to
136 .Fn SSL_get_tlsext_status_ocsp_resp .
137 The value
138 .Pf * Fa 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
142 .Pf * Fa resp
143 will be
144 .Dv NULL
145 and the return value from
146 .Fn SSL_get_tlsext_status_ocsp_resp
147 will be -1.
148 .Pp
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
152 Status responses.
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
157 data by calling
158 .Fn SSL_set_tlsext_status_ocsp_resp .
159 A pointer to the response data should be provided in the
160 .Fa resp
161 argument, and the length of that data should be in the
162 .Fa len
163 argument.
164 .Sh RETURN VALUES
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.
168 .Pp
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).
176 .Pp
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 ,
182 and
183 .Fn SSL_set_tlsext_status_ocsp_resp
184 always return 1, indicating success.
185 .Pp
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.
189 .Sh SEE ALSO
190 .Xr SSL_CTX_callback_ctrl 3
191 .Sh HISTORY
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 ,
196 and
197 .Fn SSL_set_tlsext_status_ocsp_resp
198 first appeared in OpenSSL 0.9.8h and have been available since
199 .Ox 4.5 .
200 .Pp
201 .Fn SSL_CTX_get_tlsext_status_cb
202 and
203 .Fn SSL_CTX_get_tlsext_status_arg
204 first appeared in OpenSSL 1.1.0 and have been available since
205 .Ox 6.3 .