[B<-issuer file>]
[B<-cert file>]
[B<-serial n>]
+[B<-signer file>]
+[B<-signkey file>]
+[B<-sign_other file>]
+[B<-no_certs>]
[B<-req_text>]
[B<-resp_text>]
[B<-text>]
[B<-respin file>]
[B<-nonce>]
[B<-no_nonce>]
-[B<-host host:n>]
+[B<-url URL>]
+[B<-host host:port>]
+[B<-header>]
[B<-path>]
-[B<-CApath file>]
+[B<-CApath dir>]
[B<-CAfile file>]
+[B<-no-CAfile>]
+[B<-no-CApath>]
+[B<-attime timestamp>]
+[B<-check_ss_sig>]
+[B<-crl_check>]
+[B<-crl_check_all>]
+[B<-explicit_policy>]
+[B<-extended_crl>]
+[B<-ignore_critical>]
+[B<-inhibit_any>]
+[B<-inhibit_map>]
+[B<-issuer_checks>]
+[B<-partial_chain>]
+[B<-policy arg>]
+[B<-policy_check>]
+[B<-policy_print>]
+[B<-purpose purpose>]
+[B<-suiteB_128>]
+[B<-suiteB_128_only>]
+[B<-suiteB_192>]
+[B<-trusted_first>]
+[B<-no_alt_chains>]
+[B<-use_deltas>]
+[B<-verify_depth num>]
+[B<-verify_email email>]
+[B<-verify_hostname hostname>]
+[B<-verify_ip ip>]
+[B<-verify_name name>]
+[B<-x509_strict>]
+[B<-VAfile file>]
+[B<-validity_period n>]
+[B<-status_age n>]
[B<-noverify>]
+[B<-verify_other file>]
+[B<-trust_other>]
+[B<-no_intern>]
+[B<-no_signature_verify>]
+[B<-no_cert_verify>]
+[B<-no_chain>]
+[B<-no_cert_checks>]
+[B<-no_explicit>]
+[B<-port num>]
+[B<-index file>]
+[B<-CA file>]
+[B<-rsigner file>]
+[B<-rkey file>]
+[B<-rother file>]
+[B<-resp_no_certs>]
+[B<-nmin n>]
+[B<-ndays n>]
+[B<-resp_key_id>]
+[B<-nrequest n>]
+[B<-md5|-sha1|...>]
=head1 DESCRIPTION
-B<WARNING: this documentation is preliminary and subject to change.>
-
The Online Certificate Status Protocol (OCSP) enables applications to
determine the (revocation) state of an identified certificate (RFC 2560).
The B<ocsp> command performs many common OCSP tasks. It can be used
to print out requests and responses, create requests and send queries
-to an OCSP responder.
+to an OCSP responder and behave like a mini OCSP server itself.
-=head1 OPTIONS
+=head1 OCSP CLIENT OPTIONS
=over 4
This specifies the current issuer certificate. This option can be used
multiple times. The certificate specified in B<filename> must be in
-PEM format.
+PEM format. This option B<MUST> come before any B<-cert> options.
=item B<-cert filename>
from the same file as the certificate. If neither option is specified then
the OCSP request is not signed.
+=item B<-sign_other filename>
+
+Additional certificates to include in the signed request.
+
=item B<-nonce>, B<-no_nonce>
Add an OCSP nonce extension to a request or disable OCSP nonce addition.
=item B<-req_text>, B<-resp_text>, B<-text>
-print out the text form of the OCSP request, reponse or both respectively.
+print out the text form of the OCSP request, response or both respectively.
=item B<-reqout file>, B<-respout file>
if OCSP request or response creation is implied by other options (for example
with B<serial>, B<cert> and B<host> options).
+=item B<-url responder_url>
+
+specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified.
+
=item B<-host hostname:port>, B<-path pathname>
if the B<host> option is present then the OCSP request is sent to the host
B<hostname> on port B<port>. B<path> specifies the HTTP path name to use
or "/" by default.
+=item B<-header name=value>
+
+Adds the header B<name> with the specified B<value> to the OCSP request
+that is sent to the responder.
+This may be repeated.
+
+=item B<-timeout seconds>
+
+connection timeout to the OCSP responder in seconds
+
=item B<-CAfile file>, B<-CApath pathname>
file or pathname containing trusted CA certificates. These are used to verify
the signature on the OCSP response.
+=item B<-no-CAfile>
+
+Do not load the trusted CA certificates from the default file location
+
+=item B<-no-CApath>
+
+Do not load the trusted CA certificates from the default directory location
+
+=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
+B<explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
+B<-inhibit_map>, B<-issuer_checks>, B<-partial_chain>, B<-policy>,
+B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
+B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-no_alt_chains>,
+B<-use_deltas>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
+B<-verify_ip>, B<-verify_name>, B<-x509_strict>
+
+Set different certificate verification options.
+See L<B<verify>|verify(1)> manual page for details.
+
+=item B<-verify_other file>
+
+file containing additional certificates to search when attempting to locate
+the OCSP response signing certificate. Some responders omit the actual signer's
+certificate from the response: this option can be used to supply the necessary
+certificate in such cases.
+
+=item B<-trust_other>
+
+the certificates specified by the B<-verify_other> option should be explicitly
+trusted and no additional checks will be performed on them. This is useful
+when the complete responder certificate chain is not available or trusting a
+root CA is not appropriate.
+
+=item B<-VAfile file>
+
+file containing explicitly trusted responder certificates. Equivalent to the
+B<-verify_other> and B<-trust_other> options.
+
=item B<-noverify>
-don't attempt to verify the OCSP response signature or the nonce values.
+don't attempt to verify the OCSP response signature or the nonce values. This
+option will normally only be used for debugging since it disables all verification
+of the responders certificate.
+
+=item B<-no_intern>
+
+ignore certificates contained in the OCSP response when searching for the
+signers certificate. With this option the signers certificate must be specified
+with either the B<-verify_other> or B<-VAfile> options.
+
+=item B<-no_signature_verify>
+
+don't check the signature on the OCSP response. Since this option tolerates invalid
+signatures on OCSP responses it will normally only be used for testing purposes.
+
+=item B<-no_cert_verify>
+
+don't verify the OCSP response signers certificate at all. Since this option allows
+the OCSP response to be signed by any certificate it should only be used for
+testing purposes.
+
+=item B<-no_chain>
+
+do not use certificates in the response as additional untrusted CA
+certificates.
+
+=item B<-no_explicit>
+
+do not explicitly trust the root CA if it is set to be trusted for OCSP signing.
+
+=item B<-no_cert_checks>
+
+don't perform any additional checks on the OCSP response signers certificate.
+That is do not make any checks to see if the signers certificate is authorised
+to provide the necessary status information: as a result this option should
+only be used for testing purposes.
+
+=item B<-validity_period nsec>, B<-status_age age>
+
+these options specify the range of times, in seconds, which will be tolerated
+in an OCSP response. Each certificate status response includes a B<notBefore> time and
+an optional B<notAfter> time. The current time should fall between these two values, but
+the interval between the two times may be only a few seconds. In practice the OCSP
+responder and clients clocks may not be precisely synchronised and so such a check
+may fail. To avoid this the B<-validity_period> option can be used to specify an
+acceptable error range in seconds, the default value is 5 minutes.
+
+If the B<notAfter> time is omitted from a response then this means that new status
+information is immediately available. In this case the age of the B<notBefore> field
+is checked to see it is not older than B<age> seconds old. By default this additional
+check is not performed.
+
+=item B<-[digest]>
+
+this option sets digest algorithm to use for certificate identification
+in the OCSP request.
+Any digest supported by the OpenSSL B<dgst> command can be used.
+The default is SHA-1.
+
+=back
+
+=head1 OCSP SERVER OPTIONS
+
+=over 4
+
+=item B<-index indexfile>
+
+B<indexfile> is a text index file in B<ca> format containing certificate revocation
+information.
+
+If the B<index> option is specified the B<ocsp> utility is in responder mode, otherwise
+it is in client mode. The request(s) the responder processes can be either specified on
+the command line (using B<issuer> and B<serial> options), supplied in a file (using the
+B<respin> option) or via external OCSP clients (if B<port> or B<url> is specified).
+
+If the B<index> option is present then the B<CA> and B<rsigner> options must also be
+present.
+
+=item B<-CA file>
+
+CA certificate corresponding to the revocation information in B<indexfile>.
+
+=item B<-rsigner file>
+
+The certificate to sign OCSP responses with.
+
+=item B<-rother file>
+
+Additional certificates to include in the OCSP response.
+
+=item B<-resp_no_certs>
+
+Don't include any certificates in the OCSP response.
+
+=item B<-resp_key_id>
+
+Identify the signer certificate using the key ID, default is to use the subject name.
+
+=item B<-rkey file>
+
+The private key to sign OCSP responses with: if not present the file specified in the
+B<rsigner> option is used.
+
+=item B<-port portnum>
+
+Port to listen for OCSP requests on. The port may also be specified using the B<url>
+option.
+
+=item B<-nrequest number>
+
+The OCSP server will exit after receiving B<number> requests, default unlimited.
+
+=item B<-nmin minutes>, B<-ndays days>
+
+Number of minutes or days when fresh revocation information is available: used in the
+B<nextUpdate> field. If neither option is present then the B<nextUpdate> field is
+omitted meaning fresh revocation information is immediately available.
=back
OCSP Response follows the rules specified in RFC2560.
Initially the OCSP responder certificate is located and the signature on
-the OCSP request checked using the reponder certificate's public key.
+the OCSP request checked using the responder certificate's public key.
Then a normal certificate verify is performed on the OCSP responder certificate
building up a certificate chain in the process. The locations of the trusted
extended key usage is present in the OCSP responder certificate then the
OCSP verify succeeds.
-Otherwise the root CA of the OCSP responders CA is checked to see if it
-is trusted for OCSP signing. If it is the OCSP verify succeeds.
+Otherwise, if B<-no_explicit> is B<not> set the root CA of the OCSP responders
+CA is checked to see if it is trusted for OCSP signing. If it is the OCSP
+verify succeeds.
If none of these checks is successful then the OCSP verify fails.
If the OCSP responder is a "global responder" which can give details about
multiple CAs and has its own separate certificate chain then its root
-CA must be trusted for OCSP signing. For example:
+CA can be trusted for OCSP signing. For example:
openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem
-=head1 NOTES
+Alternatively the responder certificate itself can be explicitly trusted
+with the B<-VAfile> option.
-The B<-host> and B<-path> options specify the relevant parts of the OCSP
-URI. For example the OCSP responder URL:
+=head1 NOTES
-http://ocsp.myhost.com/ocsp/request
+As noted, most of the verify options are for testing or debugging purposes.
+Normally only the B<-CApath>, B<-CAfile> and (if the responder is a 'global
+VA') B<-VAfile> options need to be used.
-corresponds to the the options:
+The OCSP server is only useful for test and demonstration purposes: it is
+not really usable as a full OCSP responder. It contains only a very
+simple HTTP request handling and can only handle the POST form of OCSP
+queries. It also handles requests serially meaning it cannot respond to
+new requests until it has processed the current one. The text index file
+format of revocation is also inefficient for large quantities of revocation
+data.
- -host ocsp.myhost.com:80 -path /ocsp/request
+It is possible to run the B<ocsp> application in responder mode via a CGI
+script using the B<respin> and B<respout> options.
=head1 EXAMPLES
openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der
-Send a query an OCSP responder with URL http://ocsp.myhost.com/ save the
+Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the
response to a file and print it out in text form
openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \
- -host ocsp.myhost.com:80 -resp_text -respout resp.der
+ -url http://ocsp.myhost.com/ -resp_text -respout resp.der
Read in an OCSP response and print out text form:
openssl ocsp -respin resp.der -text
-=head1 BUGS
+OCSP server on port 8888 using a standard B<ca> configuration, and a separate
+responder certificate. All requests and responses are printed to a file.
+
+ openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
+ -text -out log.txt
+
+As above but exit after processing one request:
+
+ openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
+ -nrequest 1
+
+Query status information using internally generated request:
+
+ openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
+ -issuer demoCA/cacert.pem -serial 1
+
+Query status information using request read from a file, write response to a
+second file.
+
+ openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
+ -reqin req.der -respout resp.der
-This utility is incomplete. It currently does not completely check the OCSP
-response's: it does not check the validity dates for example.
+=head1 HISTORY
-The B<host> and B<path> options may well go away and be replaced by a B<url>
-option or an option to determine the URI based on certificate extensions.
+The -no_alt_chains options was first added to OpenSSL 1.1.0.
-SSL OCSP responders using https URLs cannot currently be queried.
+=cut
projects / openssl.git / blobdiff