1*c8cb7e60Stb.\" $OpenBSD: tls_ocsp_process_response.3,v 1.6 2018/07/24 02:01:34 tb Exp $ 2e690d60fSschwarze.\" 34801fc0bSschwarze.\" Copyright (c) 2016 Bob Beck <beck@openbsd.org> 4e690d60fSschwarze.\" 5e690d60fSschwarze.\" Permission to use, copy, modify, and distribute this software for any 6e690d60fSschwarze.\" purpose with or without fee is hereby granted, provided that the above 7e690d60fSschwarze.\" copyright notice and this permission notice appear in all copies. 8e690d60fSschwarze.\" 9e690d60fSschwarze.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10e690d60fSschwarze.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11e690d60fSschwarze.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12e690d60fSschwarze.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13e690d60fSschwarze.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14e690d60fSschwarze.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15e690d60fSschwarze.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16e690d60fSschwarze.\" 17*c8cb7e60Stb.Dd $Mdocdate: July 24 2018 $ 18e690d60fSschwarze.Dt TLS_OCSP_PROCESS_RESPONSE 3 19e690d60fSschwarze.Os 20e690d60fSschwarze.Sh NAME 21e690d60fSschwarze.Nm tls_ocsp_process_response , 22*c8cb7e60Stb.Nm tls_peer_ocsp_url , 23*c8cb7e60Stb.Nm tls_peer_ocsp_response_status , 24e690d60fSschwarze.Nm tls_peer_ocsp_cert_status , 25e690d60fSschwarze.Nm tls_peer_ocsp_crl_reason , 26b8704739Stb.Nm tls_peer_ocsp_result , 27e690d60fSschwarze.Nm tls_peer_ocsp_revocation_time , 28e690d60fSschwarze.Nm tls_peer_ocsp_this_update , 29*c8cb7e60Stb.Nm tls_peer_ocsp_next_update 30e690d60fSschwarze.Nd inspect an OCSP response 31e690d60fSschwarze.Sh SYNOPSIS 32e690d60fSschwarze.In tls.h 33e690d60fSschwarze.Ft int 34e690d60fSschwarze.Fo tls_ocsp_process_response 35e690d60fSschwarze.Fa "struct tls *ctx" 36e690d60fSschwarze.Fa "const unsigned char *response" 37e690d60fSschwarze.Fa "size_t size" 38e690d60fSschwarze.Fc 39*c8cb7e60Stb.Ft const char * 40*c8cb7e60Stb.Fn tls_peer_ocsp_url "struct tls *ctx" 41*c8cb7e60Stb.Ft int 42*c8cb7e60Stb.Fn tls_peer_ocsp_response_status "struct tls *ctx" 43e690d60fSschwarze.Ft int 44e690d60fSschwarze.Fn tls_peer_ocsp_cert_status "struct tls *ctx" 45e690d60fSschwarze.Ft int 46e690d60fSschwarze.Fn tls_peer_ocsp_crl_reason "struct tls *ctx" 47e690d60fSschwarze.Ft const char * 48b8704739Stb.Fn tls_peer_ocsp_result "struct tls *ctx" 49e690d60fSschwarze.Ft time_t 50e690d60fSschwarze.Fn tls_peer_ocsp_revocation_time "struct tls *ctx" 51e690d60fSschwarze.Ft time_t 52e690d60fSschwarze.Fn tls_peer_ocsp_this_update "struct tls *ctx" 53*c8cb7e60Stb.Ft time_t 54*c8cb7e60Stb.Fn tls_peer_ocsp_next_update "struct tls *ctx" 55e690d60fSschwarze.Sh DESCRIPTION 56e690d60fSschwarze.Fn tls_ocsp_process_response 57e690d60fSschwarzeprocesses a raw OCSP response in 58e690d60fSschwarze.Ar response 59e690d60fSschwarzeof size 60e690d60fSschwarze.Ar size 61e690d60fSschwarzeto check the revocation status of the peer certificate from 62e690d60fSschwarze.Ar ctx . 63e690d60fSschwarzeA successful return code of 0 indicates that the certificate 64e690d60fSschwarzehas not been revoked. 65e690d60fSschwarze.Pp 66e690d60fSschwarze.Fn tls_peer_ocsp_url 67e690d60fSschwarzereturns the URL for OCSP validation of the peer certificate from 68e690d60fSschwarze.Ar ctx . 69e690d60fSschwarze.Pp 70e690d60fSschwarzeThe following functions return information about the peer certificate from 71e690d60fSschwarze.Ar ctx 72e690d60fSschwarzethat was obtained by validating a stapled OCSP response during the handshake, 73e690d60fSschwarzeor via a previous call to 74e690d60fSschwarze.Fn tls_ocsp_process_response . 75e690d60fSschwarze.Pp 76*c8cb7e60Stb.Fn tls_peer_ocsp_response_status 77*c8cb7e60Stbreturns the OCSP response status as per RFC 6960 section 2.3. 78*c8cb7e60Stb.Pp 79e690d60fSschwarze.Fn tls_peer_ocsp_cert_status 80e690d60fSschwarzereturns the OCSP certificate status code as per RFC 6960 section 2.2. 81e690d60fSschwarze.Pp 82e690d60fSschwarze.Fn tls_peer_ocsp_crl_reason 83e690d60fSschwarzereturns the OCSP certificate revocation reason status code as per RFC 5280 84e690d60fSschwarzesection 5.3.1. 85e690d60fSschwarze.Pp 86b8704739Stb.Fn tls_peer_ocsp_result 87*c8cb7e60Stbreturns a textual representation of the OCSP status code 88*c8cb7e60Stbreturned by one of the previous three functions. 89b8704739StbIf the OCSP response was valid and the certificate was not 90b8704739Stbrevoked, the string indicates the OCSP certificate status. 91b8704739StbOtherwise, the string indicates 92b8704739Stbthe OCSP certificate revocation reason or the OCSP error. 93b8704739Stb.Pp 94e690d60fSschwarze.Fn tls_peer_ocsp_revocation_time 95e690d60fSschwarzereturns the OCSP revocation time. 96e690d60fSschwarze.Pp 97e690d60fSschwarze.Fn tls_peer_ocsp_this_update 98e690d60fSschwarzereturns the OCSP this update time. 99*c8cb7e60Stb.Pp 100*c8cb7e60Stb.Fn tls_peer_ocsp_next_update 101*c8cb7e60Stbreturns the OCSP next update time. 102e690d60fSschwarze.Sh RETURN VALUES 103e690d60fSschwarze.Fn tls_ocsp_process_response 104e690d60fSschwarzereturns 0 on success or -1 on error. 105e690d60fSschwarze.Pp 106*c8cb7e60Stb.Fn tls_peer_ocsp_url 107*c8cb7e60Stband 108*c8cb7e60Stb.Fn tls_peer_ocsp_result 109*c8cb7e60Stbreturn 110*c8cb7e60Stb.Dv NULL 111*c8cb7e60Stbon error or an out of memory condition. 112*c8cb7e60Stb.Pp 113e690d60fSschwarzeThe 114e690d60fSschwarze.Fn tls_peer_ocsp_response_status 115e690d60fSschwarzefunction returns one of 116e690d60fSschwarze.Dv TLS_OCSP_RESPONSE_SUCCESSFUL , 117e690d60fSschwarze.Dv TLS_OCSP_RESPONSE_MALFORMED , 118e690d60fSschwarze.Dv TLS_OCSP_RESPONSE_INTERNALERROR , 119e690d60fSschwarze.Dv TLS_OCSP_RESPONSE_TRYLATER , 120e690d60fSschwarze.Dv TLS_OCSP_RESPONSE_SIGREQUIRED , 121e690d60fSschwarzeor 122e690d60fSschwarze.Dv TLS_OCSP_RESPONSE_UNAUTHORIZED 123e690d60fSschwarzeon success or -1 on error. 124e690d60fSschwarze.Pp 125e690d60fSschwarzeThe 126e690d60fSschwarze.Fn tls_peer_ocsp_cert_status 127e690d60fSschwarzefunction returns one of 128e690d60fSschwarze.Dv TLS_OCSP_CERT_GOOD , 129e690d60fSschwarze.Dv TLS_OCSP_CERT_REVOKED , 130e690d60fSschwarzeor 131e690d60fSschwarze.Dv TLS_OCSP_CERT_UNKNOWN 132e690d60fSschwarzeon success, and -1 on error. 133e690d60fSschwarze.Pp 134e690d60fSschwarzeThe 135e690d60fSschwarze.Fn tls_peer_ocsp_crl_reason 136e690d60fSschwarzefunction returns one of 137e690d60fSschwarze.Dv TLS_CRL_REASON_UNSPECIFIED , 138e690d60fSschwarze.Dv TLS_CRL_REASON_KEY_COMPROMISE , 139e690d60fSschwarze.Dv TLS_CRL_REASON_CA_COMPROMISE , 140e690d60fSschwarze.Dv TLS_CRL_REASON_AFFILIATION_CHANGED , 141e690d60fSschwarze.Dv TLS_CRL_REASON_SUPERSEDED , 142e690d60fSschwarze.Dv TLS_CRL_REASON_CESSATION_OF_OPERATION , 143e690d60fSschwarze.Dv TLS_CRL_REASON_CERTIFICATE_HOLD , 144e690d60fSschwarze.Dv TLS_CRL_REASON_REMOVE_FROM_CRL , 145e690d60fSschwarze.Dv TLS_CRL_REASON_PRIVILEGE_WITHDRAWN , 146e690d60fSschwarzeor 147e690d60fSschwarze.Dv TLS_CRL_REASON_AA_COMPROMISE 148e690d60fSschwarzeon success or -1 on error. 149e690d60fSschwarze.Pp 150e690d60fSschwarze.Fn tls_peer_ocsp_revocation_time , 151*c8cb7e60Stb.Fn tls_peer_ocsp_this_update , 152e690d60fSschwarzeand 153*c8cb7e60Stb.Fn tls_peer_ocsp_next_update 154e690d60fSschwarzereturn a time in epoch-seconds on success or -1 on error. 155e690d60fSschwarze.Sh SEE ALSO 156e690d60fSschwarze.Xr tls_client 3 , 157e690d60fSschwarze.Xr tls_config_ocsp_require_stapling 3 , 158e690d60fSschwarze.Xr tls_conn_version 3 , 159e690d60fSschwarze.Xr tls_connect 3 , 160e690d60fSschwarze.Xr tls_handshake 3 , 161e690d60fSschwarze.Xr tls_init 3 1628b02f64eSschwarze.Sh HISTORY 1638b02f64eSschwarzeThese functions appeared in 1648b02f64eSschwarze.Ox 6.1 . 1658b02f64eSschwarze.Sh AUTHORS 1668b02f64eSschwarze.An Bob Beck Aq Mt beck@openbsd.org 16797b5eb05Sbeck.An Marko Kreen Aq Mt markokr@gmail.com 168