diff options
Diffstat (limited to 'doc/invoke-ocsptool.texi')
| -rw-r--r-- | doc/invoke-ocsptool.texi | 245 |
1 files changed, 134 insertions, 111 deletions
diff --git a/doc/invoke-ocsptool.texi b/doc/invoke-ocsptool.texi index a4f9b95ba5..c2f87d277c 100644 --- a/doc/invoke-ocsptool.texi +++ b/doc/invoke-ocsptool.texi @@ -6,25 +6,32 @@ # # DO NOT EDIT THIS FILE (invoke-ocsptool.texi) # -# It has been AutoGen-ed December 29, 2012 at 01:05:09 PM by AutoGen 5.12 +# It has been AutoGen-ed January 1, 2013 at 09:07:57 PM by AutoGen 5.16 # From the definitions ../src/ocsptool-args.def # and the template file agtexi-cmd.tpl @end ignore + Ocsptool is a program that can parse and print information about OCSP requests/responses, generate requests and verify responses. This section was generated by @strong{AutoGen}, using the @code{agtexi-cmd} template and the option descriptions for the @code{ocsptool} program. - -This software is released under the GNU General Public License. +This software is released under the GNU General Public License, version 3 or later. @anchor{ocsptool usage} -@subsubheading ocsptool usage help (-?) +@subsubheading ocsptool help/usage (-h) +@cindex ocsptool help -This is the automatically generated usage text for ocsptool: +This is the automatically generated usage text for ocsptool. +The text printed is the same whether for the @code{help} option (-h) or the @code{more-help} option (-!). @code{more-help} will print +the usage text by passing it through a pager program. +@code{more-help} is disabled on platforms without a working +@code{fork(2)} function. The @code{PAGER} environment variable is +used to select the program, defaulting to @file{more}. Both will exit +with a status code of 0. @exampleindent 0 @example @@ -83,11 +90,19 @@ please send bug reports to: bug-gnutls@@gnu.org @end example @exampleindent 4 +@anchor{ocsptool debug} +@subsubheading debug option (-d) + +This is the ``enable debugging.'' option. +This option takes an argument number. +Specifies the debug level. @anchor{ocsptool ask} @subsubheading ask option This is the ``ask an ocsp/http server on a certificate validity'' option. +This option takes an optional argument string @file{server name|url}. +@noindent This option has some usage constraints. It: @itemize @bullet @item @@ -96,141 +111,149 @@ load-cert, load-issuer. @end itemize Connects to the specified HTTP OCSP server and queries on the validity of the loaded certificate. +@anchor{ocsptool exit status} +@subsubheading ocsptool exit status -@anchor{ocsptool debug} -@subsubheading debug option (-d) - -This is the ``enable debugging.'' option. -Specifies the debug level. - -@anchor{ocsptool generate-request} -@subsubheading generate-request option (-q) - -This is the ``generate an ocsp request'' option. - - -@anchor{ocsptool inder} -@subsubheading inder option - -This is the ``use der format for input certificates and private keys'' option. - - -@anchor{ocsptool infile} -@subsubheading infile option - -This is the ``input file'' option. - - -@anchor{ocsptool load-cert} -@subsubheading load-cert option - -This is the ``read certificate to check from file'' option. - - -@anchor{ocsptool load-issuer} -@subsubheading load-issuer option - -This is the ``read issuer certificate from file'' option. - - -@anchor{ocsptool load-request} -@subsubheading load-request option (-Q) - -This is the ``read der encoded ocsp request from file'' option. - - -@anchor{ocsptool load-response} -@subsubheading load-response option (-S) - -This is the ``read der encoded ocsp response from file'' option. - - -@anchor{ocsptool load-signer} -@subsubheading load-signer option - -This is the ``read ocsp response signer from file'' option. - -This option has some usage constraints. It: -@itemize @bullet -@item -must not appear in combination with any of the following options: -load-trust. -@end itemize - - +One of the following exit values will be returned: +@table @samp +@item 0 (EXIT_SUCCESS) +Successful program execution. +@item 1 (EXIT_FAILURE) +The operation failed or the command syntax was not valid. +@end table +@anchor{ocsptool See Also} +@subsubheading ocsptool See Also + certtool (1) -@anchor{ocsptool load-trust} -@subsubheading load-trust option +@anchor{ocsptool Examples} +@subsubheading ocsptool Examples +@subsubheading Print information about an OCSP request -This is the ``read ocsp trust anchors from file'' option. +To parse an OCSP request and print information about the content, the +@code{-i} or @code{--request-info} parameter may be used as follows. +The @code{-Q} parameter specify the name of the file containing the +OCSP request, and it should contain the OCSP request in binary DER +format. -This option has some usage constraints. It: -@itemize @bullet -@item -must not appear in combination with any of the following options: -load-signer. -@end itemize +@example +$ ocsptool -i -Q ocsp-request.der +@end example +The input file may also be sent to standard input like this: +@example +$ cat ocsp-request.der | ocsptool --request-info +@end example -@anchor{ocsptool nonce} -@subsubheading nonce option +@subsubheading Print information about an OCSP response -This is the ``don't add nonce to ocsp request'' option. +Similar to parsing OCSP requests, OCSP responses can be parsed using +the @code{-j} or @code{--response-info} as follows. +@example +$ ocsptool -j -Q ocsp-response.der +$ cat ocsp-response.der | ocsptool --response-info +@end example -@anchor{ocsptool outfile} -@subsubheading outfile option +@subsubheading Generate an OCSP request -This is the ``output file'' option. +The @code{-q} or @code{--generate-request} parameters are used to +generate an OCSP request. By default the OCSP request is written to +standard output in binary DER format, but can be stored in a file +using @code{--outfile}. To generate an OCSP request the issuer of the +certificate to check needs to be specified with @code{--load-issuer} +and the certificate to check with @code{--load-cert}. By default PEM +format is used for these files, although @code{--inder} can be used to +specify that the input files are in DER format. +@example +$ ocsptool -q --load-issuer issuer.pem --load-cert client.pem \ + --outfile ocsp-request.der +@end example -@anchor{ocsptool request-info} -@subsubheading request-info option (-i) +When generating OCSP requests, the tool will add an OCSP extension +containing a nonce. This behaviour can be disabled by specifying +@code{--no-nonce}. -This is the ``print information on a ocsp request'' option. +@subsubheading Verify signature in OCSP response +To verify the signature in an OCSP response the @code{-e} or +@code{--verify-response} parameter is used. The tool will read an +OCSP response in DER format from standard input, or from the file +specified by @code{--load-response}. The OCSP response is verified +against a set of trust anchors, which are specified using +@code{--load-trust}. The trust anchors are concatenated certificates +in PEM format. The certificate that signed the OCSP response needs to +be in the set of trust anchors, or the issuer of the signer +certificate needs to be in the set of trust anchors and the OCSP +Extended Key Usage bit has to be asserted in the signer certificate. -@anchor{ocsptool response-info} -@subsubheading response-info option (-j) +@example +$ ocsptool -e --load-trust issuer.pem \ + --load-response ocsp-response.der +@end example -This is the ``print information on a ocsp response'' option. +The tool will print status of verification. +@subsubheading Verify signature in OCSP response against given certificate -@anchor{ocsptool verbose} -@subsubheading verbose option (-V) +It is possible to override the normal trust logic if you know that a +certain certificate is supposed to have signed the OCSP response, and +you want to use it to check the signature. This is achieved using +@code{--load-signer} instead of @code{--load-trust}. This will load +one certificate and it will be used to verify the signature in the +OCSP response. It will not check the Extended Key Usage bit. -This is the ``more verbose output'' option. +@example +$ ocsptool -e --load-signer ocsp-signer.pem \ + --load-response ocsp-response.der +@end example -This option has some usage constraints. It: -@itemize @bullet -@item -may appear an unlimited number of times. -@end itemize +This approach is normally only relevant in two situations. The first +is when the OCSP response does not contain a copy of the signer +certificate, so the @code{--load-trust} code would fail. The second +is if you want to avoid the indirect mode where the OCSP response +signer certificate is signed by a trust anchor. +@subsubheading Real-world example +Here is an example of how to generate an OCSP request for a +certificate and to verify the response. For illustration we'll use +the @code{blog.josefsson.org} host, which (as of writing) uses a +certificate from CACert. First we'll use @code{gnutls-cli} to get a +copy of the server certificate chain. The server is not required to +send this information, but this particular one is configured to do so. -@anchor{ocsptool verify-response} -@subsubheading verify-response option (-e) +@example +$ echo | gnutls-cli -p 443 blog.josefsson.org --print-cert > chain.pem +@end example -This is the ``verify response'' option. +Use a text editor on @code{chain.pem} to create three files for each +separate certificates, called @code{cert.pem} for the first +certificate for the domain itself, secondly @code{issuer.pem} for the +intermediate certificate and @code{root.pem} for the final root +certificate. -@anchor{ocsptool exit status} -@subsubheading ocsptool exit status +The domain certificate normally contains a pointer to where the OCSP +responder is located, in the Authority Information Access Information +extension. For example, from @code{certtool -i < cert.pem} there is +this information: -One of the following exit values will be returned: -@table @samp -@item 0 -Successful program execution. -@item 1 -The operation failed or the command syntax was not valid. -@end table +@example +Authority Information Access Information (not critical): +Access Method: 1.3.6.1.5.5.7.48.1 (id-ad-ocsp) +Access Location URI: http://ocsp.CAcert.org/ +@end example +This means the CA support OCSP queries over HTTP. We are now ready to +create a OCSP request for the certificate. -@anchor{ocsptool See Also} -@subsubheading ocsptool See Also +@example +$ ocsptool --ask ocsp.CAcert.org --load-issuer issuer.pem \ + --load-cert cert.pem --outfile ocsp-response.der +@end example +The request is sent via HTTP to the OCSP server address specified. If the +address is ommited ocsptool will use the address stored in the certificate. -@anchor{ocsptool Examples} -@subsubheading ocsptool Examples |