1=pod
2
3=head1 NAME
4
5SSL_CTX_set_tlsext_status_cb,
6SSL_CTX_get_tlsext_status_cb,
7SSL_CTX_set_tlsext_status_arg,
8SSL_CTX_get_tlsext_status_arg,
9SSL_CTX_set_tlsext_status_type,
10SSL_CTX_get_tlsext_status_type,
11SSL_set_tlsext_status_type,
12SSL_get_tlsext_status_type,
13SSL_get_tlsext_status_ocsp_resp,
14SSL_set_tlsext_status_ocsp_resp,
15SSL_get0_tlsext_status_ocsp_resp_ex,
16SSL_set0_tlsext_status_ocsp_resp_ex
17- OCSP Certificate Status Request functions
18
19=head1 SYNOPSIS
20
21 #include <openssl/tls1.h>
22
23 long SSL_CTX_set_tlsext_status_cb(SSL_CTX *ctx, int (*callback)(SSL *, void *));
24 long SSL_CTX_get_tlsext_status_cb(SSL_CTX *ctx, int (**callback)(SSL *, void *));
25
26 long SSL_CTX_set_tlsext_status_arg(SSL_CTX *ctx, void *arg);
27 long SSL_CTX_get_tlsext_status_arg(SSL_CTX *ctx, void **arg);
28
29 long SSL_CTX_set_tlsext_status_type(SSL_CTX *ctx, int type);
30 long SSL_CTX_get_tlsext_status_type(SSL_CTX *ctx);
31
32 long SSL_set_tlsext_status_type(SSL *s, int type);
33 long SSL_get_tlsext_status_type(SSL *s);
34
35 long SSL_get_tlsext_status_ocsp_resp(ssl, unsigned char **resp);
36 long SSL_set_tlsext_status_ocsp_resp(ssl, unsigned char *resp, int len);
37
38 long SSL_get0_tlsext_status_ocsp_resp_ex(ssl, STACK_OF(OCSP_RESPONSE) **resp);
39 long SSL_set0_tlsext_status_ocsp_resp_ex(ssl, STACK_OF(OCSP_RESPONSE) *resp);
40
41=head1 DESCRIPTION
42
43A client application may request that a server send back OCSP status response(s)
44(also known as OCSP stapling). To do so the client should call the
45SSL_CTX_set_tlsext_status_type() function prior to the creation of any SSL
46objects. Alternatively an application can call the SSL_set_tlsext_status_type()
47function on an individual SSL object prior to the start of the handshake.
48Currently the only supported type is B<TLSEXT_STATUSTYPE_ocsp>. This value
49should be passed in the B<type> argument. Calling
50SSL_CTX_get_tlsext_status_type() will return the type B<TLSEXT_STATUSTYPE_ocsp>
51previously set via SSL_CTX_set_tlsext_status_type() or -1 if not set.
52
53For TLS versions before 1.3 only a single OCSP status response is sent back
54by the server. TLS 1.3 specifies that the server can send OCSP status responses
55for the whole chain (OCSP multi-stapling).
56
57The client should additionally provide a callback function to decide what to do
58with the returned OCSP response by calling SSL_CTX_set_tlsext_status_cb(). The
59callback function should determine whether the returned OCSP response(s) are
60acceptable or not. The callback will be passed as an argument the value
61previously set via a call to SSL_CTX_set_tlsext_status_arg(). Note that the
62callback will not be called in the event of a handshake where session resumption
63occurs (because there are no Certificates exchanged in such a handshake).
64The callback previously set via SSL_CTX_set_tlsext_status_cb() can be retrieved
65by calling SSL_CTX_get_tlsext_status_cb(), and the argument by calling
66SSL_CTX_get_tlsext_status_arg().
67
68On the client side SSL_get_tlsext_status_type() can be used to determine whether
69the client has previously called SSL_set_tlsext_status_type(). It will return
70B<TLSEXT_STATUSTYPE_ocsp> if it has been called or -1 otherwise. On the server
71side SSL_get_tlsext_status_type() can be used to determine whether the client
72requested OCSP stapling. If the client requested it then this function will
73return B<TLSEXT_STATUSTYPE_ocsp>, or -1 otherwise.
74
75A single response returned by the server (TLS < 1.3) can be obtained via a call
76to SSL_get_tlsext_status_ocsp_resp(). The value B<*resp> will be updated to
77point to the OCSP response data and the return value will be the length of that
78data. Typically a callback would obtain an OCSP_RESPONSE object from this data
79via a call to the d2i_OCSP_RESPONSE() function. If the server has not provided
80any response data then B<*resp> will be NULL and the return value from
81SSL_get_tlsext_status_ocsp_resp() will be -1.
82
83A server application must also call the SSL_CTX_set_tlsext_status_cb() function
84if it wants to be able to provide clients with (single) OCSP response for the
85server certificate. Typically the server callback would obtain the server
86certificate that is being sent back to the client via a call to
87SSL_get_certificate(); retrieve the related OCSP response to be sent back; and
88then set that response data by calling SSL_set_tlsext_status_ocsp_resp(). A
89pointer to the response data should be provided in the B<resp> argument, and
90the length of that data should be in the B<len> argument.
91
92In the case of multi-stapling the responses to be returned by the server can be
93obtained via a call to SSL_get0_tlsext_status_ocsp_resp_ex(). The value B<*resp>
94will be updated to point to the OCSP response stack and the return value will
95be the number of responses on the stack.
96The OCSP responses on the stack are expected to be in the same order as the
97certificates in the chain. If no OCSP response is available for a certificate
98in the chain, a NULL element in the stack will represent this.
99Typically a callback would obtain an OCSP_RESPONSE object from the stack via a
100call to sk_OCSP_RESPONSE_pop. If the server has not provided any response data
101then B<*resp> will be NULL and the return value from
102SSL_get0_tlsext_status_ocsp_resp_ex() will be -1.
103
104A server application must also call the SSL_CTX_set_tlsext_status_cb() function
105if it wants to be able to provide clients with OCSP Certificate Status
106responses, where TLS 1.3 allows for multi-stapling, i.e., providing responses
107for all certificates in the chain of the server certificate (excluding the root
108CA certificate).
109The certificates sent back to the client and for which OCSP response(s)
110should be acquired could be obtained via call to SSL_get_certificate() resp.
111SSL_get0_chain_certs(). OCSP response(s) then set by calling
112SSL_set0_tlsext_status_ocsp_resp_ex(). A stack of OCSP responses should be
113provided in the B<resp> argument.
114The OCSP responses on the stack are expected to be in the same order as the
115certificate in the chain. If no OCSP response is available for a certificate in
116the chain, a NULL element in the stack will represent this.
117
118=head1 RETURN VALUES
119
120The callback when used on the client side should return a negative value on
121error; 0 if the response is not acceptable (in which case the handshake will
122fail) or a positive value if it is acceptable.
123
124The callback when used on the server side should return with either
125SSL_TLSEXT_ERR_OK (meaning that the OCSP response that has been set should be
126returned), SSL_TLSEXT_ERR_NOACK (meaning that an OCSP response should not be
127returned) or SSL_TLSEXT_ERR_ALERT_FATAL (meaning that a fatal error has
128occurred).
129
130SSL_CTX_set_tlsext_status_cb(), SSL_CTX_set_tlsext_status_arg(),
131SSL_CTX_set_tlsext_status_type(), SSL_set_tlsext_status_type(),
132SSL_set_tlsext_status_ocsp_resp() return 0 on error or 1 on success.
133SSL_set0_tlsext_status_ocsp_resp_ex() will return always 1.
134
135SSL_CTX_get_tlsext_status_type() returns the value previously set by
136SSL_CTX_set_tlsext_status_type(), or -1 if not set.
137
138SSL_get_tlsext_status_ocsp_resp() returns the length of the OCSP response data
139or -1 if there is no OCSP response data.
140
141SSL_get0_tlsext_status_ocsp_resp_ex() returns the number of the OCSP responses
142on the stack or -1 if there is no OCSP response data.
143
144SSL_get_tlsext_status_type() returns B<TLSEXT_STATUSTYPE_ocsp> on the client
145side if SSL_set_tlsext_status_type() was previously called, or on the server
146side if the client requested OCSP stapling. Otherwise -1 is returned.
147
148=head1 SEE ALSO
149
150L<ssl(7)>
151
152=head1 HISTORY
153
154The SSL_get_tlsext_status_type(), SSL_CTX_get_tlsext_status_type()
155and SSL_CTX_set_tlsext_status_type() functions were added in OpenSSL 1.1.0.
156
157The SSL_get0_tlsext_status_ocsp_resp_ex() and SSL_set0_tlsext_status_ocsp_resp_ex()
158macros were added in OpenSSL 3.6.
159
160=head1 COPYRIGHT
161
162Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
163
164Licensed under the Apache License 2.0 (the "License").  You may not use
165this file except in compliance with the License.  You can obtain a copy
166in the file LICENSE in the source distribution or at
167L<https://www.openssl.org/source/license.html>.
168
169=cut
170