doc/man1/openssl-ocsp.pod.in

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