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