xref: /openbsd-src/lib/libtls/man/tls_ocsp_process_response.3 (revision c8cb7e6068f247a1ce3fb16dc32aab592208b818)
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