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