doc/apps/ocsp.pod

=pod

=head1 NAME

ocsp - Online Certificate Status Protocol utility

=head1 SYNOPSIS

B<openssl> B<ocsp>
[B<-out file>]
[B<-issuer file>]
[B<-cert file>]
[B<-serial n>]
[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>]
[B<-host host:n>]
[B<-path>]
[B<-CApath file>]
[B<-CAfile file>]
[B<-noverify>]

=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.

=head1 OPTIONS

=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
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.

=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.

=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>

print out the text form of the OCSP request, reponse or both respectively.

=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).

=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<-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<-noverify>

don't attempt to verify the OCSP response signature or the nonce values.

=back

=head1 OCSP Response verification.

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.

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
CA must be trusted for OCSP signing. For example:

 openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem

=head1 NOTES

The B<-host> and B<-path> options specify the relevant parts of the OCSP
URI. For example the OCSP responder URL:

http://ocsp.myhost.com/ocsp/request

corresponds to the the options:

 -host ocsp.myhost.com:80 -path /ocsp/request

=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

Send a query 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

Read in an OCSP response and print out text form:

 openssl ocsp -respin resp.der -text

=head1 BUGS

This utility is incomplete. It currently does not completely check the OCSP
response's: it does not check the validity dates for example.

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.

SSL OCSP responders using https URLs cannot currently be queried.