doc/apps/ocsp.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ocsp - Online Certificate Status Protocol utility
   6
   7 =head1 SYNOPSIS
   8
   9 B<openssl> B<ocsp>
  10 [B<-out file>]
  11 [B<-issuer file>]
  12 [B<-cert file>]
  13 [B<-serial n>]
  14 [B<-req_text>]
  15 [B<-resp_text>]
  16 [B<-text>]
  17 [B<-reqout file>]
  18 [B<-respout file>]
  19 [B<-reqin file>]
  20 [B<-respin file>]
  21 [B<-nonce>]
  22 [B<-no_nonce>]
  23 [B<-host host:n>]
  24 [B<-path>]
  25 [B<-CApath file>]
  26 [B<-CAfile file>]
  27 [B<-noverify>]
  28
  29 =head1 DESCRIPTION
  30
  31 B<WARNING: this documentation is preliminary and subject to change.>
  32
  33 The Online Certificate Status Protocol (OCSP) enables applications to
  34 determine the (revocation) state of an identified certificate (RFC 2560).
  35
  36 The B<ocsp> command performs many common OCSP tasks. It can be used
  37 to print out requests and responses, create requests and send queries
  38 to an OCSP responder.
  39
  40 =head1 OPTIONS
  41
  42 =over 4
  43
  44 =item B<-out filename>
  45
  46 specify output filename, default is standard output.
  47
  48 =item B<-issuer filename>
  49
  50 This specifies the current issuer certificate. This option can be used
  51 multiple times. The certificate specified in B<filename> must be in
  52 PEM format.
  53
  54 =item B<-cert filename>
  55
  56 Add the certificate B<filename> to the request. The issuer certificate
  57 is taken from the previous B<issuer> option, or an error occurs if no
  58 issuer certificate is specified.
  59
  60 =item B<-serial num>
  61
  62 Same as the B<cert> option except the certificate with serial number
  63 B<num> is added to the request. The serial number is interpreted as a
  64 decimal integer unless preceded by B<0x>. Negative integers can also
  65 be specified by preceding the value by a B<-> sign.
  66
  67 =item B<-signer filename>, B<-signkey filename>
  68
  69 Sign the OCSP request using the certificate specified in the B<signer>
  70 option and the private key specified by the B<signkey> option. If
  71 the B<signkey> option is not present then the private key is read
  72 from the same file as the certificate. If neither option is specified then
  73 the OCSP request is not signed.
  74
  75 =item B<-nonce>, B<-no_nonce>
  76
  77 Add an OCSP nonce extension to a request or disable OCSP nonce addition.
  78 Normally if an OCSP request is input using the B<respin> option no
  79 nonce is added: using the B<nonce> option will force addition of a nonce.
  80 If an OCSP request is being created (using B<cert> and B<serial> options)
  81 a nonce is automatically added specifying B<no_nonce> overrides this.
  82
  83 =item B<-req_text>, B<-resp_text>, B<-text>
  84
  85 print out the text form of the OCSP request, reponse or both respectively.
  86
  87 =item B<-reqout file>, B<-respout file>
  88
  89 write out the DER encoded certificate request or response to B<file>.
  90
  91 =item B<-reqin file>, B<-respin file>
  92
  93 read OCSP request or response file from B<file>. These option are ignored
  94 if OCSP request or response creation is implied by other options (for example
  95 with B<serial>, B<cert> and B<host> options).
  96
  97 =item B<-host hostname:port>, B<-path pathname>
  98
  99 if the B<host> option is present then the OCSP request is sent to the host
 100 B<hostname> on port B<port>. B<path> specifies the HTTP path name to use
 101 or "/" by default.
 102
 103 =item B<-CAfile file>, B<-CApath pathname>
 104
 105 file or pathname containing trusted CA certificates. These are used to verify
 106 the signature on the OCSP response.
 107
 108 =item B<-noverify>
 109
 110 don't attempt to verify the OCSP response signature or the nonce values.
 111
 112 =back
 113
 114 =head1 OCSP Response verification.
 115
 116 OCSP Response follows the rules specified in RFC2560.
 117
 118 Initially the OCSP responder certificate is located and the signature on
 119 the OCSP request checked using the reponder certificate's public key.
 120
 121 Then a normal certificate verify is performed on the OCSP responder certificate
 122 building up a certificate chain in the process. The locations of the trusted
 123 certificates used to build the chain can be specified by the B<CAfile>
 124 and B<CApath> options or they will be looked for in the standard OpenSSL
 125 certificates directory.
 126
 127 If the initial verify fails then the OCSP verify process halts with an
 128 error.
 129
 130 Otherwise the issuing CA certificate in the request is compared to the OCSP
 131 responder certificate: if there is a match then the OCSP verify succeeds.
 132
 133 Otherwise the OCSP responder certificate's CA is checked against the issuing
 134 CA certificate in the request. If there is a match and the OCSPSigning
 135 extended key usage is present in the OCSP responder certificate then the
 136 OCSP verify succeeds.
 137
 138 Otherwise the root CA of the OCSP responders CA is checked to see if it
 139 is trusted for OCSP signing. If it is the OCSP verify succeeds.
 140
 141 If none of these checks is successful then the OCSP verify fails.
 142
 143 What this effectively means if that if the OCSP responder certificate is
 144 authorised directly by the CA it is issuing revocation information about
 145 (and it is correctly configured) then verification will succeed.
 146
 147 If the OCSP responder is a "global responder" which can give details about
 148 multiple CAs and has its own separate certificate chain then its root
 149 CA must be trusted for OCSP signing. For example:
 150
 151  openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem
 152
 153 =head1 NOTES
 154
 155 The B<-host> and B<-path> options specify the relevant parts of the OCSP
 156 URI. For example the OCSP responder URL:
 157
 158 http://ocsp.myhost.com/ocsp/request
 159
 160 corresponds to the the options:
 161
 162  -host ocsp.myhost.com:80 -path /ocsp/request
 163
 164 =head1 EXAMPLES
 165
 166 Create an OCSP request and write it to a file:
 167
 168  openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der
 169
 170 Send a query an OCSP responder with URL http://ocsp.myhost.com/ save the
 171 response to a file and print it out in text form
 172
 173  openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \
 174      -host ocsp.myhost.com:80 -resp_text -respout resp.der
 175
 176 Read in an OCSP response and print out text form:
 177
 178  openssl ocsp -respin resp.der -text
 179
 180 =head1 BUGS
 181
 182 This utility is incomplete. It currently does not completely check the OCSP
 183 response's: it does not check the validity dates for example.
 184
 185 The B<host> and B<path> options may well go away and be replaced by a B<url>
 186 option or an option to determine the URI based on certificate extensions.
 187
 188 SSL OCSP responders using https URLs cannot currently be queried.