1109998Smarkm=pod 2109998Smarkm 3109998Smarkm=head1 NAME 4109998Smarkm 5325337Sjkimopenssl-ocsp, 6109998Smarkmocsp - Online Certificate Status Protocol utility 7109998Smarkm 8109998Smarkm=head1 SYNOPSIS 9109998Smarkm 10109998SmarkmB<openssl> B<ocsp> 11109998Smarkm[B<-out file>] 12109998Smarkm[B<-issuer file>] 13109998Smarkm[B<-cert file>] 14109998Smarkm[B<-serial n>] 15120631Snectar[B<-signer file>] 16120631Snectar[B<-signkey file>] 17120631Snectar[B<-sign_other file>] 18120631Snectar[B<-no_certs>] 19109998Smarkm[B<-req_text>] 20109998Smarkm[B<-resp_text>] 21109998Smarkm[B<-text>] 22109998Smarkm[B<-reqout file>] 23109998Smarkm[B<-respout file>] 24109998Smarkm[B<-reqin file>] 25109998Smarkm[B<-respin file>] 26109998Smarkm[B<-nonce>] 27109998Smarkm[B<-no_nonce>] 28120631Snectar[B<-url URL>] 29109998Smarkm[B<-host host:n>] 30312826Sjkim[B<-header name value>] 31109998Smarkm[B<-path>] 32120631Snectar[B<-CApath dir>] 33109998Smarkm[B<-CAfile file>] 34298998Sjkim[B<-no_alt_chains>] 35109998Smarkm[B<-VAfile file>] 36120631Snectar[B<-validity_period n>] 37120631Snectar[B<-status_age n>] 38109998Smarkm[B<-noverify>] 39120631Snectar[B<-verify_other file>] 40109998Smarkm[B<-trust_other>] 41109998Smarkm[B<-no_intern>] 42120631Snectar[B<-no_signature_verify>] 43109998Smarkm[B<-no_cert_verify>] 44109998Smarkm[B<-no_chain>] 45109998Smarkm[B<-no_cert_checks>] 46280297Sjkim[B<-no_explicit>] 47120631Snectar[B<-port num>] 48120631Snectar[B<-index file>] 49120631Snectar[B<-CA file>] 50120631Snectar[B<-rsigner file>] 51120631Snectar[B<-rkey file>] 52120631Snectar[B<-rother file>] 53120631Snectar[B<-resp_no_certs>] 54120631Snectar[B<-nmin n>] 55120631Snectar[B<-ndays n>] 56120631Snectar[B<-resp_key_id>] 57120631Snectar[B<-nrequest n>] 58238405Sjkim[B<-md5|-sha1|...>] 59109998Smarkm 60109998Smarkm=head1 DESCRIPTION 61109998Smarkm 62109998SmarkmThe Online Certificate Status Protocol (OCSP) enables applications to 63109998Smarkmdetermine the (revocation) state of an identified certificate (RFC 2560). 64109998Smarkm 65109998SmarkmThe B<ocsp> command performs many common OCSP tasks. It can be used 66109998Smarkmto print out requests and responses, create requests and send queries 67109998Smarkmto an OCSP responder and behave like a mini OCSP server itself. 68109998Smarkm 69109998Smarkm=head1 OCSP CLIENT OPTIONS 70109998Smarkm 71109998Smarkm=over 4 72109998Smarkm 73109998Smarkm=item B<-out filename> 74109998Smarkm 75109998Smarkmspecify output filename, default is standard output. 76109998Smarkm 77109998Smarkm=item B<-issuer filename> 78109998Smarkm 79109998SmarkmThis specifies the current issuer certificate. This option can be used 80109998Smarkmmultiple times. The certificate specified in B<filename> must be in 81194206SsimonPEM format. This option B<MUST> come before any B<-cert> options. 82109998Smarkm 83109998Smarkm=item B<-cert filename> 84109998Smarkm 85109998SmarkmAdd the certificate B<filename> to the request. The issuer certificate 86109998Smarkmis taken from the previous B<issuer> option, or an error occurs if no 87109998Smarkmissuer certificate is specified. 88109998Smarkm 89109998Smarkm=item B<-serial num> 90109998Smarkm 91109998SmarkmSame as the B<cert> option except the certificate with serial number 92109998SmarkmB<num> is added to the request. The serial number is interpreted as a 93109998Smarkmdecimal integer unless preceded by B<0x>. Negative integers can also 94109998Smarkmbe specified by preceding the value by a B<-> sign. 95109998Smarkm 96109998Smarkm=item B<-signer filename>, B<-signkey filename> 97109998Smarkm 98109998SmarkmSign the OCSP request using the certificate specified in the B<signer> 99109998Smarkmoption and the private key specified by the B<signkey> option. If 100109998Smarkmthe B<signkey> option is not present then the private key is read 101109998Smarkmfrom the same file as the certificate. If neither option is specified then 102109998Smarkmthe OCSP request is not signed. 103109998Smarkm 104120631Snectar=item B<-sign_other filename> 105120631Snectar 106120631SnectarAdditional certificates to include in the signed request. 107120631Snectar 108109998Smarkm=item B<-nonce>, B<-no_nonce> 109109998Smarkm 110109998SmarkmAdd an OCSP nonce extension to a request or disable OCSP nonce addition. 111109998SmarkmNormally if an OCSP request is input using the B<respin> option no 112109998Smarkmnonce is added: using the B<nonce> option will force addition of a nonce. 113109998SmarkmIf an OCSP request is being created (using B<cert> and B<serial> options) 114109998Smarkma nonce is automatically added specifying B<no_nonce> overrides this. 115109998Smarkm 116109998Smarkm=item B<-req_text>, B<-resp_text>, B<-text> 117109998Smarkm 118109998Smarkmprint out the text form of the OCSP request, response or both respectively. 119109998Smarkm 120109998Smarkm=item B<-reqout file>, B<-respout file> 121109998Smarkm 122109998Smarkmwrite out the DER encoded certificate request or response to B<file>. 123109998Smarkm 124109998Smarkm=item B<-reqin file>, B<-respin file> 125109998Smarkm 126109998Smarkmread OCSP request or response file from B<file>. These option are ignored 127109998Smarkmif OCSP request or response creation is implied by other options (for example 128109998Smarkmwith B<serial>, B<cert> and B<host> options). 129109998Smarkm 130109998Smarkm=item B<-url responder_url> 131109998Smarkm 132109998Smarkmspecify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified. 133109998Smarkm 134109998Smarkm=item B<-host hostname:port>, B<-path pathname> 135109998Smarkm 136109998Smarkmif the B<host> option is present then the OCSP request is sent to the host 137109998SmarkmB<hostname> on port B<port>. B<path> specifies the HTTP path name to use 138109998Smarkmor "/" by default. 139109998Smarkm 140312826Sjkim=item B<-header name value> 141312826Sjkim 142312826SjkimIf sending a request to an OCSP server, then the specified header name and 143312826Sjkimvalue are added to the HTTP request. Note that the B<name> and B<value> must 144312826Sjkimbe specified as two separate parameters, not as a single quoted string, and 145312826Sjkimthat the header name does not have the trailing colon. 146312826SjkimSome OCSP responders require a Host header; use this flag to provide it. 147312826Sjkim 148276861Sjkim=item B<-timeout seconds> 149276861Sjkim 150276861Sjkimconnection timeout to the OCSP responder in seconds 151276861Sjkim 152109998Smarkm=item B<-CAfile file>, B<-CApath pathname> 153109998Smarkm 154109998Smarkmfile or pathname containing trusted CA certificates. These are used to verify 155109998Smarkmthe signature on the OCSP response. 156109998Smarkm 157284283Sjkim=item B<-no_alt_chains> 158284283Sjkim 159284283SjkimSee L<B<verify>|verify(1)> manual page for details. 160284283Sjkim 161120631Snectar=item B<-verify_other file> 162109998Smarkm 163109998Smarkmfile containing additional certificates to search when attempting to locate 164109998Smarkmthe OCSP response signing certificate. Some responders omit the actual signer's 165109998Smarkmcertificate from the response: this option can be used to supply the necessary 166109998Smarkmcertificate in such cases. 167109998Smarkm 168109998Smarkm=item B<-trust_other> 169109998Smarkm 170194206Ssimonthe certificates specified by the B<-verify_other> option should be explicitly 171109998Smarkmtrusted and no additional checks will be performed on them. This is useful 172109998Smarkmwhen the complete responder certificate chain is not available or trusting a 173109998Smarkmroot CA is not appropriate. 174109998Smarkm 175109998Smarkm=item B<-VAfile file> 176109998Smarkm 177109998Smarkmfile containing explicitly trusted responder certificates. Equivalent to the 178194206SsimonB<-verify_other> and B<-trust_other> options. 179109998Smarkm 180109998Smarkm=item B<-noverify> 181109998Smarkm 182109998Smarkmdon't attempt to verify the OCSP response signature or the nonce values. This 183109998Smarkmoption will normally only be used for debugging since it disables all verification 184109998Smarkmof the responders certificate. 185109998Smarkm 186109998Smarkm=item B<-no_intern> 187109998Smarkm 188109998Smarkmignore certificates contained in the OCSP response when searching for the 189109998Smarkmsigners certificate. With this option the signers certificate must be specified 190194206Ssimonwith either the B<-verify_other> or B<-VAfile> options. 191109998Smarkm 192120631Snectar=item B<-no_signature_verify> 193109998Smarkm 194109998Smarkmdon't check the signature on the OCSP response. Since this option tolerates invalid 195109998Smarkmsignatures on OCSP responses it will normally only be used for testing purposes. 196109998Smarkm 197109998Smarkm=item B<-no_cert_verify> 198109998Smarkm 199109998Smarkmdon't verify the OCSP response signers certificate at all. Since this option allows 200109998Smarkmthe OCSP response to be signed by any certificate it should only be used for 201109998Smarkmtesting purposes. 202109998Smarkm 203109998Smarkm=item B<-no_chain> 204109998Smarkm 205109998Smarkmdo not use certificates in the response as additional untrusted CA 206109998Smarkmcertificates. 207109998Smarkm 208280297Sjkim=item B<-no_explicit> 209280297Sjkim 210280297Sjkimdo not explicitly trust the root CA if it is set to be trusted for OCSP signing. 211280297Sjkim 212109998Smarkm=item B<-no_cert_checks> 213109998Smarkm 214109998Smarkmdon't perform any additional checks on the OCSP response signers certificate. 215109998SmarkmThat is do not make any checks to see if the signers certificate is authorised 216109998Smarkmto provide the necessary status information: as a result this option should 217109998Smarkmonly be used for testing purposes. 218109998Smarkm 219109998Smarkm=item B<-validity_period nsec>, B<-status_age age> 220109998Smarkm 221109998Smarkmthese options specify the range of times, in seconds, which will be tolerated 222109998Smarkmin an OCSP response. Each certificate status response includes a B<notBefore> time and 223109998Smarkman optional B<notAfter> time. The current time should fall between these two values, but 224109998Smarkmthe interval between the two times may be only a few seconds. In practice the OCSP 225109998Smarkmresponder and clients clocks may not be precisely synchronised and so such a check 226109998Smarkmmay fail. To avoid this the B<-validity_period> option can be used to specify an 227109998Smarkmacceptable error range in seconds, the default value is 5 minutes. 228109998Smarkm 229109998SmarkmIf the B<notAfter> time is omitted from a response then this means that new status 230109998Smarkminformation is immediately available. In this case the age of the B<notBefore> field 231109998Smarkmis checked to see it is not older than B<age> seconds old. By default this additional 232109998Smarkmcheck is not performed. 233109998Smarkm 234238405Sjkim=item B<-md5|-sha1|-sha256|-ripemod160|...> 235238405Sjkim 236238405Sjkimthis option sets digest algorithm to use for certificate identification 237238405Sjkimin the OCSP request. By default SHA-1 is used. 238238405Sjkim 239109998Smarkm=back 240109998Smarkm 241109998Smarkm=head1 OCSP SERVER OPTIONS 242109998Smarkm 243109998Smarkm=over 4 244109998Smarkm 245109998Smarkm=item B<-index indexfile> 246109998Smarkm 247109998SmarkmB<indexfile> is a text index file in B<ca> format containing certificate revocation 248109998Smarkminformation. 249109998Smarkm 250109998SmarkmIf the B<index> option is specified the B<ocsp> utility is in responder mode, otherwise 251109998Smarkmit is in client mode. The request(s) the responder processes can be either specified on 252109998Smarkmthe command line (using B<issuer> and B<serial> options), supplied in a file (using the 253109998SmarkmB<respin> option) or via external OCSP clients (if B<port> or B<url> is specified). 254109998Smarkm 255109998SmarkmIf the B<index> option is present then the B<CA> and B<rsigner> options must also be 256109998Smarkmpresent. 257109998Smarkm 258109998Smarkm=item B<-CA file> 259109998Smarkm 260109998SmarkmCA certificate corresponding to the revocation information in B<indexfile>. 261109998Smarkm 262109998Smarkm=item B<-rsigner file> 263109998Smarkm 264109998SmarkmThe certificate to sign OCSP responses with. 265109998Smarkm 266109998Smarkm=item B<-rother file> 267109998Smarkm 268109998SmarkmAdditional certificates to include in the OCSP response. 269109998Smarkm 270109998Smarkm=item B<-resp_no_certs> 271109998Smarkm 272109998SmarkmDon't include any certificates in the OCSP response. 273109998Smarkm 274109998Smarkm=item B<-resp_key_id> 275109998Smarkm 276109998SmarkmIdentify the signer certificate using the key ID, default is to use the subject name. 277109998Smarkm 278109998Smarkm=item B<-rkey file> 279109998Smarkm 280109998SmarkmThe private key to sign OCSP responses with: if not present the file specified in the 281109998SmarkmB<rsigner> option is used. 282109998Smarkm 283109998Smarkm=item B<-port portnum> 284109998Smarkm 285109998SmarkmPort to listen for OCSP requests on. The port may also be specified using the B<url> 286109998Smarkmoption. 287109998Smarkm 288109998Smarkm=item B<-nrequest number> 289109998Smarkm 290109998SmarkmThe OCSP server will exit after receiving B<number> requests, default unlimited. 291109998Smarkm 292109998Smarkm=item B<-nmin minutes>, B<-ndays days> 293109998Smarkm 294109998SmarkmNumber of minutes or days when fresh revocation information is available: used in the 295109998SmarkmB<nextUpdate> field. If neither option is present then the B<nextUpdate> field is 296109998Smarkmomitted meaning fresh revocation information is immediately available. 297109998Smarkm 298109998Smarkm=back 299109998Smarkm 300109998Smarkm=head1 OCSP Response verification. 301109998Smarkm 302109998SmarkmOCSP Response follows the rules specified in RFC2560. 303109998Smarkm 304109998SmarkmInitially the OCSP responder certificate is located and the signature on 305109998Smarkmthe OCSP request checked using the responder certificate's public key. 306109998Smarkm 307109998SmarkmThen a normal certificate verify is performed on the OCSP responder certificate 308109998Smarkmbuilding up a certificate chain in the process. The locations of the trusted 309109998Smarkmcertificates used to build the chain can be specified by the B<CAfile> 310109998Smarkmand B<CApath> options or they will be looked for in the standard OpenSSL 311109998Smarkmcertificates directory. 312109998Smarkm 313109998SmarkmIf the initial verify fails then the OCSP verify process halts with an 314109998Smarkmerror. 315109998Smarkm 316109998SmarkmOtherwise the issuing CA certificate in the request is compared to the OCSP 317109998Smarkmresponder certificate: if there is a match then the OCSP verify succeeds. 318109998Smarkm 319109998SmarkmOtherwise the OCSP responder certificate's CA is checked against the issuing 320109998SmarkmCA certificate in the request. If there is a match and the OCSPSigning 321109998Smarkmextended key usage is present in the OCSP responder certificate then the 322109998SmarkmOCSP verify succeeds. 323109998Smarkm 324280297SjkimOtherwise, if B<-no_explicit> is B<not> set the root CA of the OCSP responders 325280297SjkimCA is checked to see if it is trusted for OCSP signing. If it is the OCSP 326280297Sjkimverify succeeds. 327109998Smarkm 328109998SmarkmIf none of these checks is successful then the OCSP verify fails. 329109998Smarkm 330109998SmarkmWhat this effectively means if that if the OCSP responder certificate is 331109998Smarkmauthorised directly by the CA it is issuing revocation information about 332109998Smarkm(and it is correctly configured) then verification will succeed. 333109998Smarkm 334109998SmarkmIf the OCSP responder is a "global responder" which can give details about 335109998Smarkmmultiple CAs and has its own separate certificate chain then its root 336109998SmarkmCA can be trusted for OCSP signing. For example: 337109998Smarkm 338109998Smarkm openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem 339109998Smarkm 340109998SmarkmAlternatively the responder certificate itself can be explicitly trusted 341109998Smarkmwith the B<-VAfile> option. 342109998Smarkm 343109998Smarkm=head1 NOTES 344109998Smarkm 345109998SmarkmAs noted, most of the verify options are for testing or debugging purposes. 346109998SmarkmNormally only the B<-CApath>, B<-CAfile> and (if the responder is a 'global 347109998SmarkmVA') B<-VAfile> options need to be used. 348109998Smarkm 349109998SmarkmThe OCSP server is only useful for test and demonstration purposes: it is 350109998Smarkmnot really usable as a full OCSP responder. It contains only a very 351109998Smarkmsimple HTTP request handling and can only handle the POST form of OCSP 352109998Smarkmqueries. It also handles requests serially meaning it cannot respond to 353109998Smarkmnew requests until it has processed the current one. The text index file 354109998Smarkmformat of revocation is also inefficient for large quantities of revocation 355109998Smarkmdata. 356109998Smarkm 357109998SmarkmIt is possible to run the B<ocsp> application in responder mode via a CGI 358109998Smarkmscript using the B<respin> and B<respout> options. 359109998Smarkm 360109998Smarkm=head1 EXAMPLES 361109998Smarkm 362109998SmarkmCreate an OCSP request and write it to a file: 363109998Smarkm 364109998Smarkm openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der 365109998Smarkm 366109998SmarkmSend a query to an OCSP responder with URL http://ocsp.myhost.com/ save the 367109998Smarkmresponse to a file and print it out in text form 368109998Smarkm 369109998Smarkm openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \ 370109998Smarkm -url http://ocsp.myhost.com/ -resp_text -respout resp.der 371109998Smarkm 372109998SmarkmRead in an OCSP response and print out text form: 373109998Smarkm 374109998Smarkm openssl ocsp -respin resp.der -text 375109998Smarkm 376109998SmarkmOCSP server on port 8888 using a standard B<ca> configuration, and a separate 377109998Smarkmresponder certificate. All requests and responses are printed to a file. 378109998Smarkm 379109998Smarkm openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem 380109998Smarkm -text -out log.txt 381109998Smarkm 382109998SmarkmAs above but exit after processing one request: 383109998Smarkm 384109998Smarkm openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem 385109998Smarkm -nrequest 1 386109998Smarkm 387109998SmarkmQuery status information using internally generated request: 388109998Smarkm 389109998Smarkm openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem 390109998Smarkm -issuer demoCA/cacert.pem -serial 1 391109998Smarkm 392109998SmarkmQuery status information using request read from a file, write response to a 393109998Smarkmsecond file. 394109998Smarkm 395109998Smarkm openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem 396109998Smarkm -reqin req.der -respout resp.der 397284283Sjkim 398284283Sjkim=head1 HISTORY 399284283Sjkim 400290207SjkimThe -no_alt_chains options was first added to OpenSSL 1.0.2b. 401284283Sjkim 402284283Sjkim=cut 403