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