Debian Codegraph @

upstream/debian-unstable/man3/OCSP_resp_find_status.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OCSP_RESP_FIND_STATUS 3SSL"
58 .TH OCSP_RESP_FIND_STATUS 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 OCSP_resp_find_status, OCSP_resp_count,
65 OCSP_resp_get0, OCSP_resp_find, OCSP_single_get0_status,
66 OCSP_resp_get0_produced_at, OCSP_resp_get0_signature,
67 OCSP_resp_get0_tbs_sigalg, OCSP_resp_get0_respdata,
68 OCSP_resp_get0_certs, OCSP_resp_get0_signer,
69 OCSP_resp_get0_id, OCSP_resp_get1_id,
70 OCSP_check_validity, OCSP_basic_verify
71 \&\- OCSP response utility functions
72 .SH SYNOPSIS
73 .IX Header "SYNOPSIS"
74 .Vb 1
75 \& #include <openssl/ocsp.h>
76 \&
77 \& int OCSP_resp_find_status(OCSP_BASICRESP *bs, OCSP_CERTID *id, int *status,
78 \& int *reason,
79 \& ASN1_GENERALIZEDTIME **revtime,
80 \& ASN1_GENERALIZEDTIME **thisupd,
81 \& ASN1_GENERALIZEDTIME **nextupd);
82 \&
83 \& int OCSP_resp_count(OCSP_BASICRESP *bs);
84 \& OCSP_SINGLERESP *OCSP_resp_get0(OCSP_BASICRESP *bs, int idx);
85 \& int OCSP_resp_find(OCSP_BASICRESP *bs, OCSP_CERTID *id, int last);
86 \& int OCSP_single_get0_status(OCSP_SINGLERESP *single, int *reason,
87 \& ASN1_GENERALIZEDTIME **revtime,
88 \& ASN1_GENERALIZEDTIME **thisupd,
89 \& ASN1_GENERALIZEDTIME **nextupd);
90 \&
91 \& const ASN1_GENERALIZEDTIME *OCSP_resp_get0_produced_at(
92 \& const OCSP_BASICRESP* single);
93 \&
94 \& const ASN1_OCTET_STRING *OCSP_resp_get0_signature(const OCSP_BASICRESP *bs);
95 \& const X509_ALGOR *OCSP_resp_get0_tbs_sigalg(const OCSP_BASICRESP *bs);
96 \& const OCSP_RESPDATA *OCSP_resp_get0_respdata(const OCSP_BASICRESP *bs);
97 \& const STACK_OF(X509) *OCSP_resp_get0_certs(const OCSP_BASICRESP *bs);
98 \&
99 \& int OCSP_resp_get0_signer(OCSP_BASICRESP *bs, X509 **signer,
100 \& STACK_OF(X509) *extra_certs);
101 \&
102 \& int OCSP_resp_get0_id(const OCSP_BASICRESP *bs,
103 \& const ASN1_OCTET_STRING **pid,
104 \& const X509_NAME **pname);
105 \& int OCSP_resp_get1_id(const OCSP_BASICRESP *bs,
106 \& ASN1_OCTET_STRING **pid,
107 \& X509_NAME **pname);
108 \&
109 \& int OCSP_check_validity(ASN1_GENERALIZEDTIME *thisupd,
110 \& ASN1_GENERALIZEDTIME *nextupd,
111 \& long sec, long maxsec);
112 \&
113 \& int OCSP_basic_verify(OCSP_BASICRESP *bs, STACK_OF(X509) *certs,
114 \& X509_STORE *st, unsigned long flags);
115 .Ve
116 .SH DESCRIPTION
117 .IX Header "DESCRIPTION"
118 \&\fBOCSP_resp_find_status()\fR searches \fIbs\fR for an OCSP response for \fIid\fR. If it is
119 successful the fields of the response are returned in \fI*status\fR, \fI*reason\fR,
120 \&\fI*revtime\fR, \fI*thisupd\fR and \fI*nextupd\fR. The \fI*status\fR value will be one of
121 \&\fBV_OCSP_CERTSTATUS_GOOD\fR, \fBV_OCSP_CERTSTATUS_REVOKED\fR or
122 \&\fBV_OCSP_CERTSTATUS_UNKNOWN\fR. The \fI*reason\fR and \fI*revtime\fR fields are only
123 set if the status is \fBV_OCSP_CERTSTATUS_REVOKED\fR. If set the \fI*reason\fR field
124 will be set to the revocation reason which will be one of
125 \&\fBOCSP_REVOKED_STATUS_NOSTATUS\fR, \fBOCSP_REVOKED_STATUS_UNSPECIFIED\fR,
126 \&\fBOCSP_REVOKED_STATUS_KEYCOMPROMISE\fR, \fBOCSP_REVOKED_STATUS_CACOMPROMISE\fR,
127 \&\fBOCSP_REVOKED_STATUS_AFFILIATIONCHANGED\fR, \fBOCSP_REVOKED_STATUS_SUPERSEDED\fR,
128 \&\fBOCSP_REVOKED_STATUS_CESSATIONOFOPERATION\fR,
129 \&\fBOCSP_REVOKED_STATUS_CERTIFICATEHOLD\fR or \fBOCSP_REVOKED_STATUS_REMOVEFROMCRL\fR.
130 .PP
131 \&\fBOCSP_resp_count()\fR returns the number of \fBOCSP_SINGLERESP\fR structures in \fIbs\fR.
132 .PP
133 \&\fBOCSP_resp_get0()\fR returns the \fBOCSP_SINGLERESP\fR structure in \fIbs\fR corresponding
134 to index \fIidx\fR, where \fIidx\fR runs from 0 to OCSP_resp_count(bs) \- 1.
135 .PP
136 \&\fBOCSP_resp_find()\fR searches \fIbs\fR for \fIid\fR and returns the index of the first
137 matching entry after \fIlast\fR or starting from the beginning if \fIlast\fR is \-1.
138 .PP
139 \&\fBOCSP_single_get0_status()\fR extracts the fields of \fIsingle\fR in \fI*reason\fR,
140 \&\fI*revtime\fR, \fI*thisupd\fR and \fI*nextupd\fR.
141 .PP
142 \&\fBOCSP_resp_get0_produced_at()\fR extracts the \fBproducedAt\fR field from the
143 single response \fIbs\fR.
144 .PP
145 \&\fBOCSP_resp_get0_signature()\fR returns the signature from \fIbs\fR.
146 .PP
147 \&\fBOCSP_resp_get0_tbs_sigalg()\fR returns the \fBsignatureAlgorithm\fR from \fIbs\fR.
148 .PP
149 \&\fBOCSP_resp_get0_respdata()\fR returns the \fBtbsResponseData\fR from \fIbs\fR.
150 .PP
151 \&\fBOCSP_resp_get0_certs()\fR returns any certificates included in \fIbs\fR.
152 .PP
153 \&\fBOCSP_resp_get0_signer()\fR attempts to retrieve the certificate that directly
154 signed \fIbs\fR. The OCSP protocol does not require that this certificate
155 is included in the \fBcerts\fR field of the response, so additional certificates
156 can be supplied via the \fIextra_certs\fR if the certificates that may have
157 signed the response are known via some out-of-band mechanism.
158 .PP
159 \&\fBOCSP_resp_get0_id()\fR gets the responder id of \fIbs\fR. If the responder ID is
160 a name then <*pname> is set to the name and \fI*pid\fR is set to NULL. If the
161 responder ID is by key ID then \fI*pid\fR is set to the key ID and \fI*pname\fR
162 is set to NULL.
163 .PP
164 \&\fBOCSP_resp_get1_id()\fR is the same as \fBOCSP_resp_get0_id()\fR
165 but leaves ownership of \fI*pid\fR and \fI*pname\fR with the caller,
166 who is responsible for freeing them unless the function returns 0.
167 .PP
168 \&\fBOCSP_check_validity()\fR checks the validity of its \fIthisupd\fR and \fInextupd\fR
169 arguments, which will be typically obtained from \fBOCSP_resp_find_status()\fR or
170 \&\fBOCSP_single_get0_status()\fR. If \fIsec\fR is nonzero it indicates how many seconds
171 leeway should be allowed in the check. If \fImaxsec\fR is positive it indicates
172 the maximum age of \fIthisupd\fR in seconds.
173 .PP
174 \&\fBOCSP_basic_verify()\fR checks that the basic response message \fIbs\fR is correctly
175 signed and that the signer certificate can be validated. It takes \fIst\fR as
176 the trusted store and \fIcerts\fR as a set of untrusted intermediate certificates.
177 The function first tries to find the signer certificate of the response
178 in \fIcerts\fR. It then searches the certificates the responder may have included
179 in \fIbs\fR unless \fIflags\fR contains \fBOCSP_NOINTERN\fR.
180 It fails if the signer certificate cannot be found.
181 Next, unless \fIflags\fR contains \fBOCSP_NOSIGS\fR, the function checks
182 the signature of \fIbs\fR and fails on error. Then the function already returns
183 success if \fIflags\fR contains \fBOCSP_NOVERIFY\fR or if the signer certificate
184 was found in \fIcerts\fR and \fIflags\fR contains \fBOCSP_TRUSTOTHER\fR.
185 Otherwise the function continues by validating the signer certificate.
186 If \fIflags\fR contains \fBOCSP_PARTIAL_CHAIN\fR it takes intermediate CA
187 certificates in \fIst\fR as trust anchors.
188 For more details, see the description of \fBX509_V_FLAG_PARTIAL_CHAIN\fR
189 in "VERIFICATION FLAGS" in \fBX509_VERIFY_PARAM_set_flags\fR\|(3).
190 If \fIflags\fR contains \fBOCSP_NOCHAIN\fR it ignores all certificates in \fIcerts\fR
191 and in \fIbs\fR, else it takes them as untrusted intermediate CA certificates
192 and uses them for constructing the validation path for the signer certificate.
193 Certificate revocation status checks using CRLs is disabled during path validation
194 if the signer certificate contains the \fBid-pkix-ocsp-no-check\fR extension.
195 After successful path
196 validation the function returns success if the \fBOCSP_NOCHECKS\fR flag is set.
197 Otherwise it verifies that the signer certificate meets the OCSP issuer
198 criteria including potential delegation. If this does not succeed and the
199 \&\fBOCSP_NOEXPLICIT\fR flag is not set the function checks for explicit
200 trust for OCSP signing in the root CA certificate.
201 .SH "RETURN VALUES"
202 .IX Header "RETURN VALUES"
203 \&\fBOCSP_resp_find_status()\fR returns 1 if \fIid\fR is found in \fIbs\fR and 0 otherwise.
204 .PP
205 \&\fBOCSP_resp_count()\fR returns the total number of \fBOCSP_SINGLERESP\fR fields in \fIbs\fR
206 or \-1 on error.
207 .PP
208 \&\fBOCSP_resp_get0()\fR returns a pointer to an \fBOCSP_SINGLERESP\fR structure or
209 NULL on error, such as \fIidx\fR being out of range.
210 .PP
211 \&\fBOCSP_resp_find()\fR returns the index of \fIid\fR in \fIbs\fR (which may be 0)
212 or \-1 on error, such as when \fIid\fR was not found.
213 .PP
214 \&\fBOCSP_single_get0_status()\fR returns the status of \fIsingle\fR or \-1 if an error
215 occurred.
216 .PP
217 \&\fBOCSP_resp_get0_produced_at()\fR returns the \fBproducedAt\fR field from \fIbs\fR.
218 .PP
219 \&\fBOCSP_resp_get0_signature()\fR returns the signature from \fIbs\fR.
220 .PP
221 \&\fBOCSP_resp_get0_tbs_sigalg()\fR returns the \fBsignatureAlgorithm\fR field from \fIbs\fR.
222 .PP
223 \&\fBOCSP_resp_get0_respdata()\fR returns the \fBtbsResponseData\fR field from \fIbs\fR.
224 .PP
225 \&\fBOCSP_resp_get0_certs()\fR returns any certificates included in \fIbs\fR.
226 .PP
227 \&\fBOCSP_resp_get0_signer()\fR returns 1 if the signing certificate was located,
228 or 0 if not found or on error.
229 .PP
230 \&\fBOCSP_resp_get0_id()\fR and \fBOCSP_resp_get1_id()\fR return 1 on success, 0 on failure.
231 .PP
232 \&\fBOCSP_check_validity()\fR returns 1 if \fIthisupd\fR and \fInextupd\fR are valid time
233 values and the current time + \fIsec\fR is not before \fIthisupd\fR and,
234 if \fImaxsec\fR >= 0, the current time \- \fImaxsec\fR is not past \fInextupd\fR.
235 Otherwise it returns 0 to indicate an error.
236 .PP
237 \&\fBOCSP_basic_verify()\fR returns 1 on success, 0 on verification not successful,
238 or \-1 on a fatal error such as malloc failure.
239 .SH NOTES
240 .IX Header "NOTES"
241 Applications will typically call \fBOCSP_resp_find_status()\fR using the certificate
242 ID of interest and then check its validity using \fBOCSP_check_validity()\fR. They
243 can then take appropriate action based on the status of the certificate.
244 .PP
245 An OCSP response for a certificate contains \fBthisUpdate\fR and \fBnextUpdate\fR
246 fields. Normally the current time should be between these two values. To
247 account for clock skew the \fImaxsec\fR field can be set to nonzero in
248 \&\fBOCSP_check_validity()\fR. Some responders do not set the \fBnextUpdate\fR field, this
249 would otherwise mean an ancient response would be considered valid: the
250 \&\fImaxsec\fR parameter to \fBOCSP_check_validity()\fR can be used to limit the permitted
251 age of responses.
252 .PP
253 The values written to \fI*revtime\fR, \fI*thisupd\fR and \fI*nextupd\fR by
254 \&\fBOCSP_resp_find_status()\fR and \fBOCSP_single_get0_status()\fR are internal pointers
255 which MUST NOT be freed up by the calling application. Any or all of these
256 parameters can be set to NULL if their value is not required.
257 .SH "SEE ALSO"
258 .IX Header "SEE ALSO"
259 \&\fBcrypto\fR\|(7),
260 \&\fBOCSP_cert_to_id\fR\|(3),
261 \&\fBOCSP_request_add1_nonce\fR\|(3),
262 \&\fBOCSP_REQUEST_new\fR\|(3),
263 \&\fBOCSP_response_status\fR\|(3),
264 \&\fBOCSP_sendreq_new\fR\|(3),
265 \&\fBX509_VERIFY_PARAM_set_flags\fR\|(3)
266 .SH COPYRIGHT
267 .IX Header "COPYRIGHT"
268 Copyright 2015\-2022 The OpenSSL Project Authors. All Rights Reserved.
269 .PP
270 Licensed under the Apache License 2.0 (the "License"). You may not use
271 this file except in compliance with the License. You can obtain a copy
272 in the file LICENSE in the source distribution or at
273 <https://www.openssl.org/source/license.html>.