]>
Commit | Line | Data |
---|---|---|
43c34894 MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
24358340 | 5 | SSL_CTX_set_tlsext_status_cb, |
fddfc0af | 6 | SSL_CTX_get_tlsext_status_cb, |
24358340 | 7 | SSL_CTX_set_tlsext_status_arg, |
fddfc0af | 8 | SSL_CTX_get_tlsext_status_arg, |
24358340 MC |
9 | SSL_CTX_set_tlsext_status_type, |
10 | SSL_CTX_get_tlsext_status_type, | |
11 | SSL_set_tlsext_status_type, | |
12 | SSL_get_tlsext_status_type, | |
13 | SSL_get_tlsext_status_ocsp_resp, | |
14 | SSL_set_tlsext_status_ocsp_resp | |
15 | - OCSP Certificate Status Request functions | |
43c34894 MC |
16 | |
17 | =head1 SYNOPSIS | |
18 | ||
19 | #include <openssl/tls1.h> | |
20 | ||
e9b77246 BB |
21 | long SSL_CTX_set_tlsext_status_cb(SSL_CTX *ctx, int (*callback)(SSL *, void *)); |
22 | long SSL_CTX_get_tlsext_status_cb(SSL_CTX *ctx, int (**callback)(SSL *, void *)); | |
fddfc0af | 23 | |
43c34894 | 24 | long SSL_CTX_set_tlsext_status_arg(SSL_CTX *ctx, void *arg); |
fddfc0af | 25 | long SSL_CTX_get_tlsext_status_arg(SSL_CTX *ctx, void **arg); |
43c34894 | 26 | |
c408b80c | 27 | long SSL_CTX_set_tlsext_status_type(SSL_CTX *ctx, int type); |
24358340 | 28 | long SSL_CTX_get_tlsext_status_type(SSL_CTX *ctx); |
c408b80c | 29 | |
43c34894 | 30 | long SSL_set_tlsext_status_type(SSL *s, int type); |
24358340 | 31 | long SSL_get_tlsext_status_type(SSL *s); |
43c34894 MC |
32 | |
33 | long SSL_get_tlsext_status_ocsp_resp(ssl, unsigned char **resp); | |
34 | long SSL_set_tlsext_status_ocsp_resp(ssl, unsigned char *resp, int len); | |
35 | ||
36 | =head1 DESCRIPTION | |
37 | ||
38 | A client application may request that a server send back an OCSP status response | |
39 | (also known as OCSP stapling). To do so the client should call the | |
c408b80c MC |
40 | SSL_CTX_set_tlsext_status_type() function prior to the creation of any SSL |
41 | objects. Alternatively an application can call the SSL_set_tlsext_status_type() | |
42 | function on an individual SSL object prior to the start of the handshake. | |
43c34894 | 43 | Currently the only supported type is B<TLSEXT_STATUSTYPE_ocsp>. This value |
24358340 MC |
44 | should be passed in the B<type> argument. Calling |
45 | SSL_CTX_get_tlsext_status_type() will return the type B<TLSEXT_STATUSTYPE_ocsp> | |
46 | previously set via SSL_CTX_set_tlsext_status_type() or -1 if not set. | |
c408b80c MC |
47 | |
48 | The client should additionally provide a callback function to decide what to do | |
49 | with the returned OCSP response by calling SSL_CTX_set_tlsext_status_cb(). The | |
50 | callback function should determine whether the returned OCSP response is | |
51 | acceptable or not. The callback will be passed as an argument the value | |
52 | previously set via a call to SSL_CTX_set_tlsext_status_arg(). Note that the | |
53 | callback will not be called in the event of a handshake where session resumption | |
54 | occurs (because there are no Certificates exchanged in such a handshake). | |
fddfc0af RG |
55 | The callback previously set via SSL_CTX_set_tlsext_status_cb() can be retrieved |
56 | by calling SSL_CTX_get_tlsext_status_cb(), and the argument by calling | |
57 | SSL_CTX_get_tlsext_status_arg(). | |
43c34894 | 58 | |
24358340 MC |
59 | On the client side SSL_get_tlsext_status_type() can be used to determine whether |
60 | the client has previously called SSL_set_tlsext_status_type(). It will return | |
61 | B<TLSEXT_STATUSTYPE_ocsp> if it has been called or -1 otherwise. On the server | |
62 | side SSL_get_tlsext_status_type() can be used to determine whether the client | |
63 | requested OCSP stapling. If the client requested it then this function will | |
64 | return B<TLSEXT_STATUSTYPE_ocsp>, or -1 otherwise. | |
65 | ||
43c34894 MC |
66 | The response returned by the server can be obtained via a call to |
67 | SSL_get_tlsext_status_ocsp_resp(). The value B<*resp> will be updated to point | |
68 | to the OCSP response data and the return value will be the length of that data. | |
69 | Typically a callback would obtain an OCSP_RESPONSE object from this data via a | |
70 | call to the d2i_OCSP_RESPONSE() function. If the server has not provided any | |
71 | response data then B<*resp> will be NULL and the return value from | |
72 | SSL_get_tlsext_status_ocsp_resp() will be -1. | |
73 | ||
74 | A server application must also call the SSL_CTX_set_tlsext_status_cb() function | |
75 | if it wants to be able to provide clients with OCSP Certificate Status | |
76 | responses. Typically the server callback would obtain the server certificate | |
77 | that is being sent back to the client via a call to SSL_get_certificate(); | |
78 | obtain the OCSP response to be sent back; and then set that response data by | |
79 | calling SSL_set_tlsext_status_ocsp_resp(). A pointer to the response data should | |
80 | be provided in the B<resp> argument, and the length of that data should be in | |
81 | the B<len> argument. | |
82 | ||
83 | =head1 RETURN VALUES | |
84 | ||
85 | The callback when used on the client side should return a negative value on | |
86 | error; 0 if the response is not acceptable (in which case the handshake will | |
87 | fail) or a positive value if it is acceptable. | |
88 | ||
89 | The callback when used on the server side should return with either | |
90 | SSL_TLSEXT_ERR_OK (meaning that the OCSP response that has been set should be | |
91 | returned), SSL_TLSEXT_ERR_NOACK (meaning that an OCSP response should not be | |
92 | returned) or SSL_TLSEXT_ERR_ALERT_FATAL (meaning that a fatal error has | |
93 | occurred). | |
94 | ||
95 | SSL_CTX_set_tlsext_status_cb(), SSL_CTX_set_tlsext_status_arg(), | |
c408b80c MC |
96 | SSL_CTX_set_tlsext_status_type(), SSL_set_tlsext_status_type() and |
97 | SSL_set_tlsext_status_ocsp_resp() return 0 on error or 1 on success. | |
43c34894 | 98 | |
24358340 MC |
99 | SSL_CTX_get_tlsext_status_type() returns the value previously set by |
100 | SSL_CTX_set_tlsext_status_type(), or -1 if not set. | |
101 | ||
43c34894 MC |
102 | SSL_get_tlsext_status_ocsp_resp() returns the length of the OCSP response data |
103 | or -1 if there is no OCSP response data. | |
104 | ||
24358340 MC |
105 | SSL_get_tlsext_status_type() returns B<TLSEXT_STATUSTYPE_ocsp> on the client |
106 | side if SSL_set_tlsext_status_type() was previously called, or on the server | |
107 | side if the client requested OCSP stapling. Otherwise -1 is returned. | |
108 | ||
98ca37e4 RS |
109 | =head1 SEE ALSO |
110 | ||
111 | L<ssl(7)> | |
112 | ||
c408b80c MC |
113 | =head1 HISTORY |
114 | ||
fc5ecadd DMSP |
115 | The SSL_get_tlsext_status_type(), SSL_CTX_get_tlsext_status_type() |
116 | and SSL_CTX_set_tlsext_status_type() functions were added in OpenSSL 1.1.0. | |
c408b80c | 117 | |
e2f92610 RS |
118 | =head1 COPYRIGHT |
119 | ||
120 | Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. | |
121 | ||
4746f25a | 122 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
123 | this file except in compliance with the License. You can obtain a copy |
124 | in the file LICENSE in the source distribution or at | |
125 | L<https://www.openssl.org/source/license.html>. | |
126 | ||
127 | =cut |