]>
Commit | Line | Data |
---|---|---|
797a89a1 DSH |
1 | =pod |
2 | ||
aec3ecd0 RL |
3 | =head1 NAME |
4 | ||
9b9d24f0 DDO |
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 | |
c952780c | 12 | - OCSP response utility functions |
797a89a1 DSH |
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 | ||
79613ea8 MC |
32 | const ASN1_GENERALIZEDTIME *OCSP_resp_get0_produced_at( |
33 | const OCSP_BASICRESP* single); | |
213f60bf | 34 | |
6ad952ba | 35 | const ASN1_OCTET_STRING *OCSP_resp_get0_signature(const OCSP_BASICRESP *bs); |
20c36721 PK |
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); | |
02fb7cfe DSH |
38 | const STACK_OF(X509) *OCSP_resp_get0_certs(const OCSP_BASICRESP *bs); |
39 | ||
b741fcd2 | 40 | int OCSP_resp_get0_signer(OCSP_BASICRESP *bs, X509 **signer, |
ce5886dd BK |
41 | STACK_OF(X509) *extra_certs); |
42 | ||
02fb7cfe DSH |
43 | int OCSP_resp_get0_id(const OCSP_BASICRESP *bs, |
44 | const ASN1_OCTET_STRING **pid, | |
45 | const X509_NAME **pname); | |
db17e43d SS |
46 | int OCSP_resp_get1_id(const OCSP_BASICRESP *bs, |
47 | ASN1_OCTET_STRING **pid, | |
48 | X509_NAME **pname); | |
02fb7cfe | 49 | |
797a89a1 DSH |
50 | int OCSP_check_validity(ASN1_GENERALIZEDTIME *thisupd, |
51 | ASN1_GENERALIZEDTIME *nextupd, | |
52 | long sec, long maxsec); | |
53 | ||
b8c32081 DO |
54 | int OCSP_basic_verify(OCSP_BASICRESP *bs, STACK_OF(X509) *certs, |
55 | X509_STORE *st, unsigned long flags); | |
56 | ||
797a89a1 DSH |
57 | =head1 DESCRIPTION |
58 | ||
7d5ea3fe DDO |
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 | |
797a89a1 | 62 | B<V_OCSP_CERTSTATUS_GOOD>, B<V_OCSP_CERTSTATUS_REVOKED> or |
7d5ea3fe DDO |
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 | |
797a89a1 DSH |
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 | ||
7d5ea3fe | 72 | OCSP_resp_count() returns the number of B<OCSP_SINGLERESP> structures in I<bs>. |
797a89a1 | 73 | |
9b9d24f0 DDO |
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. | |
797a89a1 | 76 | |
7d5ea3fe DDO |
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. | |
797a89a1 | 79 | |
7d5ea3fe DDO |
80 | OCSP_single_get0_status() extracts the fields of I<single> in I<*reason>, |
81 | I<*revtime>, I<*thisupd> and I<*nextupd>. | |
797a89a1 | 82 | |
213f60bf | 83 | OCSP_resp_get0_produced_at() extracts the B<producedAt> field from the |
7d5ea3fe | 84 | single response I<bs>. |
213f60bf | 85 | |
7d5ea3fe | 86 | OCSP_resp_get0_signature() returns the signature from I<bs>. |
6ad952ba | 87 | |
7d5ea3fe | 88 | OCSP_resp_get0_tbs_sigalg() returns the B<signatureAlgorithm> from I<bs>. |
20c36721 | 89 | |
7d5ea3fe | 90 | OCSP_resp_get0_respdata() returns the B<tbsResponseData> from I<bs>. |
20c36721 | 91 | |
7d5ea3fe | 92 | OCSP_resp_get0_certs() returns any certificates included in I<bs>. |
02fb7cfe | 93 | |
eb48052e | 94 | OCSP_resp_get0_signer() attempts to retrieve the certificate that directly |
7d5ea3fe | 95 | signed I<bs>. The OCSP protocol does not require that this certificate |
ce5886dd | 96 | is included in the B<certs> field of the response, so additional certificates |
7d5ea3fe | 97 | can be supplied via the I<extra_certs> if the certificates that may have |
ce5886dd BK |
98 | signed the response are known via some out-of-band mechanism. |
99 | ||
7d5ea3fe DDO |
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> | |
9b9d24f0 DDO |
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. | |
02fb7cfe | 108 | |
7d5ea3fe DDO |
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. | |
797a89a1 | 114 | |
7d5ea3fe DDO |
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. | |
b8c32081 | 118 | The function first tries to find the signer certificate of the response |
7d5ea3fe | 119 | in I<certs>. It then searches the certificates the responder may have included |
37326895 | 120 | in I<bs> unless I<flags> contains B<OCSP_NOINTERN>. |
b8c32081 | 121 | It fails if the signer certificate cannot be found. |
37326895 | 122 | Next, unless I<flags> contains B<OCSP_NOSIGS>, the function checks |
7d5ea3fe | 123 | the signature of I<bs> and fails on error. Then the function already returns |
37326895 DDO |
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>. | |
b8c32081 | 126 | Otherwise the function continues by validating the signer certificate. |
37326895 DDO |
127 | If I<flags> contains B<OCSP_PARTIAL_CHAIN> it takes intermediate CA |
128 | certificates in I<st> as trust anchors. | |
0495a3ec RS |
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>. | |
37326895 DDO |
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. | |
e304aa87 | 134 | Certificate revocation status checks using CRLs is disabled during path validation |
4ff993d7 | 135 | if the signer certificate contains the B<id-pkix-ocsp-no-check> extension. |
37326895 | 136 | After successful path |
b8c32081 DO |
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 | |
37326895 | 140 | B<OCSP_NOEXPLICIT> flag is not set the function checks for explicit |
b8c32081 DO |
141 | trust for OCSP signing in the root CA certificate. |
142 | ||
797a89a1 DSH |
143 | =head1 RETURN VALUES |
144 | ||
7d5ea3fe | 145 | OCSP_resp_find_status() returns 1 if I<id> is found in I<bs> and 0 otherwise. |
797a89a1 | 146 | |
9b9d24f0 DDO |
147 | OCSP_resp_count() returns the total number of B<OCSP_SINGLERESP> fields in I<bs> |
148 | or -1 on error. | |
797a89a1 DSH |
149 | |
150 | OCSP_resp_get0() returns a pointer to an B<OCSP_SINGLERESP> structure or | |
9b9d24f0 | 151 | NULL on error, such as I<idx> being out of range. |
797a89a1 | 152 | |
9b9d24f0 DDO |
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. | |
797a89a1 | 155 | |
7d5ea3fe | 156 | OCSP_single_get0_status() returns the status of I<single> or -1 if an error |
797a89a1 DSH |
157 | occurred. |
158 | ||
9b9d24f0 DDO |
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 | ||
ce5886dd | 169 | OCSP_resp_get0_signer() returns 1 if the signing certificate was located, |
9b9d24f0 DDO |
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. | |
ce5886dd | 178 | |
9b9d24f0 DDO |
179 | OCSP_basic_verify() returns 1 on success, 0 on verification not successful, |
180 | or -1 on a fatal error such as malloc failure. | |
b8c32081 | 181 | |
797a89a1 DSH |
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 | |
7d5ea3fe | 190 | account for clock skew the I<maxsec> field can be set to nonzero in |
797a89a1 DSH |
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 | |
7d5ea3fe | 193 | I<maxsec> parameter to OCSP_check_validity() can be used to limit the permitted |
797a89a1 DSH |
194 | age of responses. |
195 | ||
7d5ea3fe | 196 | The values written to I<*revtime>, I<*thisupd> and I<*nextupd> by |
797a89a1 | 197 | OCSP_resp_find_status() and OCSP_single_get0_status() are internal pointers |
7d5ea3fe | 198 | which MUST NOT be freed up by the calling application. Any or all of these |
797a89a1 DSH |
199 | parameters can be set to NULL if their value is not required. |
200 | ||
201 | =head1 SEE ALSO | |
202 | ||
b97fdb57 | 203 | L<crypto(7)>, |
9b86974e RS |
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)>, | |
0495a3ec RS |
208 | L<OCSP_sendreq_new(3)>, |
209 | L<X509_VERIFY_PARAM_set_flags(3)> | |
797a89a1 | 210 | |
e2f92610 RS |
211 | =head1 COPYRIGHT |
212 | ||
fecb3aae | 213 | Copyright 2015-2022 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 214 | |
4746f25a | 215 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
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 |