X-Git-Url: https://git.openssl.org/gitweb/?a=blobdiff_plain;f=doc%2Fapps%2Focsp.pod;h=2372b373cdc1cdbda7247b626b71c3ad12123569;hb=36b619a06e5a2a296058f8dbf11a74f95cb3f71d;hp=6829f51a348d614586306842d99df3d6f5070d5d;hpb=bfcec27d61a333ec853237dcf28cf77c7285be1f;p=openssl.git diff --git a/doc/apps/ocsp.pod b/doc/apps/ocsp.pod index 6829f51a34..2372b373cd 100644 --- a/doc/apps/ocsp.pod +++ b/doc/apps/ocsp.pod @@ -11,6 +11,10 @@ B B [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>] @@ -20,24 +24,46 @@ B B [B<-respin file>] [B<-nonce>] [B<-no_nonce>] +[B<-url URL>] [B<-host host:n>] [B<-path>] -[B<-CApath file>] +[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<-no_explicit>] +[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>] +[B<-md5|-sha1|...>] =head1 DESCRIPTION -B - The Online Certificate Status Protocol (OCSP) enables applications to determine the (revocation) state of an identified certificate (RFC 2560). The B 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. +to an OCSP responder and behave like a mini OCSP server itself. -=head1 OPTIONS +=head1 OCSP CLIENT OPTIONS =over 4 @@ -49,7 +75,7 @@ specify output filename, default is standard output. This specifies the current issuer certificate. This option can be used multiple times. The certificate specified in B must be in -PEM format. +PEM format. This option B come before any B<-cert> options. =item B<-cert filename> @@ -72,6 +98,10 @@ the B 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. @@ -82,7 +112,7 @@ a nonce is automatically added specifying B overrides this. =item B<-req_text>, B<-resp_text>, B<-text> -print out the text form of the OCSP request, reponse or both respectively. +print out the text form of the OCSP request, response or both respectively. =item B<-reqout file>, B<-respout file> @@ -94,20 +124,161 @@ read OCSP request or response file from B. These option are ignored if OCSP request or response creation is implied by other options (for example with B, B and B 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 option is present then the OCSP request is sent to the host B on port B. B specifies the HTTP path name to use or "/" by default. +=item B<-timeout seconds> + +connection timeout to the OCSP responder in seconds + =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. +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_explicit> + +do not explicitly trust the root CA if it is set to be trusted for OCSP signing. + +=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 time and +an optional B 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 time is omitted from a response then this means that new status +information is immediately available. In this case the age of the B field +is checked to see it is not older than B seconds old. By default this additional +check is not performed. + +=item B<-md5|-sha1|-sha256|-ripemod160|...> + +this option sets digest algorithm to use for certificate identification +in the OCSP request. By default SHA-1 is used. + +=back + +=head1 OCSP SERVER OPTIONS + +=over 4 + +=item B<-index indexfile> + +B is a text index file in B format containing certificate revocation +information. + +If the B option is specified the B 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 and B options), supplied in a file (using the +B option) or via external OCSP clients (if B or B is specified). + +If the B option is present then the B and B options must also be +present. + +=item B<-CA file> + +CA certificate corresponding to the revocation information in B. + +=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 option is used. + +=item B<-port portnum> + +Port to listen for OCSP requests on. The port may also be specified using the B +option. + +=item B<-nrequest number> + +The OCSP server will exit after receiving B 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 field. If neither option is present then the B field is +omitted meaning fresh revocation information is immediately available. =back @@ -116,7 +287,7 @@ don't attempt to verify the OCSP response signature or the nonce values. 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. +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 @@ -135,8 +306,9 @@ 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. +Otherwise, if B<-no_explicit> is B set 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. @@ -146,20 +318,29 @@ authorised directly by the CA it is issuing revocation information about 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: +CA can be trusted for OCSP signing. For example: openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem -=head1 NOTES +Alternatively the responder certificate itself can be explicitly trusted +with the B<-VAfile> option. -The B<-host> and B<-path> options specify the relevant parts of the OCSP -URI. For example the OCSP responder URL: +=head1 NOTES -http://ocsp.myhost.com/ocsp/request +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. -corresponds to the the options: +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. - -host ocsp.myhost.com:80 -path /ocsp/request +It is possible to run the B application in responder mode via a CGI +script using the B and B options. =head1 EXAMPLES @@ -167,22 +348,34 @@ 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 +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 \ - -host ocsp.myhost.com:80 -resp_text -respout resp.der + -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 -=head1 BUGS +OCSP server on port 8888 using a standard B 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: -This utility is incomplete. It currently does not completely check the OCSP -response's: it does not check the validity dates for example. + openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem + -issuer demoCA/cacert.pem -serial 1 -The B and B options may well go away and be replaced by a B -option or an option to determine the URI based on certificate extensions. +Query status information using request read from a file, write response to a +second file. -SSL OCSP responders using https URLs cannot currently be queried. + openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem + -reqin req.der -respout resp.der