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