From 43c34894d703e3e5c2fc03bad3a78a1cf10d8ba5 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Mon, 30 Nov 2015 16:04:51 +0000 Subject: Add some documentation for the OCSP callback functions Describe the usage of the OCSP callback functions on both the client and the server side. Reviewed-by: Viktor Dukhovni --- doc/ssl/SSL_CTX_set_tlsext_status_cb.pod | 73 ++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 doc/ssl/SSL_CTX_set_tlsext_status_cb.pod (limited to 'doc') diff --git a/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod b/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod new file mode 100644 index 0000000000..b8147baecf --- /dev/null +++ b/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +SSL_CTX_set_tlsext_status_cb, SSL_CTX_set_tlsext_status_arg, +SSL_set_tlsext_status_type, SSL_get_tlsext_status_ocsp_resp, +SSL_set_tlsext_status_ocsp_resp - OCSP Certificate Status Request functions + +=head1 SYNOPSIS + + #include + + long SSL_CTX_set_tlsext_status_cb(SSL_CTX *ctx, + int (*callback)(SSL *, void *)); + long SSL_CTX_set_tlsext_status_arg(SSL_CTX *ctx, void *arg); + + long SSL_set_tlsext_status_type(SSL *s, int type); + + long SSL_get_tlsext_status_ocsp_resp(ssl, unsigned char **resp); + long SSL_set_tlsext_status_ocsp_resp(ssl, unsigned char *resp, int len); + +=head1 DESCRIPTION + +A client application may request that a server send back an OCSP status response +(also known as OCSP stapling). To do so the client should call the +SSL_set_tlsext_status_type() function prior to the start of the handshake. +Currently the only supported type is B. This value +should be passed in the B argument. The client should additionally provide +a callback function to decide what to do with the returned OCSP response by +calling SSL_CTX_set_tlsext_status_cb(). The callback function should determine +whether the returned OCSP response is acceptable or not. The callback will be +passed as an argument the value previously set via a call to +SSL_CTX_set_tlsext_status_arg(). Note that the callback will not be called in +the event of a handshake where session resumption occurs (because there are no +Certificates exchanged in such a handshake). + +The response returned by the server can be obtained via a call to +SSL_get_tlsext_status_ocsp_resp(). The value B<*resp> will be updated to point +to the OCSP response data and the return value will be the length of that data. +Typically a callback would obtain an OCSP_RESPONSE object from this data via a +call to the d2i_OCSP_RESPONSE() function. If the server has not provided any +response data then B<*resp> will be NULL and the return value from +SSL_get_tlsext_status_ocsp_resp() will be -1. + +A server application must also call the SSL_CTX_set_tlsext_status_cb() function +if it wants to be able to provide clients with OCSP Certificate Status +responses. Typically the server callback would obtain the server certificate +that is being sent back to the client via a call to SSL_get_certificate(); +obtain the OCSP response to be sent back; and then set that response data by +calling SSL_set_tlsext_status_ocsp_resp(). A pointer to the response data should +be provided in the B argument, and the length of that data should be in +the B argument. + +=head1 RETURN VALUES + +The callback when used on the client side should return a negative value on +error; 0 if the response is not acceptable (in which case the handshake will +fail) or a positive value if it is acceptable. + +The callback when used on the server side should return with either +SSL_TLSEXT_ERR_OK (meaning that the OCSP response that has been set should be +returned), SSL_TLSEXT_ERR_NOACK (meaning that an OCSP response should not be +returned) or SSL_TLSEXT_ERR_ALERT_FATAL (meaning that a fatal error has +occurred). + +SSL_CTX_set_tlsext_status_cb(), SSL_CTX_set_tlsext_status_arg(), +SSL_set_tlsext_status_type() and SSL_set_tlsext_status_ocsp_resp() return 0 on +error or 1 on success. + +SSL_get_tlsext_status_ocsp_resp() returns the length of the OCSP response data +or -1 if there is no OCSP response data. + +=cut -- cgit v1.2.3