diff options
Diffstat (limited to 'openssl/doc/apps/ocsp.pod')
| -rw-r--r-- | openssl/doc/apps/ocsp.pod | 365 |
1 files changed, 365 insertions, 0 deletions
diff --git a/openssl/doc/apps/ocsp.pod b/openssl/doc/apps/ocsp.pod new file mode 100644 index 000000000..b58ddc178 --- /dev/null +++ b/openssl/doc/apps/ocsp.pod @@ -0,0 +1,365 @@ +=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<-signer file>] +[B<-signkey file>] +[B<-sign_other file>] +[B<-no_certs>] +[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<-url URL>] +[B<-host host:n>] +[B<-path>] +[B<-CApath dir>] +[B<-CAfile file>] +[B<-VAfile file>] +[B<-validity_period n>] +[B<-status_age n>] +[B<-noverify>] +[B<-verify_other file>] +[B<-trust_other>] +[B<-no_intern>] +[B<-no_signature_verify>] +[B<-no_cert_verify>] +[B<-no_chain>] +[B<-no_cert_checks>] +[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>] + +=head1 DESCRIPTION + +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 and behave like a mini OCSP server itself. + +=head1 OCSP CLIENT 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. This option B<MUST> come before any B<-cert> options. + +=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<-sign_other filename> + +Additional certificates to include in the signed request. + +=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, response 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<-url responder_url> + +specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified. + +=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<-verify_other file> + +file containing additional certificates to search when attempting to locate +the OCSP response signing certificate. Some responders omit the actual signer's +certificate from the response: this option can be used to supply the necessary +certificate in such cases. + +=item B<-trust_other> + +the certificates specified by the B<-verify_other> option should be explicitly +trusted and no additional checks will be performed on them. This is useful +when the complete responder certificate chain is not available or trusting a +root CA is not appropriate. + +=item B<-VAfile file> + +file containing explicitly trusted responder certificates. Equivalent to the +B<-verify_other> and B<-trust_other> options. + +=item B<-noverify> + +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_other> or B<-VAfile> options. + +=item B<-no_signature_verify> + +don't check the signature on the OCSP response. Since this option tolerates invalid +signatures on OCSP responses it will normally only be used for testing purposes. + +=item B<-no_cert_verify> + +don't verify the OCSP response signers certificate at all. Since this option allows +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 +to provide the necessary status information: as a result this option should +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. + +=back + +=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 + +=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 responder 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 can be trusted for OCSP signing. For example: + + openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem + +Alternatively the responder certificate itself can be explicitly trusted +with the B<-VAfile> option. + +=head1 NOTES + +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. + +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. + +=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 to 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 \ + -url http://ocsp.myhost.com/ -resp_text -respout resp.der + +Read in an OCSP response and print out text form: + + openssl ocsp -respin resp.der -text + +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 |