summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/OCSP_resp_find_status.3
diff options
context:
space:
mode:
authorschwarze <>2016-11-27 20:40:07 +0000
committerschwarze <>2016-11-27 20:40:07 +0000
commitead4a921a06e852a55b89efef89b48f1a4d1e3d3 (patch)
tree37809d727204ff4a84215c775599f31426aed275 /src/lib/libcrypto/man/OCSP_resp_find_status.3
parent67128047df7652762716f09d2c4bdd5adfc569cf (diff)
downloadopenbsd-ead4a921a06e852a55b89efef89b48f1a4d1e3d3.tar.gz
openbsd-ead4a921a06e852a55b89efef89b48f1a4d1e3d3.tar.bz2
openbsd-ead4a921a06e852a55b89efef89b48f1a4d1e3d3.zip
Import OCSP documentation from OpenSSL, leaving out some stuff
that we don't have, fixing some bugs and tweaking some parts for readability. P.S. Why did some people write a HTTP client implementation and then decide that the best place to publish it might be a crypto(3) library? Oh never mind, to go easy on my sanity, i should probably stop asking such questions and just document what i find.
Diffstat (limited to 'src/lib/libcrypto/man/OCSP_resp_find_status.3')
-rw-r--r--src/lib/libcrypto/man/OCSP_resp_find_status.3285
1 files changed, 285 insertions, 0 deletions
diff --git a/src/lib/libcrypto/man/OCSP_resp_find_status.3 b/src/lib/libcrypto/man/OCSP_resp_find_status.3
new file mode 100644
index 0000000000..603b155455
--- /dev/null
+++ b/src/lib/libcrypto/man/OCSP_resp_find_status.3
@@ -0,0 +1,285 @@
1.\" $OpenBSD: OCSP_resp_find_status.3,v 1.1 2016/11/27 20:40:07 schwarze Exp $
2.\" OpenSSL c952780c Jun 21 07:03:34 2016 -0400
3.\"
4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
5.\" Copyright (c) 2014 The OpenSSL Project. All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\"
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\"
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in
16.\" the documentation and/or other materials provided with the
17.\" distribution.
18.\"
19.\" 3. All advertising materials mentioning features or use of this
20.\" software must display the following acknowledgment:
21.\" "This product includes software developed by the OpenSSL Project
22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23.\"
24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25.\" endorse or promote products derived from this software without
26.\" prior written permission. For written permission, please contact
27.\" openssl-core@openssl.org.
28.\"
29.\" 5. Products derived from this software may not be called "OpenSSL"
30.\" nor may "OpenSSL" appear in their names without prior written
31.\" permission of the OpenSSL Project.
32.\"
33.\" 6. Redistributions of any form whatsoever must retain the following
34.\" acknowledgment:
35.\" "This product includes software developed by the OpenSSL Project
36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37.\"
38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50.\"
51.Dd $Mdocdate: November 27 2016 $
52.Dt OCSP_RESP_FIND_STATUS 3
53.Os
54.Sh NAME
55.Nm OCSP_resp_find_status ,
56.Nm OCSP_resp_count ,
57.Nm OCSP_resp_get0 ,
58.Nm OCSP_resp_find ,
59.Nm OCSP_single_get0_status ,
60.Nm OCSP_check_validity
61.Nd OCSP response utility functions
62.Sh SYNOPSIS
63.In openssl/ocsp.h
64.Ft int
65.Fo OCSP_resp_find_status
66.Fa "OCSP_BASICRESP *bs"
67.Fa "OCSP_CERTID *id"
68.Fa "int *status"
69.Fa "int *reason"
70.Fa "ASN1_GENERALIZEDTIME **revtime"
71.Fa "ASN1_GENERALIZEDTIME **thisupd"
72.Fa "ASN1_GENERALIZEDTIME **nextupd"
73.Fc
74.Ft int
75.Fo OCSP_resp_count
76.Fa "OCSP_BASICRESP *bs"
77.Fc
78.Ft OCSP_SINGLERESP *
79.Fo OCSP_resp_get0
80.Fa "OCSP_BASICRESP *bs"
81.Fa "int idx"
82.Fc
83.Ft int
84.Fo OCSP_resp_find
85.Fa "OCSP_BASICRESP *bs"
86.Fa "OCSP_CERTID *id"
87.Fa "int last"
88.Fc
89.Ft int
90.Fo OCSP_single_get0_status
91.Fa "OCSP_SINGLERESP *single"
92.Fa "int *reason"
93.Fa "ASN1_GENERALIZEDTIME **revtime"
94.Fa "ASN1_GENERALIZEDTIME **thisupd"
95.Fa "ASN1_GENERALIZEDTIME **nextupd"
96.Fc
97.Ft int
98.Fo OCSP_check_validity
99.Fa "ASN1_GENERALIZEDTIME *thisupd"
100.Fa "ASN1_GENERALIZEDTIME *nextupd"
101.Fa "long sec"
102.Fa "long maxsec"
103.Fc
104.Sh DESCRIPTION
105.Fn OCSP_resp_find_status
106searches
107.Fa bs
108for an OCSP response for
109.Fa id .
110If it is successful, the fields of the response are returned in
111.Pf * Fa status ,
112.Pf * Fa reason ,
113.Pf * Fa revtime ,
114.Pf * Fa thisupd
115and
116.Pf * Fa nextupd .
117The
118.Pf * Fa status
119value will be one of
120.Dv V_OCSP_CERTSTATUS_GOOD ,
121.Dv V_OCSP_CERTSTATUS_REVOKED ,
122or
123.Dv V_OCSP_CERTSTATUS_UNKNOWN .
124The
125.Pf * Fa reason
126and
127.Pf * Fa revtime
128fields are only set if the status is
129.Dv V_OCSP_CERTSTATUS_REVOKED .
130If set, the
131.Pf * Fa reason
132field will be set to the revocation reason which will be one of
133.Dv OCSP_REVOKED_STATUS_NOSTATUS ,
134.Dv OCSP_REVOKED_STATUS_UNSPECIFIED ,
135.Dv OCSP_REVOKED_STATUS_KEYCOMPROMISE ,
136.Dv OCSP_REVOKED_STATUS_CACOMPROMISE ,
137.Dv OCSP_REVOKED_STATUS_AFFILIATIONCHANGED ,
138.Dv OCSP_REVOKED_STATUS_SUPERSEDED ,
139.Dv OCSP_REVOKED_STATUS_CESSATIONOFOPERATION ,
140.Dv OCSP_REVOKED_STATUS_CERTIFICATEHOLD
141or
142.Dv OCSP_REVOKED_STATUS_REMOVEFROMCRL .
143.Pp
144.Fn OCSP_resp_count
145returns the number of
146.Vt OCSP_SINGLERESP
147structures in
148.Fa bs .
149.Pp
150.Fn OCSP_resp_get0
151returns the
152.Vt OCSP_SINGLERESP
153structure in
154.Fa bs
155corresponding to index
156.Fa idx ,
157where
158.Fa idx
159runs from 0 to
160.Fn OCSP_resp_count bs No - 1 .
161.Pp
162.Fn OCSP_resp_find
163searches
164.Fa bs
165for
166.Fa id
167and returns the index of the first matching entry after
168.Fa last
169or starting from the beginning if
170.Fa last
171is -1.
172.Pp
173.Fn OCSP_single_get0_status
174extracts the fields of
175.Fa single
176in
177.Pf * Fa reason ,
178.Pf * Fa revtime ,
179.Pf * Fa thisupd ,
180and
181.Pf * Fa nextupd .
182.Pp
183.Fn OCSP_check_validity
184checks the validity of
185.Fa thisupd
186and
187.Fa nextupd
188values which will be typically obtained from
189.Fn OCSP_resp_find_status
190or
191.Fn OCSP_single_get0_status .
192If
193.Fa sec
194is non-zero it indicates how many seconds leeway should be allowed in
195the check.
196If
197.Fa maxsec
198is positive it indicates the maximum age of
199.Fa thisupd
200in seconds.
201.Pp
202Applications will typically call
203.Fn OCSP_resp_find_status
204using the certificate ID of interest and then check its validity using
205.Fn OCSP_check_validity .
206They can then take appropriate action based on the status of the
207certificate.
208.Pp
209An OCSP response for a certificate contains
210.Sy thisUpdate
211and
212.Sy nextUpdate
213fields.
214Normally the current time should be between these two values.
215To account for clock skew, the
216.Fa maxsec
217field can be set to non-zero in
218.Fn OCSP_check_validity .
219Some responders do not set the
220.Sy nextUpdate
221field.
222This would otherwise mean an ancient response would be considered
223valid: the
224.Fa maxsec
225parameter to
226.Fn OCSP_check_validity
227can be used to limit the permitted age of responses.
228.Pp
229The values written to
230.Pf * Fa revtime ,
231.Pf * Fa thisupd ,
232and
233.Pf * Fa nextupd
234by
235.Fn OCSP_resp_find_status
236and
237.Fn OCSP_single_get0_status
238are internal pointers which must not be freed up by the calling
239application.
240Any or all of these parameters can be set to
241.Dv NULL
242if their value is not required.
243.Sh RETURN VALUES
244.Fn OCSP_resp_find_status
245returns 1 if
246.Fa id
247is found in
248.Fa bs
249or 0 otherwise.
250.Pp
251.Fn OCSP_resp_count
252returns the total number of
253.Vt OCSP_SINGLERESP
254fields in
255.Fa bs .
256.Pp
257.Fn OCSP_resp_get0
258returns a pointer to an
259.Vt OCSP_SINGLERESP
260structure or
261.Dv NULL
262if
263.Fa idx
264is out of range.
265.Pp
266.Fn OCSP_resp_find
267returns the index of
268.Fa id
269in
270.Fa bs
271(which may be 0) or -1 if
272.Fa id
273was not found.
274.Pp
275.Fn OCSP_single_get0_status
276returns the status of
277.Fa single
278or -1 if an error occurred.
279.Sh SEE ALSO
280.Xr crypto 3 ,
281.Xr OCSP_cert_to_id 3 ,
282.Xr OCSP_request_add1_nonce 3 ,
283.Xr OCSP_REQUEST_new 3 ,
284.Xr OCSP_response_status 3 ,
285.Xr OCSP_sendreq_new 3