ocsp.pod revision 280304
1=pod 2 3=head1 NAME 4 5ocsp - Online Certificate Status Protocol utility 6 7=head1 SYNOPSIS 8 9B<openssl> B<ocsp> 10[B<-out file>] 11[B<-issuer file>] 12[B<-cert file>] 13[B<-serial n>] 14[B<-signer file>] 15[B<-signkey file>] 16[B<-sign_other file>] 17[B<-no_certs>] 18[B<-req_text>] 19[B<-resp_text>] 20[B<-text>] 21[B<-reqout file>] 22[B<-respout file>] 23[B<-reqin file>] 24[B<-respin file>] 25[B<-nonce>] 26[B<-no_nonce>] 27[B<-url URL>] 28[B<-host host:n>] 29[B<-path>] 30[B<-CApath dir>] 31[B<-CAfile file>] 32[B<-VAfile file>] 33[B<-validity_period n>] 34[B<-status_age n>] 35[B<-noverify>] 36[B<-verify_other file>] 37[B<-trust_other>] 38[B<-no_intern>] 39[B<-no_signature_verify>] 40[B<-no_cert_verify>] 41[B<-no_chain>] 42[B<-no_cert_checks>] 43[B<-no_explicit>] 44[B<-port num>] 45[B<-index file>] 46[B<-CA file>] 47[B<-rsigner file>] 48[B<-rkey file>] 49[B<-rother file>] 50[B<-resp_no_certs>] 51[B<-nmin n>] 52[B<-ndays n>] 53[B<-resp_key_id>] 54[B<-nrequest n>] 55[B<-md5|-sha1|...>] 56 57=head1 DESCRIPTION 58 59The Online Certificate Status Protocol (OCSP) enables applications to 60determine the (revocation) state of an identified certificate (RFC 2560). 61 62The B<ocsp> command performs many common OCSP tasks. It can be used 63to print out requests and responses, create requests and send queries 64to an OCSP responder and behave like a mini OCSP server itself. 65 66=head1 OCSP CLIENT OPTIONS 67 68=over 4 69 70=item B<-out filename> 71 72specify output filename, default is standard output. 73 74=item B<-issuer filename> 75 76This specifies the current issuer certificate. This option can be used 77multiple times. The certificate specified in B<filename> must be in 78PEM format. This option B<MUST> come before any B<-cert> options. 79 80=item B<-cert filename> 81 82Add the certificate B<filename> to the request. The issuer certificate 83is taken from the previous B<issuer> option, or an error occurs if no 84issuer certificate is specified. 85 86=item B<-serial num> 87 88Same as the B<cert> option except the certificate with serial number 89B<num> is added to the request. The serial number is interpreted as a 90decimal integer unless preceded by B<0x>. Negative integers can also 91be specified by preceding the value by a B<-> sign. 92 93=item B<-signer filename>, B<-signkey filename> 94 95Sign the OCSP request using the certificate specified in the B<signer> 96option and the private key specified by the B<signkey> option. If 97the B<signkey> option is not present then the private key is read 98from the same file as the certificate. If neither option is specified then 99the OCSP request is not signed. 100 101=item B<-sign_other filename> 102 103Additional certificates to include in the signed request. 104 105=item B<-nonce>, B<-no_nonce> 106 107Add an OCSP nonce extension to a request or disable OCSP nonce addition. 108Normally if an OCSP request is input using the B<respin> option no 109nonce is added: using the B<nonce> option will force addition of a nonce. 110If an OCSP request is being created (using B<cert> and B<serial> options) 111a nonce is automatically added specifying B<no_nonce> overrides this. 112 113=item B<-req_text>, B<-resp_text>, B<-text> 114 115print out the text form of the OCSP request, response or both respectively. 116 117=item B<-reqout file>, B<-respout file> 118 119write out the DER encoded certificate request or response to B<file>. 120 121=item B<-reqin file>, B<-respin file> 122 123read OCSP request or response file from B<file>. These option are ignored 124if OCSP request or response creation is implied by other options (for example 125with B<serial>, B<cert> and B<host> options). 126 127=item B<-url responder_url> 128 129specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified. 130 131=item B<-host hostname:port>, B<-path pathname> 132 133if the B<host> option is present then the OCSP request is sent to the host 134B<hostname> on port B<port>. B<path> specifies the HTTP path name to use 135or "/" by default. 136 137=item B<-timeout seconds> 138 139connection timeout to the OCSP responder in seconds 140 141=item B<-CAfile file>, B<-CApath pathname> 142 143file or pathname containing trusted CA certificates. These are used to verify 144the signature on the OCSP response. 145 146=item B<-verify_other file> 147 148file containing additional certificates to search when attempting to locate 149the OCSP response signing certificate. Some responders omit the actual signer's 150certificate from the response: this option can be used to supply the necessary 151certificate in such cases. 152 153=item B<-trust_other> 154 155the certificates specified by the B<-verify_other> option should be explicitly 156trusted and no additional checks will be performed on them. This is useful 157when the complete responder certificate chain is not available or trusting a 158root CA is not appropriate. 159 160=item B<-VAfile file> 161 162file containing explicitly trusted responder certificates. Equivalent to the 163B<-verify_other> and B<-trust_other> options. 164 165=item B<-noverify> 166 167don't attempt to verify the OCSP response signature or the nonce values. This 168option will normally only be used for debugging since it disables all verification 169of the responders certificate. 170 171=item B<-no_intern> 172 173ignore certificates contained in the OCSP response when searching for the 174signers certificate. With this option the signers certificate must be specified 175with either the B<-verify_other> or B<-VAfile> options. 176 177=item B<-no_signature_verify> 178 179don't check the signature on the OCSP response. Since this option tolerates invalid 180signatures on OCSP responses it will normally only be used for testing purposes. 181 182=item B<-no_cert_verify> 183 184don't verify the OCSP response signers certificate at all. Since this option allows 185the OCSP response to be signed by any certificate it should only be used for 186testing purposes. 187 188=item B<-no_chain> 189 190do not use certificates in the response as additional untrusted CA 191certificates. 192 193=item B<-no_explicit> 194 195do not explicitly trust the root CA if it is set to be trusted for OCSP signing. 196 197=item B<-no_cert_checks> 198 199don't perform any additional checks on the OCSP response signers certificate. 200That is do not make any checks to see if the signers certificate is authorised 201to provide the necessary status information: as a result this option should 202only be used for testing purposes. 203 204=item B<-validity_period nsec>, B<-status_age age> 205 206these options specify the range of times, in seconds, which will be tolerated 207in an OCSP response. Each certificate status response includes a B<notBefore> time and 208an optional B<notAfter> time. The current time should fall between these two values, but 209the interval between the two times may be only a few seconds. In practice the OCSP 210responder and clients clocks may not be precisely synchronised and so such a check 211may fail. To avoid this the B<-validity_period> option can be used to specify an 212acceptable error range in seconds, the default value is 5 minutes. 213 214If the B<notAfter> time is omitted from a response then this means that new status 215information is immediately available. In this case the age of the B<notBefore> field 216is checked to see it is not older than B<age> seconds old. By default this additional 217check is not performed. 218 219=item B<-md5|-sha1|-sha256|-ripemod160|...> 220 221this option sets digest algorithm to use for certificate identification 222in the OCSP request. By default SHA-1 is used. 223 224=back 225 226=head1 OCSP SERVER OPTIONS 227 228=over 4 229 230=item B<-index indexfile> 231 232B<indexfile> is a text index file in B<ca> format containing certificate revocation 233information. 234 235If the B<index> option is specified the B<ocsp> utility is in responder mode, otherwise 236it is in client mode. The request(s) the responder processes can be either specified on 237the command line (using B<issuer> and B<serial> options), supplied in a file (using the 238B<respin> option) or via external OCSP clients (if B<port> or B<url> is specified). 239 240If the B<index> option is present then the B<CA> and B<rsigner> options must also be 241present. 242 243=item B<-CA file> 244 245CA certificate corresponding to the revocation information in B<indexfile>. 246 247=item B<-rsigner file> 248 249The certificate to sign OCSP responses with. 250 251=item B<-rother file> 252 253Additional certificates to include in the OCSP response. 254 255=item B<-resp_no_certs> 256 257Don't include any certificates in the OCSP response. 258 259=item B<-resp_key_id> 260 261Identify the signer certificate using the key ID, default is to use the subject name. 262 263=item B<-rkey file> 264 265The private key to sign OCSP responses with: if not present the file specified in the 266B<rsigner> option is used. 267 268=item B<-port portnum> 269 270Port to listen for OCSP requests on. The port may also be specified using the B<url> 271option. 272 273=item B<-nrequest number> 274 275The OCSP server will exit after receiving B<number> requests, default unlimited. 276 277=item B<-nmin minutes>, B<-ndays days> 278 279Number of minutes or days when fresh revocation information is available: used in the 280B<nextUpdate> field. If neither option is present then the B<nextUpdate> field is 281omitted meaning fresh revocation information is immediately available. 282 283=back 284 285=head1 OCSP Response verification. 286 287OCSP Response follows the rules specified in RFC2560. 288 289Initially the OCSP responder certificate is located and the signature on 290the OCSP request checked using the responder certificate's public key. 291 292Then a normal certificate verify is performed on the OCSP responder certificate 293building up a certificate chain in the process. The locations of the trusted 294certificates used to build the chain can be specified by the B<CAfile> 295and B<CApath> options or they will be looked for in the standard OpenSSL 296certificates directory. 297 298If the initial verify fails then the OCSP verify process halts with an 299error. 300 301Otherwise the issuing CA certificate in the request is compared to the OCSP 302responder certificate: if there is a match then the OCSP verify succeeds. 303 304Otherwise the OCSP responder certificate's CA is checked against the issuing 305CA certificate in the request. If there is a match and the OCSPSigning 306extended key usage is present in the OCSP responder certificate then the 307OCSP verify succeeds. 308 309Otherwise, if B<-no_explicit> is B<not> set the root CA of the OCSP responders 310CA is checked to see if it is trusted for OCSP signing. If it is the OCSP 311verify succeeds. 312 313If none of these checks is successful then the OCSP verify fails. 314 315What this effectively means if that if the OCSP responder certificate is 316authorised directly by the CA it is issuing revocation information about 317(and it is correctly configured) then verification will succeed. 318 319If the OCSP responder is a "global responder" which can give details about 320multiple CAs and has its own separate certificate chain then its root 321CA can be trusted for OCSP signing. For example: 322 323 openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem 324 325Alternatively the responder certificate itself can be explicitly trusted 326with the B<-VAfile> option. 327 328=head1 NOTES 329 330As noted, most of the verify options are for testing or debugging purposes. 331Normally only the B<-CApath>, B<-CAfile> and (if the responder is a 'global 332VA') B<-VAfile> options need to be used. 333 334The OCSP server is only useful for test and demonstration purposes: it is 335not really usable as a full OCSP responder. It contains only a very 336simple HTTP request handling and can only handle the POST form of OCSP 337queries. It also handles requests serially meaning it cannot respond to 338new requests until it has processed the current one. The text index file 339format of revocation is also inefficient for large quantities of revocation 340data. 341 342It is possible to run the B<ocsp> application in responder mode via a CGI 343script using the B<respin> and B<respout> options. 344 345=head1 EXAMPLES 346 347Create an OCSP request and write it to a file: 348 349 openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der 350 351Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the 352response to a file and print it out in text form 353 354 openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \ 355 -url http://ocsp.myhost.com/ -resp_text -respout resp.der 356 357Read in an OCSP response and print out text form: 358 359 openssl ocsp -respin resp.der -text 360 361OCSP server on port 8888 using a standard B<ca> configuration, and a separate 362responder certificate. All requests and responses are printed to a file. 363 364 openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem 365 -text -out log.txt 366 367As above but exit after processing one request: 368 369 openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem 370 -nrequest 1 371 372Query status information using internally generated request: 373 374 openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem 375 -issuer demoCA/cacert.pem -serial 1 376 377Query status information using request read from a file, write response to a 378second file. 379 380 openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem 381 -reqin req.der -respout resp.der 382