]>
Commit | Line | Data |
---|---|---|
b4b1bdd5 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
a068630a | 5 | ocsp - Online Certificate Status Protocol utility |
b4b1bdd5 DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | B<openssl> B<ocsp> | |
169394d4 | 10 | [B<-help>] |
b4b1bdd5 DSH |
11 | [B<-out file>] |
12 | [B<-issuer file>] | |
13 | [B<-cert file>] | |
14 | [B<-serial n>] | |
e5b0508a DSH |
15 | [B<-signer file>] |
16 | [B<-signkey file>] | |
17 | [B<-sign_other file>] | |
18 | [B<-no_certs>] | |
b4b1bdd5 DSH |
19 | [B<-req_text>] |
20 | [B<-resp_text>] | |
21 | [B<-text>] | |
22 | [B<-reqout file>] | |
23 | [B<-respout file>] | |
24 | [B<-reqin file>] | |
25 | [B<-respin file>] | |
26 | [B<-nonce>] | |
27 | [B<-no_nonce>] | |
e5b0508a | 28 | [B<-url URL>] |
46aa6078 RS |
29 | [B<-host host:port>] |
30 | [B<-header>] | |
b4b1bdd5 | 31 | [B<-path>] |
e5b0508a | 32 | [B<-CApath dir>] |
bfcec27d | 33 | [B<-CAfile file>] |
40e2d76b MC |
34 | [B<-no-CAfile>] |
35 | [B<-no-CApath>] | |
e42d84be HK |
36 | [B<-attime timestamp>] |
37 | [B<-check_ss_sig>] | |
38 | [B<-crl_check>] | |
39 | [B<-crl_check_all>] | |
40 | [B<-explicit_policy>] | |
41 | [B<-extended_crl>] | |
42 | [B<-ignore_critical>] | |
43 | [B<-inhibit_any>] | |
44 | [B<-inhibit_map>] | |
5a1f853b | 45 | [B<-no_check_time>] |
e42d84be HK |
46 | [B<-partial_chain>] |
47 | [B<-policy arg>] | |
48 | [B<-policy_check>] | |
49 | [B<-policy_print>] | |
50 | [B<-purpose purpose>] | |
51 | [B<-suiteB_128>] | |
52 | [B<-suiteB_128_only>] | |
53 | [B<-suiteB_192>] | |
6d3d5793 | 54 | [B<-trusted_first>] |
fa7b0111 | 55 | [B<-no_alt_chains>] |
e42d84be | 56 | [B<-use_deltas>] |
fbb82a60 | 57 | [B<-auth_level num>] |
e42d84be HK |
58 | [B<-verify_depth num>] |
59 | [B<-verify_email email>] | |
60 | [B<-verify_hostname hostname>] | |
61 | [B<-verify_ip ip>] | |
62 | [B<-verify_name name>] | |
63 | [B<-x509_strict>] | |
cc5ba6a7 | 64 | [B<-VAfile file>] |
e5b0508a DSH |
65 | [B<-validity_period n>] |
66 | [B<-status_age n>] | |
bfcec27d | 67 | [B<-noverify>] |
e5b0508a | 68 | [B<-verify_other file>] |
cc5ba6a7 DSH |
69 | [B<-trust_other>] |
70 | [B<-no_intern>] | |
e5b0508a | 71 | [B<-no_signature_verify>] |
cc5ba6a7 DSH |
72 | [B<-no_cert_verify>] |
73 | [B<-no_chain>] | |
74 | [B<-no_cert_checks>] | |
384dee51 | 75 | [B<-no_explicit>] |
e5b0508a DSH |
76 | [B<-port num>] |
77 | [B<-index file>] | |
78 | [B<-CA file>] | |
79 | [B<-rsigner file>] | |
80 | [B<-rkey file>] | |
81 | [B<-rother file>] | |
82 | [B<-resp_no_certs>] | |
83 | [B<-nmin n>] | |
84 | [B<-ndays n>] | |
85 | [B<-resp_key_id>] | |
86 | [B<-nrequest n>] | |
cec2538c | 87 | [B<-md5|-sha1|...>] |
b4b1bdd5 DSH |
88 | |
89 | =head1 DESCRIPTION | |
90 | ||
a068630a UM |
91 | The Online Certificate Status Protocol (OCSP) enables applications to |
92 | determine the (revocation) state of an identified certificate (RFC 2560). | |
93 | ||
b4b1bdd5 DSH |
94 | The B<ocsp> command performs many common OCSP tasks. It can be used |
95 | to print out requests and responses, create requests and send queries | |
534a1ed0 | 96 | to an OCSP responder and behave like a mini OCSP server itself. |
b4b1bdd5 | 97 | |
534a1ed0 | 98 | =head1 OCSP CLIENT OPTIONS |
b4b1bdd5 DSH |
99 | |
100 | =over 4 | |
101 | ||
169394d4 MR |
102 | =item B<-help> |
103 | ||
104 | Print out a usage message. | |
105 | ||
b4b1bdd5 DSH |
106 | =item B<-out filename> |
107 | ||
108 | specify output filename, default is standard output. | |
109 | ||
110 | =item B<-issuer filename> | |
111 | ||
112 | This specifies the current issuer certificate. This option can be used | |
113 | multiple times. The certificate specified in B<filename> must be in | |
0d7f6fc7 | 114 | PEM format. This option B<MUST> come before any B<-cert> options. |
b4b1bdd5 DSH |
115 | |
116 | =item B<-cert filename> | |
117 | ||
118 | Add the certificate B<filename> to the request. The issuer certificate | |
119 | is taken from the previous B<issuer> option, or an error occurs if no | |
120 | issuer certificate is specified. | |
121 | ||
122 | =item B<-serial num> | |
123 | ||
124 | Same as the B<cert> option except the certificate with serial number | |
bfcec27d DSH |
125 | B<num> is added to the request. The serial number is interpreted as a |
126 | decimal integer unless preceded by B<0x>. Negative integers can also | |
127 | be specified by preceding the value by a B<-> sign. | |
b4b1bdd5 DSH |
128 | |
129 | =item B<-signer filename>, B<-signkey filename> | |
130 | ||
131 | Sign the OCSP request using the certificate specified in the B<signer> | |
132 | option and the private key specified by the B<signkey> option. If | |
133 | the B<signkey> option is not present then the private key is read | |
134 | from the same file as the certificate. If neither option is specified then | |
135 | the OCSP request is not signed. | |
136 | ||
e5b0508a DSH |
137 | =item B<-sign_other filename> |
138 | ||
139 | Additional certificates to include in the signed request. | |
140 | ||
b4b1bdd5 DSH |
141 | =item B<-nonce>, B<-no_nonce> |
142 | ||
143 | Add an OCSP nonce extension to a request or disable OCSP nonce addition. | |
21c6c50f | 144 | Normally if an OCSP request is input using the B<reqin> option no |
b4b1bdd5 DSH |
145 | nonce is added: using the B<nonce> option will force addition of a nonce. |
146 | If an OCSP request is being created (using B<cert> and B<serial> options) | |
147 | a nonce is automatically added specifying B<no_nonce> overrides this. | |
148 | ||
149 | =item B<-req_text>, B<-resp_text>, B<-text> | |
150 | ||
3b80e3aa | 151 | print out the text form of the OCSP request, response or both respectively. |
b4b1bdd5 DSH |
152 | |
153 | =item B<-reqout file>, B<-respout file> | |
154 | ||
155 | write out the DER encoded certificate request or response to B<file>. | |
156 | ||
157 | =item B<-reqin file>, B<-respin file> | |
158 | ||
159 | read OCSP request or response file from B<file>. These option are ignored | |
160 | if OCSP request or response creation is implied by other options (for example | |
161 | with B<serial>, B<cert> and B<host> options). | |
162 | ||
cc5ba6a7 DSH |
163 | =item B<-url responder_url> |
164 | ||
165 | specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified. | |
166 | ||
b4b1bdd5 DSH |
167 | =item B<-host hostname:port>, B<-path pathname> |
168 | ||
169 | if the B<host> option is present then the OCSP request is sent to the host | |
170 | B<hostname> on port B<port>. B<path> specifies the HTTP path name to use | |
21c6c50f BK |
171 | or "/" by default. This is equivalent to specifying B<-url> with scheme |
172 | http:// and the given hostname, port, and pathname. | |
b4b1bdd5 | 173 | |
46aa6078 RS |
174 | =item B<-header name=value> |
175 | ||
176 | Adds the header B<name> with the specified B<value> to the OCSP request | |
177 | that is sent to the responder. | |
178 | This may be repeated. | |
179 | ||
de87dd46 AG |
180 | =item B<-timeout seconds> |
181 | ||
182 | connection timeout to the OCSP responder in seconds | |
183 | ||
bfcec27d DSH |
184 | =item B<-CAfile file>, B<-CApath pathname> |
185 | ||
186 | file or pathname containing trusted CA certificates. These are used to verify | |
187 | the signature on the OCSP response. | |
188 | ||
40e2d76b MC |
189 | =item B<-no-CAfile> |
190 | ||
191 | Do not load the trusted CA certificates from the default file location | |
192 | ||
193 | =item B<-no-CApath> | |
194 | ||
195 | Do not load the trusted CA certificates from the default directory location | |
196 | ||
e42d84be | 197 | =item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>, |
d33def66 | 198 | B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>, |
5a1f853b | 199 | B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>, |
e42d84be | 200 | B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>, |
d33def66 | 201 | B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, |
fbb82a60 VD |
202 | B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, |
203 | B<-verify_ip>, B<-verify_name>, B<-x509_strict> | |
6d3d5793 | 204 | |
e42d84be | 205 | Set different certificate verification options. |
fbb82a60 | 206 | See L<verify(1)> manual page for details. |
6d3d5793 | 207 | |
e5b0508a | 208 | =item B<-verify_other file> |
cc5ba6a7 DSH |
209 | |
210 | file containing additional certificates to search when attempting to locate | |
211 | the OCSP response signing certificate. Some responders omit the actual signer's | |
3b80e3aa | 212 | certificate from the response: this option can be used to supply the necessary |
cc5ba6a7 DSH |
213 | certificate in such cases. |
214 | ||
215 | =item B<-trust_other> | |
216 | ||
0d7f6fc7 | 217 | the certificates specified by the B<-verify_other> option should be explicitly |
cc5ba6a7 | 218 | trusted and no additional checks will be performed on them. This is useful |
3b80e3aa | 219 | when the complete responder certificate chain is not available or trusting a |
cc5ba6a7 DSH |
220 | root CA is not appropriate. |
221 | ||
222 | =item B<-VAfile file> | |
223 | ||
224 | file containing explicitly trusted responder certificates. Equivalent to the | |
0d7f6fc7 | 225 | B<-verify_other> and B<-trust_other> options. |
cc5ba6a7 | 226 | |
bfcec27d DSH |
227 | =item B<-noverify> |
228 | ||
cc5ba6a7 DSH |
229 | don't attempt to verify the OCSP response signature or the nonce values. This |
230 | option will normally only be used for debugging since it disables all verification | |
231 | of the responders certificate. | |
232 | ||
233 | =item B<-no_intern> | |
234 | ||
235 | ignore certificates contained in the OCSP response when searching for the | |
236 | signers certificate. With this option the signers certificate must be specified | |
0d7f6fc7 | 237 | with either the B<-verify_other> or B<-VAfile> options. |
cc5ba6a7 | 238 | |
e5b0508a | 239 | =item B<-no_signature_verify> |
cc5ba6a7 DSH |
240 | |
241 | don't check the signature on the OCSP response. Since this option tolerates invalid | |
3b80e3aa | 242 | signatures on OCSP responses it will normally only be used for testing purposes. |
cc5ba6a7 DSH |
243 | |
244 | =item B<-no_cert_verify> | |
245 | ||
3b80e3aa | 246 | don't verify the OCSP response signers certificate at all. Since this option allows |
cc5ba6a7 DSH |
247 | the OCSP response to be signed by any certificate it should only be used for |
248 | testing purposes. | |
249 | ||
250 | =item B<-no_chain> | |
251 | ||
252 | do not use certificates in the response as additional untrusted CA | |
253 | certificates. | |
254 | ||
384dee51 DSH |
255 | =item B<-no_explicit> |
256 | ||
257 | do not explicitly trust the root CA if it is set to be trusted for OCSP signing. | |
258 | ||
cc5ba6a7 DSH |
259 | =item B<-no_cert_checks> |
260 | ||
261 | don't perform any additional checks on the OCSP response signers certificate. | |
262 | That is do not make any checks to see if the signers certificate is authorised | |
3b80e3aa | 263 | to provide the necessary status information: as a result this option should |
cc5ba6a7 DSH |
264 | only be used for testing purposes. |
265 | ||
266 | =item B<-validity_period nsec>, B<-status_age age> | |
267 | ||
268 | these options specify the range of times, in seconds, which will be tolerated | |
6302bbd2 DSH |
269 | in an OCSP response. Each certificate status response includes a B<notBefore> |
270 | time and an optional B<notAfter> time. The current time should fall between | |
271 | these two values, but the interval between the two times may be only a few | |
272 | seconds. In practice the OCSP responder and clients clocks may not be precisely | |
273 | synchronised and so such a check may fail. To avoid this the | |
274 | B<-validity_period> option can be used to specify an acceptable error range in | |
275 | seconds, the default value is 5 minutes. | |
276 | ||
277 | If the B<notAfter> time is omitted from a response then this means that new | |
278 | status information is immediately available. In this case the age of the | |
279 | B<notBefore> field is checked to see it is not older than B<age> seconds old. | |
280 | By default this additional check is not performed. | |
bfcec27d | 281 | |
c03726ca | 282 | =item B<-[digest]> |
cec2538c | 283 | |
6302bbd2 DSH |
284 | this option sets digest algorithm to use for certificate identification in the |
285 | OCSP request. Any digest supported by the OpenSSL B<dgst> command can be used. | |
286 | The default is SHA-1. This option may be used multiple times to specify the | |
287 | digest used by subsequent certificate identifiers. | |
cec2538c | 288 | |
b4b1bdd5 DSH |
289 | =back |
290 | ||
534a1ed0 DSH |
291 | =head1 OCSP SERVER OPTIONS |
292 | ||
293 | =over 4 | |
294 | ||
295 | =item B<-index indexfile> | |
296 | ||
297 | B<indexfile> is a text index file in B<ca> format containing certificate revocation | |
298 | information. | |
299 | ||
300 | If the B<index> option is specified the B<ocsp> utility is in responder mode, otherwise | |
301 | it is in client mode. The request(s) the responder processes can be either specified on | |
302 | the command line (using B<issuer> and B<serial> options), supplied in a file (using the | |
21c6c50f | 303 | B<reqin> option) or via external OCSP clients (if B<port> or B<url> is specified). |
534a1ed0 DSH |
304 | |
305 | If the B<index> option is present then the B<CA> and B<rsigner> options must also be | |
306 | present. | |
307 | ||
308 | =item B<-CA file> | |
309 | ||
310 | CA certificate corresponding to the revocation information in B<indexfile>. | |
311 | ||
312 | =item B<-rsigner file> | |
313 | ||
314 | The certificate to sign OCSP responses with. | |
315 | ||
316 | =item B<-rother file> | |
317 | ||
318 | Additional certificates to include in the OCSP response. | |
319 | ||
320 | =item B<-resp_no_certs> | |
321 | ||
322 | Don't include any certificates in the OCSP response. | |
323 | ||
324 | =item B<-resp_key_id> | |
325 | ||
326 | Identify the signer certificate using the key ID, default is to use the subject name. | |
327 | ||
328 | =item B<-rkey file> | |
329 | ||
330 | The private key to sign OCSP responses with: if not present the file specified in the | |
331 | B<rsigner> option is used. | |
332 | ||
333 | =item B<-port portnum> | |
334 | ||
335 | Port to listen for OCSP requests on. The port may also be specified using the B<url> | |
336 | option. | |
337 | ||
338 | =item B<-nrequest number> | |
339 | ||
1bc74519 | 340 | The OCSP server will exit after receiving B<number> requests, default unlimited. |
534a1ed0 DSH |
341 | |
342 | =item B<-nmin minutes>, B<-ndays days> | |
343 | ||
344 | Number of minutes or days when fresh revocation information is available: used in the | |
1bc74519 RS |
345 | B<nextUpdate> field. If neither option is present then the B<nextUpdate> field |
346 | is omitted meaning fresh revocation information is immediately available. | |
534a1ed0 DSH |
347 | |
348 | =back | |
349 | ||
bfcec27d DSH |
350 | =head1 OCSP Response verification. |
351 | ||
352 | OCSP Response follows the rules specified in RFC2560. | |
353 | ||
354 | Initially the OCSP responder certificate is located and the signature on | |
3b80e3aa | 355 | the OCSP request checked using the responder certificate's public key. |
bfcec27d DSH |
356 | |
357 | Then a normal certificate verify is performed on the OCSP responder certificate | |
358 | building up a certificate chain in the process. The locations of the trusted | |
359 | certificates used to build the chain can be specified by the B<CAfile> | |
360 | and B<CApath> options or they will be looked for in the standard OpenSSL | |
361 | certificates directory. | |
362 | ||
363 | If the initial verify fails then the OCSP verify process halts with an | |
364 | error. | |
365 | ||
366 | Otherwise the issuing CA certificate in the request is compared to the OCSP | |
367 | responder certificate: if there is a match then the OCSP verify succeeds. | |
368 | ||
369 | Otherwise the OCSP responder certificate's CA is checked against the issuing | |
370 | CA certificate in the request. If there is a match and the OCSPSigning | |
371 | extended key usage is present in the OCSP responder certificate then the | |
372 | OCSP verify succeeds. | |
373 | ||
384dee51 DSH |
374 | Otherwise, if B<-no_explicit> is B<not> set the root CA of the OCSP responders |
375 | CA is checked to see if it is trusted for OCSP signing. If it is the OCSP | |
376 | verify succeeds. | |
bfcec27d DSH |
377 | |
378 | If none of these checks is successful then the OCSP verify fails. | |
379 | ||
380 | What this effectively means if that if the OCSP responder certificate is | |
381 | authorised directly by the CA it is issuing revocation information about | |
382 | (and it is correctly configured) then verification will succeed. | |
383 | ||
384 | If the OCSP responder is a "global responder" which can give details about | |
385 | multiple CAs and has its own separate certificate chain then its root | |
cc5ba6a7 | 386 | CA can be trusted for OCSP signing. For example: |
bfcec27d DSH |
387 | |
388 | openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem | |
389 | ||
cc5ba6a7 DSH |
390 | Alternatively the responder certificate itself can be explicitly trusted |
391 | with the B<-VAfile> option. | |
b4b1bdd5 | 392 | |
cc5ba6a7 | 393 | =head1 NOTES |
b4b1bdd5 | 394 | |
cc5ba6a7 DSH |
395 | As noted, most of the verify options are for testing or debugging purposes. |
396 | Normally only the B<-CApath>, B<-CAfile> and (if the responder is a 'global | |
397 | VA') B<-VAfile> options need to be used. | |
b4b1bdd5 | 398 | |
534a1ed0 DSH |
399 | The OCSP server is only useful for test and demonstration purposes: it is |
400 | not really usable as a full OCSP responder. It contains only a very | |
401 | simple HTTP request handling and can only handle the POST form of OCSP | |
402 | queries. It also handles requests serially meaning it cannot respond to | |
403 | new requests until it has processed the current one. The text index file | |
404 | format of revocation is also inefficient for large quantities of revocation | |
405 | data. | |
406 | ||
407 | It is possible to run the B<ocsp> application in responder mode via a CGI | |
21c6c50f | 408 | script using the B<reqin> and B<respout> options. |
534a1ed0 | 409 | |
b4b1bdd5 DSH |
410 | =head1 EXAMPLES |
411 | ||
412 | Create an OCSP request and write it to a file: | |
413 | ||
414 | openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der | |
415 | ||
1bc74519 | 416 | Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the |
21c6c50f | 417 | response to a file, print it out in text form, and verify the response: |
b4b1bdd5 DSH |
418 | |
419 | openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \ | |
cc5ba6a7 | 420 | -url http://ocsp.myhost.com/ -resp_text -respout resp.der |
b4b1bdd5 DSH |
421 | |
422 | Read in an OCSP response and print out text form: | |
423 | ||
21c6c50f | 424 | openssl ocsp -respin resp.der -text -noverify |
b4b1bdd5 | 425 | |
534a1ed0 DSH |
426 | OCSP server on port 8888 using a standard B<ca> configuration, and a separate |
427 | responder certificate. All requests and responses are printed to a file. | |
428 | ||
429 | openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem | |
1bc74519 | 430 | -text -out log.txt |
534a1ed0 DSH |
431 | |
432 | As above but exit after processing one request: | |
433 | ||
434 | openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem | |
435 | -nrequest 1 | |
436 | ||
21c6c50f | 437 | Query status information using an internally generated request: |
534a1ed0 DSH |
438 | |
439 | openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem | |
440 | -issuer demoCA/cacert.pem -serial 1 | |
441 | ||
21c6c50f BK |
442 | Query status information using request read from a file, and write the response |
443 | to a second file. | |
534a1ed0 DSH |
444 | |
445 | openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem | |
446 | -reqin req.der -respout resp.der | |
fa7b0111 MC |
447 | |
448 | =head1 HISTORY | |
449 | ||
450 | The -no_alt_chains options was first added to OpenSSL 1.1.0. | |
451 | ||
452 | =cut | |
e2f92610 RS |
453 | |
454 | =head1 COPYRIGHT | |
455 | ||
456 | Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. | |
457 | ||
458 | Licensed under the OpenSSL license (the "License"). You may not use | |
459 | this file except in compliance with the License. You can obtain a copy | |
460 | in the file LICENSE in the source distribution or at | |
461 | L<https://www.openssl.org/source/license.html>. | |
462 | ||
463 | =cut |