1.\" $OpenBSD: tls_ocsp_process_response.3,v 1.6 2018/07/24 02:01:34 tb 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 24 2018 $ 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.In tls.h 33.Ft int 34.Fo tls_ocsp_process_response 35.Fa "struct tls *ctx" 36.Fa "const unsigned char *response" 37.Fa "size_t size" 38.Fc 39.Ft const char * 40.Fn tls_peer_ocsp_url "struct tls *ctx" 41.Ft int 42.Fn tls_peer_ocsp_response_status "struct tls *ctx" 43.Ft int 44.Fn tls_peer_ocsp_cert_status "struct tls *ctx" 45.Ft int 46.Fn tls_peer_ocsp_crl_reason "struct tls *ctx" 47.Ft const char * 48.Fn tls_peer_ocsp_result "struct tls *ctx" 49.Ft time_t 50.Fn tls_peer_ocsp_revocation_time "struct tls *ctx" 51.Ft time_t 52.Fn tls_peer_ocsp_this_update "struct tls *ctx" 53.Ft time_t 54.Fn tls_peer_ocsp_next_update "struct tls *ctx" 55.Sh DESCRIPTION 56.Fn tls_ocsp_process_response 57processes a raw OCSP response in 58.Ar response 59of size 60.Ar size 61to check the revocation status of the peer certificate from 62.Ar ctx . 63A successful return code of 0 indicates that the certificate 64has not been revoked. 65.Pp 66.Fn tls_peer_ocsp_url 67returns the URL for OCSP validation of the peer certificate from 68.Ar ctx . 69.Pp 70The following functions return information about the peer certificate from 71.Ar ctx 72that was obtained by validating a stapled OCSP response during the handshake, 73or via a previous call to 74.Fn tls_ocsp_process_response . 75.Pp 76.Fn tls_peer_ocsp_response_status 77returns the OCSP response status as per RFC 6960 section 2.3. 78.Pp 79.Fn tls_peer_ocsp_cert_status 80returns the OCSP certificate status code as per RFC 6960 section 2.2. 81.Pp 82.Fn tls_peer_ocsp_crl_reason 83returns the OCSP certificate revocation reason status code as per RFC 5280 84section 5.3.1. 85.Pp 86.Fn tls_peer_ocsp_result 87returns a textual representation of the OCSP status code 88returned by one of the previous three functions. 89If the OCSP response was valid and the certificate was not 90revoked, the string indicates the OCSP certificate status. 91Otherwise, the string indicates 92the OCSP certificate revocation reason or the OCSP error. 93.Pp 94.Fn tls_peer_ocsp_revocation_time 95returns the OCSP revocation time. 96.Pp 97.Fn tls_peer_ocsp_this_update 98returns the OCSP this update time. 99.Pp 100.Fn tls_peer_ocsp_next_update 101returns the OCSP next update time. 102.Sh RETURN VALUES 103.Fn tls_ocsp_process_response 104returns 0 on success or -1 on error. 105.Pp 106.Fn tls_peer_ocsp_url 107and 108.Fn tls_peer_ocsp_result 109return 110.Dv NULL 111on error or an out of memory condition. 112.Pp 113The 114.Fn tls_peer_ocsp_response_status 115function returns one of 116.Dv TLS_OCSP_RESPONSE_SUCCESSFUL , 117.Dv TLS_OCSP_RESPONSE_MALFORMED , 118.Dv TLS_OCSP_RESPONSE_INTERNALERROR , 119.Dv TLS_OCSP_RESPONSE_TRYLATER , 120.Dv TLS_OCSP_RESPONSE_SIGREQUIRED , 121or 122.Dv TLS_OCSP_RESPONSE_UNAUTHORIZED 123on success or -1 on error. 124.Pp 125The 126.Fn tls_peer_ocsp_cert_status 127function returns one of 128.Dv TLS_OCSP_CERT_GOOD , 129.Dv TLS_OCSP_CERT_REVOKED , 130or 131.Dv TLS_OCSP_CERT_UNKNOWN 132on success, and -1 on error. 133.Pp 134The 135.Fn tls_peer_ocsp_crl_reason 136function returns one of 137.Dv TLS_CRL_REASON_UNSPECIFIED , 138.Dv TLS_CRL_REASON_KEY_COMPROMISE , 139.Dv TLS_CRL_REASON_CA_COMPROMISE , 140.Dv TLS_CRL_REASON_AFFILIATION_CHANGED , 141.Dv TLS_CRL_REASON_SUPERSEDED , 142.Dv TLS_CRL_REASON_CESSATION_OF_OPERATION , 143.Dv TLS_CRL_REASON_CERTIFICATE_HOLD , 144.Dv TLS_CRL_REASON_REMOVE_FROM_CRL , 145.Dv TLS_CRL_REASON_PRIVILEGE_WITHDRAWN , 146or 147.Dv TLS_CRL_REASON_AA_COMPROMISE 148on success or -1 on error. 149.Pp 150.Fn tls_peer_ocsp_revocation_time , 151.Fn tls_peer_ocsp_this_update , 152and 153.Fn tls_peer_ocsp_next_update 154return a time in epoch-seconds on success or -1 on error. 155.Sh SEE ALSO 156.Xr tls_client 3 , 157.Xr tls_config_ocsp_require_stapling 3 , 158.Xr tls_conn_version 3 , 159.Xr tls_connect 3 , 160.Xr tls_handshake 3 , 161.Xr tls_init 3 162.Sh HISTORY 163These functions appeared in 164.Ox 6.1 . 165.Sh AUTHORS 166.An Bob Beck Aq Mt beck@openbsd.org 167.An Marko Kreen Aq Mt markokr@gmail.com 168