1.\" $OpenBSD: tls_ocsp_process_response.3,v 1.4 2017/01/29 18:00:21 beck 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: January 29 2017 $ 18.Dt TLS_OCSP_PROCESS_RESPONSE 3 19.Os 20.Sh NAME 21.Nm tls_ocsp_process_response , 22.Nm tls_peer_ocsp_cert_status , 23.Nm tls_peer_ocsp_crl_reason , 24.Nm tls_peer_ocsp_next_update , 25.Nm tls_peer_ocsp_response_status , 26.Nm tls_peer_ocsp_result_msg , 27.Nm tls_peer_ocsp_revocation_time , 28.Nm tls_peer_ocsp_this_update , 29.Nm tls_peer_ocsp_url 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 int 40.Fn tls_peer_ocsp_cert_status "struct tls *ctx" 41.Ft int 42.Fn tls_peer_ocsp_crl_reason "struct tls *ctx" 43.Ft time_t 44.Fn tls_peer_ocsp_next_update "struct tls *ctx" 45.Ft int 46.Fn tls_peer_ocsp_response_status "struct tls *ctx" 47.Ft const char * 48.Fn tls_peer_ocsp_result_msg "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 const char * 54.Fn tls_peer_ocsp_url "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_cert_status 77returns the OCSP certificate status code as per RFC 6960 section 2.2. 78.Pp 79.Fn tls_peer_ocsp_crl_reason 80returns the OCSP certificate revocation reason status code as per RFC 5280 81section 5.3.1. 82.Pp 83.Fn tls_peer_ocsp_next_update 84returns the OCSP next update time. 85.Pp 86.Fn tls_peer_ocsp_response_status 87returns the OCSP response status as per RFC 6960 section 2.3. 88.Pp 89.\" XXX Fn tls_peer_ocsp_result_msg does what? 90.Fn tls_peer_ocsp_revocation_time 91returns the OCSP revocation time. 92.Pp 93.Fn tls_peer_ocsp_this_update 94returns the OCSP this update time. 95.Sh RETURN VALUES 96.Fn tls_ocsp_process_response 97returns 0 on success or -1 on error. 98.Pp 99The 100.Fn tls_peer_ocsp_response_status 101function returns one of 102.Dv TLS_OCSP_RESPONSE_SUCCESSFUL , 103.Dv TLS_OCSP_RESPONSE_MALFORMED , 104.Dv TLS_OCSP_RESPONSE_INTERNALERROR , 105.Dv TLS_OCSP_RESPONSE_TRYLATER , 106.Dv TLS_OCSP_RESPONSE_SIGREQUIRED , 107or 108.Dv TLS_OCSP_RESPONSE_UNAUTHORIZED 109on success or -1 on error. 110.Pp 111The 112.Fn tls_peer_ocsp_cert_status 113function returns one of 114.Dv TLS_OCSP_CERT_GOOD , 115.Dv TLS_OCSP_CERT_REVOKED , 116or 117.Dv TLS_OCSP_CERT_UNKNOWN 118on success, and -1 on error. 119.Pp 120The 121.Fn tls_peer_ocsp_crl_reason 122function returns one of 123.Dv TLS_CRL_REASON_UNSPECIFIED , 124.Dv TLS_CRL_REASON_KEY_COMPROMISE , 125.Dv TLS_CRL_REASON_CA_COMPROMISE , 126.Dv TLS_CRL_REASON_AFFILIATION_CHANGED , 127.Dv TLS_CRL_REASON_SUPERSEDED , 128.Dv TLS_CRL_REASON_CESSATION_OF_OPERATION , 129.Dv TLS_CRL_REASON_CERTIFICATE_HOLD , 130.Dv TLS_CRL_REASON_REMOVE_FROM_CRL , 131.Dv TLS_CRL_REASON_PRIVILEGE_WITHDRAWN , 132or 133.Dv TLS_CRL_REASON_AA_COMPROMISE 134on success or -1 on error. 135.Pp 136.Fn tls_peer_ocsp_next_update , 137.Fn tls_peer_ocsp_revocation_time , 138and 139.Fn tls_peer_ocsp_this_update 140return a time in epoch-seconds on success or -1 on error. 141.Pp 142.Fn tls_peer_ocsp_result_msg 143and 144.Fn tls_peer_ocsp_url 145return 146.Dv NULL 147on error or an out of memory condition. 148.Sh SEE ALSO 149.Xr tls_client 3 , 150.Xr tls_config_ocsp_require_stapling 3 , 151.Xr tls_conn_version 3 , 152.Xr tls_connect 3 , 153.Xr tls_handshake 3 , 154.Xr tls_init 3 155.Sh HISTORY 156These functions appeared in 157.Ox 6.1 . 158.Sh AUTHORS 159.An Bob Beck Aq Mt beck@openbsd.org 160.An Marko Kreen Aq Mt markokr@gmail.com 161