2001-01-14 08:52:19 +08:00
|
|
|
=pod
|
|
|
|
|
|
|
|
=head1 NAME
|
|
|
|
|
2001-01-16 06:19:30 +08:00
|
|
|
ocsp - Online Certificate Status Protocol utility
|
2001-01-14 08:52:19 +08:00
|
|
|
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
|
|
|
|
B<openssl> B<ocsp>
|
|
|
|
[B<-out file>]
|
|
|
|
[B<-issuer file>]
|
|
|
|
[B<-cert file>]
|
|
|
|
[B<-serial n>]
|
2003-03-26 08:46:47 +08:00
|
|
|
[B<-signer file>]
|
|
|
|
[B<-signkey file>]
|
|
|
|
[B<-sign_other file>]
|
|
|
|
[B<-no_certs>]
|
2001-01-14 08:52:19 +08:00
|
|
|
[B<-req_text>]
|
|
|
|
[B<-resp_text>]
|
|
|
|
[B<-text>]
|
|
|
|
[B<-reqout file>]
|
|
|
|
[B<-respout file>]
|
|
|
|
[B<-reqin file>]
|
|
|
|
[B<-respin file>]
|
|
|
|
[B<-nonce>]
|
|
|
|
[B<-no_nonce>]
|
2003-03-26 08:46:47 +08:00
|
|
|
[B<-url URL>]
|
2001-01-14 08:52:19 +08:00
|
|
|
[B<-host host:n>]
|
|
|
|
[B<-path>]
|
2003-03-26 08:46:47 +08:00
|
|
|
[B<-CApath dir>]
|
2001-01-20 09:26:28 +08:00
|
|
|
[B<-CAfile file>]
|
2001-03-09 21:57:14 +08:00
|
|
|
[B<-VAfile file>]
|
2003-03-26 08:46:47 +08:00
|
|
|
[B<-validity_period n>]
|
|
|
|
[B<-status_age n>]
|
2001-01-20 09:26:28 +08:00
|
|
|
[B<-noverify>]
|
2003-03-26 08:46:47 +08:00
|
|
|
[B<-verify_other file>]
|
2001-03-09 21:57:14 +08:00
|
|
|
[B<-trust_other>]
|
|
|
|
[B<-no_intern>]
|
2003-03-26 08:46:47 +08:00
|
|
|
[B<-no_signature_verify>]
|
2001-03-09 21:57:14 +08:00
|
|
|
[B<-no_cert_verify>]
|
|
|
|
[B<-no_chain>]
|
|
|
|
[B<-no_cert_checks>]
|
2003-03-26 08:46:47 +08:00
|
|
|
[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>]
|
2001-01-14 08:52:19 +08:00
|
|
|
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
|
2001-01-16 06:19:30 +08:00
|
|
|
The Online Certificate Status Protocol (OCSP) enables applications to
|
|
|
|
determine the (revocation) state of an identified certificate (RFC 2560).
|
|
|
|
|
2001-01-14 08:52:19 +08:00
|
|
|
The B<ocsp> command performs many common OCSP tasks. It can be used
|
|
|
|
to print out requests and responses, create requests and send queries
|
2001-07-13 21:13:44 +08:00
|
|
|
to an OCSP responder and behave like a mini OCSP server itself.
|
2001-01-14 08:52:19 +08:00
|
|
|
|
2001-07-13 21:13:44 +08:00
|
|
|
=head1 OCSP CLIENT OPTIONS
|
2001-01-14 08:52:19 +08:00
|
|
|
|
|
|
|
=over 4
|
|
|
|
|
|
|
|
=item B<-out filename>
|
|
|
|
|
|
|
|
specify output filename, default is standard output.
|
|
|
|
|
|
|
|
=item B<-issuer filename>
|
|
|
|
|
|
|
|
This specifies the current issuer certificate. This option can be used
|
|
|
|
multiple times. The certificate specified in B<filename> must be in
|
|
|
|
PEM format.
|
|
|
|
|
|
|
|
=item B<-cert filename>
|
|
|
|
|
|
|
|
Add the certificate B<filename> to the request. The issuer certificate
|
|
|
|
is taken from the previous B<issuer> option, or an error occurs if no
|
|
|
|
issuer certificate is specified.
|
|
|
|
|
|
|
|
=item B<-serial num>
|
|
|
|
|
|
|
|
Same as the B<cert> option except the certificate with serial number
|
2001-01-20 09:26:28 +08:00
|
|
|
B<num> is added to the request. The serial number is interpreted as a
|
|
|
|
decimal integer unless preceded by B<0x>. Negative integers can also
|
|
|
|
be specified by preceding the value by a B<-> sign.
|
2001-01-14 08:52:19 +08:00
|
|
|
|
|
|
|
=item B<-signer filename>, B<-signkey filename>
|
|
|
|
|
|
|
|
Sign the OCSP request using the certificate specified in the B<signer>
|
|
|
|
option and the private key specified by the B<signkey> option. If
|
|
|
|
the B<signkey> option is not present then the private key is read
|
|
|
|
from the same file as the certificate. If neither option is specified then
|
|
|
|
the OCSP request is not signed.
|
|
|
|
|
2003-03-26 08:46:47 +08:00
|
|
|
=item B<-sign_other filename>
|
|
|
|
|
|
|
|
Additional certificates to include in the signed request.
|
|
|
|
|
2001-01-14 08:52:19 +08:00
|
|
|
=item B<-nonce>, B<-no_nonce>
|
|
|
|
|
|
|
|
Add an OCSP nonce extension to a request or disable OCSP nonce addition.
|
|
|
|
Normally if an OCSP request is input using the B<respin> option no
|
|
|
|
nonce is added: using the B<nonce> option will force addition of a nonce.
|
|
|
|
If an OCSP request is being created (using B<cert> and B<serial> options)
|
|
|
|
a nonce is automatically added specifying B<no_nonce> overrides this.
|
|
|
|
|
|
|
|
=item B<-req_text>, B<-resp_text>, B<-text>
|
|
|
|
|
2001-09-07 14:13:40 +08:00
|
|
|
print out the text form of the OCSP request, response or both respectively.
|
2001-01-14 08:52:19 +08:00
|
|
|
|
|
|
|
=item B<-reqout file>, B<-respout file>
|
|
|
|
|
|
|
|
write out the DER encoded certificate request or response to B<file>.
|
|
|
|
|
|
|
|
=item B<-reqin file>, B<-respin file>
|
|
|
|
|
|
|
|
read OCSP request or response file from B<file>. These option are ignored
|
|
|
|
if OCSP request or response creation is implied by other options (for example
|
|
|
|
with B<serial>, B<cert> and B<host> options).
|
|
|
|
|
2001-03-09 21:57:14 +08:00
|
|
|
=item B<-url responder_url>
|
|
|
|
|
|
|
|
specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified.
|
|
|
|
|
2001-01-14 08:52:19 +08:00
|
|
|
=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.
|
|
|
|
|
2001-01-20 09:26:28 +08:00
|
|
|
=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.
|
|
|
|
|
2003-03-26 08:46:47 +08:00
|
|
|
=item B<-verify_other file>
|
2001-03-09 21:57:14 +08:00
|
|
|
|
|
|
|
file containing additional certificates to search when attempting to locate
|
|
|
|
the OCSP response signing certificate. Some responders omit the actual signer's
|
2001-09-07 14:13:40 +08:00
|
|
|
certificate from the response: this option can be used to supply the necessary
|
2001-03-09 21:57:14 +08:00
|
|
|
certificate in such cases.
|
|
|
|
|
|
|
|
=item B<-trust_other>
|
|
|
|
|
|
|
|
the certificates specified by the B<-verify_certs> option should be explicitly
|
|
|
|
trusted and no additional checks will be performed on them. This is useful
|
2001-09-07 14:13:40 +08:00
|
|
|
when the complete responder certificate chain is not available or trusting a
|
2001-03-09 21:57:14 +08:00
|
|
|
root CA is not appropriate.
|
|
|
|
|
|
|
|
=item B<-VAfile file>
|
|
|
|
|
|
|
|
file containing explicitly trusted responder certificates. Equivalent to the
|
|
|
|
B<-verify_certs> and B<-trust_other> options.
|
|
|
|
|
2001-01-20 09:26:28 +08:00
|
|
|
=item B<-noverify>
|
|
|
|
|
2001-03-09 21:57:14 +08:00
|
|
|
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_certs> or B<-VAfile> options.
|
|
|
|
|
2003-03-26 08:46:47 +08:00
|
|
|
=item B<-no_signature_verify>
|
2001-03-09 21:57:14 +08:00
|
|
|
|
|
|
|
don't check the signature on the OCSP response. Since this option tolerates invalid
|
2001-09-07 14:13:40 +08:00
|
|
|
signatures on OCSP responses it will normally only be used for testing purposes.
|
2001-03-09 21:57:14 +08:00
|
|
|
|
|
|
|
=item B<-no_cert_verify>
|
|
|
|
|
2001-09-07 14:13:40 +08:00
|
|
|
don't verify the OCSP response signers certificate at all. Since this option allows
|
2001-03-09 21:57:14 +08:00
|
|
|
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_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
|
2001-09-07 14:13:40 +08:00
|
|
|
to provide the necessary status information: as a result this option should
|
2001-03-09 21:57:14 +08:00
|
|
|
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.
|
2001-01-20 09:26:28 +08:00
|
|
|
|
2001-01-14 08:52:19 +08:00
|
|
|
=back
|
|
|
|
|
2001-07-13 21:13:44 +08:00
|
|
|
=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
|
|
|
|
|
2001-01-20 09:26:28 +08:00
|
|
|
=head1 OCSP Response verification.
|
|
|
|
|
|
|
|
OCSP Response follows the rules specified in RFC2560.
|
|
|
|
|
|
|
|
Initially the OCSP responder certificate is located and the signature on
|
2001-09-07 14:13:40 +08:00
|
|
|
the OCSP request checked using the responder certificate's public key.
|
2001-01-20 09:26:28 +08:00
|
|
|
|
|
|
|
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
|
|
|
|
certificates used to build the chain can be specified by the B<CAfile>
|
|
|
|
and B<CApath> options or they will be looked for in the standard OpenSSL
|
|
|
|
certificates directory.
|
|
|
|
|
|
|
|
If the initial verify fails then the OCSP verify process halts with an
|
|
|
|
error.
|
|
|
|
|
|
|
|
Otherwise the issuing CA certificate in the request is compared to the OCSP
|
|
|
|
responder certificate: if there is a match then the OCSP verify succeeds.
|
|
|
|
|
|
|
|
Otherwise the OCSP responder certificate's CA is checked against the issuing
|
|
|
|
CA certificate in the request. If there is a match and the OCSPSigning
|
|
|
|
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.
|
|
|
|
|
|
|
|
If none of these checks is successful then the OCSP verify fails.
|
|
|
|
|
|
|
|
What this effectively means if that if the OCSP responder certificate is
|
|
|
|
authorised directly by the CA it is issuing revocation information about
|
|
|
|
(and it is correctly configured) then verification will succeed.
|
|
|
|
|
|
|
|
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
|
2001-03-09 21:57:14 +08:00
|
|
|
CA can be trusted for OCSP signing. For example:
|
2001-01-20 09:26:28 +08:00
|
|
|
|
|
|
|
openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem
|
|
|
|
|
2001-03-09 21:57:14 +08:00
|
|
|
Alternatively the responder certificate itself can be explicitly trusted
|
|
|
|
with the B<-VAfile> option.
|
2001-01-14 08:52:19 +08:00
|
|
|
|
2001-03-09 21:57:14 +08:00
|
|
|
=head1 NOTES
|
2001-01-14 08:52:19 +08:00
|
|
|
|
2001-03-09 21:57:14 +08:00
|
|
|
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.
|
2001-01-14 08:52:19 +08:00
|
|
|
|
2001-07-13 21:13:44 +08:00
|
|
|
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.
|
|
|
|
|
|
|
|
It is possible to run the B<ocsp> application in responder mode via a CGI
|
|
|
|
script using the B<respin> and B<respout> options.
|
|
|
|
|
2001-01-14 08:52:19 +08:00
|
|
|
=head1 EXAMPLES
|
|
|
|
|
|
|
|
Create an OCSP request and write it to a file:
|
|
|
|
|
|
|
|
openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der
|
|
|
|
|
2001-07-13 21:13:44 +08:00
|
|
|
Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the
|
2001-01-14 08:52:19 +08:00
|
|
|
response to a file and print it out in text form
|
|
|
|
|
|
|
|
openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \
|
2001-03-09 21:57:14 +08:00
|
|
|
-url http://ocsp.myhost.com/ -resp_text -respout resp.der
|
2001-01-14 08:52:19 +08:00
|
|
|
|
|
|
|
Read in an OCSP response and print out text form:
|
|
|
|
|
|
|
|
openssl ocsp -respin resp.der -text
|
|
|
|
|
2001-07-13 21:13:44 +08:00
|
|
|
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
|