1=pod
2
3=head1 NAME
4
5OCSP_resp_find_status, OCSP_resp_count,
6OCSP_resp_get0, OCSP_resp_find, OCSP_single_get0_status,
7OCSP_resp_get0_produced_at, OCSP_resp_get0_signature,
8OCSP_resp_get0_tbs_sigalg, OCSP_resp_get0_respdata,
9OCSP_resp_get0_certs, OCSP_resp_get0_signer,
10OCSP_resp_get0_id, OCSP_resp_get1_id,
11OCSP_check_validity, OCSP_basic_verify
12- OCSP response utility functions
13
14=head1 SYNOPSIS
15
16 #include <openssl/ocsp.h>
17
18 int OCSP_resp_find_status(OCSP_BASICRESP *bs, OCSP_CERTID *id, int *status,
19                           int *reason,
20                           ASN1_GENERALIZEDTIME **revtime,
21                           ASN1_GENERALIZEDTIME **thisupd,
22                           ASN1_GENERALIZEDTIME **nextupd);
23
24 int OCSP_resp_count(OCSP_BASICRESP *bs);
25 OCSP_SINGLERESP *OCSP_resp_get0(OCSP_BASICRESP *bs, int idx);
26 int OCSP_resp_find(OCSP_BASICRESP *bs, OCSP_CERTID *id, int last);
27 int OCSP_single_get0_status(OCSP_SINGLERESP *single, int *reason,
28                             ASN1_GENERALIZEDTIME **revtime,
29                             ASN1_GENERALIZEDTIME **thisupd,
30                             ASN1_GENERALIZEDTIME **nextupd);
31
32 const ASN1_GENERALIZEDTIME *OCSP_resp_get0_produced_at(
33                             const OCSP_BASICRESP* single);
34
35 const ASN1_OCTET_STRING *OCSP_resp_get0_signature(const OCSP_BASICRESP *bs);
36 const X509_ALGOR *OCSP_resp_get0_tbs_sigalg(const OCSP_BASICRESP *bs);
37 const OCSP_RESPDATA *OCSP_resp_get0_respdata(const OCSP_BASICRESP *bs);
38 const STACK_OF(X509) *OCSP_resp_get0_certs(const OCSP_BASICRESP *bs);
39
40 int OCSP_resp_get0_signer(OCSP_BASICRESP *bs, X509 **signer,
41                           STACK_OF(X509) *extra_certs);
42
43 int OCSP_resp_get0_id(const OCSP_BASICRESP *bs,
44                       const ASN1_OCTET_STRING **pid,
45                       const X509_NAME **pname);
46 int OCSP_resp_get1_id(const OCSP_BASICRESP *bs,
47                       ASN1_OCTET_STRING **pid,
48                       X509_NAME **pname);
49
50 int OCSP_check_validity(ASN1_GENERALIZEDTIME *thisupd,
51                         ASN1_GENERALIZEDTIME *nextupd,
52                         long sec, long maxsec);
53
54 int OCSP_basic_verify(OCSP_BASICRESP *bs, STACK_OF(X509) *certs,
55                      X509_STORE *st, unsigned long flags);
56
57=head1 DESCRIPTION
58
59OCSP_resp_find_status() searches I<bs> for an OCSP response for I<id>. If it is
60successful the fields of the response are returned in I<*status>, I<*reason>,
61I<*revtime>, I<*thisupd> and I<*nextupd>.  The I<*status> value will be one of
62B<V_OCSP_CERTSTATUS_GOOD>, B<V_OCSP_CERTSTATUS_REVOKED> or
63B<V_OCSP_CERTSTATUS_UNKNOWN>. The I<*reason> and I<*revtime> fields are only
64set if the status is B<V_OCSP_CERTSTATUS_REVOKED>. If set the I<*reason> field
65will be set to the revocation reason which will be one of
66B<OCSP_REVOKED_STATUS_NOSTATUS>, B<OCSP_REVOKED_STATUS_UNSPECIFIED>,
67B<OCSP_REVOKED_STATUS_KEYCOMPROMISE>, B<OCSP_REVOKED_STATUS_CACOMPROMISE>,
68B<OCSP_REVOKED_STATUS_AFFILIATIONCHANGED>, B<OCSP_REVOKED_STATUS_SUPERSEDED>,
69B<OCSP_REVOKED_STATUS_CESSATIONOFOPERATION>,
70B<OCSP_REVOKED_STATUS_CERTIFICATEHOLD> or B<OCSP_REVOKED_STATUS_REMOVEFROMCRL>.
71
72OCSP_resp_count() returns the number of B<OCSP_SINGLERESP> structures in I<bs>.
73
74OCSP_resp_get0() returns the B<OCSP_SINGLERESP> structure in I<bs> corresponding
75to index I<idx>, where I<idx> runs from 0 to OCSP_resp_count(bs) - 1.
76
77OCSP_resp_find() searches I<bs> for I<id> and returns the index of the first
78matching entry after I<last> or starting from the beginning if I<last> is -1.
79
80OCSP_single_get0_status() extracts the fields of I<single> in I<*reason>,
81I<*revtime>, I<*thisupd> and I<*nextupd>.
82
83OCSP_resp_get0_produced_at() extracts the B<producedAt> field from the
84single response I<bs>.
85
86OCSP_resp_get0_signature() returns the signature from I<bs>.
87
88OCSP_resp_get0_tbs_sigalg() returns the B<signatureAlgorithm> from I<bs>.
89
90OCSP_resp_get0_respdata() returns the B<tbsResponseData> from I<bs>.
91
92OCSP_resp_get0_certs() returns any certificates included in I<bs>.
93
94OCSP_resp_get0_signer() attempts to retrieve the certificate that directly
95signed I<bs>.  The OCSP protocol does not require that this certificate
96is included in the B<certs> field of the response, so additional certificates
97can be supplied via the I<extra_certs> if the certificates that may have
98signed the response are known via some out-of-band mechanism.
99
100OCSP_resp_get0_id() gets the responder id of I<bs>. If the responder ID is
101a name then <*pname> is set to the name and I<*pid> is set to NULL. If the
102responder ID is by key ID then I<*pid> is set to the key ID and I<*pname>
103is set to NULL.
104
105OCSP_resp_get1_id() is the same as OCSP_resp_get0_id()
106but leaves ownership of I<*pid> and I<*pname> with the caller,
107who is responsible for freeing them unless the function returns 0.
108
109OCSP_check_validity() checks the validity of its I<thisupd> and I<nextupd>
110arguments, which will be typically obtained from OCSP_resp_find_status() or
111OCSP_single_get0_status(). If I<sec> is nonzero it indicates how many seconds
112leeway should be allowed in the check. If I<maxsec> is positive it indicates
113the maximum age of I<thisupd> in seconds.
114
115OCSP_basic_verify() checks that the basic response message I<bs> is correctly
116signed and that the signer certificate can be validated. It takes I<st> as
117the trusted store and I<certs> as a set of untrusted intermediate certificates.
118The function first tries to find the signer certificate of the response
119in I<certs>. It then searches the certificates the responder may have included
120in I<bs> unless I<flags> contains B<OCSP_NOINTERN>.
121It fails if the signer certificate cannot be found.
122Next, unless I<flags> contains B<OCSP_NOSIGS>, the function checks
123the signature of I<bs> and fails on error. Then the function already returns
124success if I<flags> contains B<OCSP_NOVERIFY> or if the signer certificate
125was found in I<certs> and I<flags> contains B<OCSP_TRUSTOTHER>.
126Otherwise the function continues by validating the signer certificate.
127If I<flags> contains B<OCSP_PARTIAL_CHAIN> it takes intermediate CA
128certificates in I<st> as trust anchors.
129For more details, see the description of B<X509_V_FLAG_PARTIAL_CHAIN>
130in L<X509_VERIFY_PARAM_set_flags(3)/VERIFICATION FLAGS>.
131If I<flags> contains B<OCSP_NOCHAIN> it ignores all certificates in I<certs>
132and in I<bs>, else it takes them as untrusted intermediate CA certificates
133and uses them for constructing the validation path for the signer certificate.
134Certificate revocation status checks using CRLs is disabled during path validation
135if the signer certificate contains the B<id-pkix-ocsp-no-check> extension.
136After successful path
137validation the function returns success if the B<OCSP_NOCHECKS> flag is set.
138Otherwise it verifies that the signer certificate meets the OCSP issuer
139criteria including potential delegation. If this does not succeed and the
140B<OCSP_NOEXPLICIT> flag is not set the function checks for explicit
141trust for OCSP signing in the root CA certificate.
142
143=head1 RETURN VALUES
144
145OCSP_resp_find_status() returns 1 if I<id> is found in I<bs> and 0 otherwise.
146
147OCSP_resp_count() returns the total number of B<OCSP_SINGLERESP> fields in I<bs>
148or -1 on error.
149
150OCSP_resp_get0() returns a pointer to an B<OCSP_SINGLERESP> structure or
151NULL on error, such as I<idx> being out of range.
152
153OCSP_resp_find() returns the index of I<id> in I<bs> (which may be 0)
154or -1 on error, such as when I<id> was not found.
155
156OCSP_single_get0_status() returns the status of I<single> or -1 if an error
157occurred.
158
159OCSP_resp_get0_produced_at() returns the B<producedAt> field from I<bs>.
160
161OCSP_resp_get0_signature() returns the signature from I<bs>.
162
163OCSP_resp_get0_tbs_sigalg() returns the B<signatureAlgorithm> field from I<bs>.
164
165OCSP_resp_get0_respdata() returns the B<tbsResponseData> field from I<bs>.
166
167OCSP_resp_get0_certs() returns any certificates included in I<bs>.
168
169OCSP_resp_get0_signer() returns 1 if the signing certificate was located,
170or 0 if not found or on error.
171
172OCSP_resp_get0_id() and OCSP_resp_get1_id() return 1 on success, 0 on failure.
173
174OCSP_check_validity() returns 1 if I<thisupd> and I<nextupd> are valid time
175values and the current time + I<sec> is not before I<thisupd> and,
176if I<maxsec> >= 0, the current time - I<maxsec> is not past I<nextupd>.
177Otherwise it returns 0 to indicate an error.
178
179OCSP_basic_verify() returns 1 on success, 0 on verification not successful,
180or -1 on a fatal error such as malloc failure.
181
182=head1 NOTES
183
184Applications will typically call OCSP_resp_find_status() using the certificate
185ID of interest and then check its validity using OCSP_check_validity(). They
186can then take appropriate action based on the status of the certificate.
187
188An OCSP response for a certificate contains B<thisUpdate> and B<nextUpdate>
189fields. Normally the current time should be between these two values. To
190account for clock skew the I<maxsec> field can be set to nonzero in
191OCSP_check_validity(). Some responders do not set the B<nextUpdate> field, this
192would otherwise mean an ancient response would be considered valid: the
193I<maxsec> parameter to OCSP_check_validity() can be used to limit the permitted
194age of responses.
195
196The values written to I<*revtime>, I<*thisupd> and I<*nextupd> by
197OCSP_resp_find_status() and OCSP_single_get0_status() are internal pointers
198which MUST NOT be freed up by the calling application. Any or all of these
199parameters can be set to NULL if their value is not required.
200
201=head1 SEE ALSO
202
203L<crypto(7)>,
204L<OCSP_cert_to_id(3)>,
205L<OCSP_request_add1_nonce(3)>,
206L<OCSP_REQUEST_new(3)>,
207L<OCSP_response_status(3)>,
208L<OCSP_sendreq_new(3)>,
209L<X509_VERIFY_PARAM_set_flags(3)>
210
211=head1 COPYRIGHT
212
213Copyright 2015-2023 The OpenSSL Project Authors. All Rights Reserved.
214
215Licensed under the Apache License 2.0 (the "License").  You may not use
216this file except in compliance with the License.  You can obtain a copy
217in the file LICENSE in the source distribution or at
218L<https://www.openssl.org/source/license.html>.
219
220=cut
221