1.\" $OpenBSD: SSL_CTX_set_tlsext_status_cb.3,v 1.7 2019/06/12 09:36:30 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: June 12 2019 $ 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 103A client application may request that a server send back an OCSP status 104response (also known as OCSP stapling). 105To do so the client should call the 106.Fn SSL_set_tlsext_status_type 107function on an individual 108.Vt SSL 109object prior to the start of the handshake. 110Currently the only supported type is 111.Dv TLSEXT_STATUSTYPE_ocsp . 112This value should be passed in the 113.Fa type 114argument. 115.Pp 116The client should additionally provide a callback function to decide 117what to do with the returned OCSP response by calling 118.Fn SSL_CTX_set_tlsext_status_cb . 119The callback function should determine whether the returned OCSP 120response is acceptable or not. 121The callback will be passed as an argument the value previously set via 122a call to 123.Fn SSL_CTX_set_tlsext_status_arg . 124Note that the callback will not be called in the event of a handshake 125where session resumption occurs (because there are no Certificates 126exchanged in such a handshake). 127.Pp 128The callback previously set via 129.Fn SSL_CTX_set_tlsext_status_cb 130can be retrieved by calling 131.Fn SSL_CTX_get_tlsext_status_cb , 132and the argument by calling 133.Fn SSL_CTX_get_tlsext_status_arg . 134.Pp 135The response returned by the server can be obtained via a call to 136.Fn SSL_get_tlsext_status_ocsp_resp . 137The value 138.Pf * Fa resp 139will be updated to point to the OCSP response data and the return value 140will be the length of that data. 141If the server has not provided any response data, then 142.Pf * Fa resp 143will be 144.Dv NULL 145and the return value from 146.Fn SSL_get_tlsext_status_ocsp_resp 147will be -1. 148.Pp 149A server application must also call the 150.Fn SSL_CTX_set_tlsext_status_cb 151function if it wants to be able to provide clients with OCSP Certificate 152Status responses. 153Typically the server callback would obtain the server certificate that 154is being sent back to the client via a call to 155.Xr SSL_get_certificate 3 , 156obtain the OCSP response to be sent back, and then set that response 157data by calling 158.Fn SSL_set_tlsext_status_ocsp_resp . 159A pointer to the response data should be provided in the 160.Fa resp 161argument, and the length of that data should be in the 162.Fa len 163argument. 164.Sh RETURN VALUES 165The callback when used on the client side should return a negative 166value on error, 0 if the response is not acceptable (in which case 167the handshake will fail), or a positive value if it is acceptable. 168.Pp 169The 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 , 182and 183.Fn SSL_set_tlsext_status_ocsp_resp 184always return 1, indicating success. 185.Pp 186.Fn SSL_get_tlsext_status_ocsp_resp 187returns the length of the OCSP response data 188or \-1 if there is no OCSP response data. 189.Sh SEE ALSO 190.Xr ssl 3 , 191.Xr SSL_CTX_callback_ctrl 3 192.Sh HISTORY 193.Fn SSL_CTX_set_tlsext_status_cb , 194.Fn SSL_CTX_set_tlsext_status_arg , 195.Fn SSL_set_tlsext_status_type , 196.Fn SSL_get_tlsext_status_ocsp_resp , 197and 198.Fn SSL_set_tlsext_status_ocsp_resp 199first appeared in OpenSSL 0.9.8h and have been available since 200.Ox 4.5 . 201.Pp 202.Fn SSL_CTX_get_tlsext_status_cb 203and 204.Fn SSL_CTX_get_tlsext_status_arg 205first appeared in OpenSSL 1.1.0 and have been available since 206.Ox 6.3 . 207