doc/invoke-ocsptool.texi

   1 @node ocsptool Invocation
   2 @section Invoking ocsptool
   3 @pindex ocsptool
   4 @ignore
   5 #  -*- buffer-read-only: t -*- vi: set ro:
   6 #
   7 # DO NOT EDIT THIS FILE   (invoke-ocsptool.texi)
   8 #
   9 # It has been AutoGen-ed  November  8, 2012 at 11:40:17 PM by AutoGen 5.16
  10 # From the definitions    ../src/ocsptool-args.def
  11 # and the template file   agtexi-cmd.tpl
  12 @end ignore
  13
  14
  15 Ocsptool is a program that can parse and print information about
  16 OCSP requests/responses, generate requests and verify responses.
  17
  18
  19 This section was generated by @strong{AutoGen},
  20 using the @code{agtexi-cmd} template and the option descriptions for the @code{ocsptool} program.
  21 This software is released under the GNU General Public License, version 3 or later.
  22
  23
  24 @anchor{ocsptool usage}
  25 @subheading ocsptool help/usage (-h)
  26 @cindex ocsptool help
  27
  28 This is the automatically generated usage text for ocsptool.
  29 The text printed is the same whether for the @code{help} option (-h) or the @code{more-help} option (-!).  @code{more-help} will print
  30 the usage text by passing it through a pager program.
  31 @code{more-help} is disabled on platforms without a working
  32 @code{fork(2)} function.  The @code{PAGER} environment variable is
  33 used to select the program, defaulting to @file{more}.  Both will exit
  34 with a status code of 0.
  35
  36 @exampleindent 0
  37 @example
  38 ocsptool - GnuTLS OCSP tool - Ver. @@VERSION@@
  39 USAGE:  ocsptool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]...
  40
  41    -d, --debug=num            Enable debugging.
  42                                 - It must be in the range:
  43                                   0 to 9999
  44    -V, --verbose              More verbose output
  45                                 - may appear multiple times
  46        --infile=file          Input file
  47                                 - file must pre-exist
  48        --outfile=str          Output file
  49        --ask[=arg]            Ask an OCSP/HTTP server on a certificate validity
  50                                 - requires these options:
  51                                 load-cert
  52                                 load-issuer
  53    -e, --verify-response      Verify response
  54    -i, --request-info         Print information on a OCSP request
  55    -j, --response-info        Print information on a OCSP response
  56    -q, --generate-request     Generate an OCSP request
  57        --nonce                Don't add nonce to OCSP request
  58                                 - disabled as --no-nonce
  59        --load-issuer=file     Read issuer certificate from file
  60                                 - file must pre-exist
  61        --load-cert=file       Read certificate to check from file
  62                                 - file must pre-exist
  63        --load-trust=file      Read OCSP trust anchors from file
  64                                 - prohibits these options:
  65                                 load-signer
  66                                 - file must pre-exist
  67        --load-signer=file     Read OCSP response signer from file
  68                                 - prohibits these options:
  69                                 load-trust
  70                                 - file must pre-exist
  71        --inder                Use DER format for input certificates and private keys
  72                                 - disabled as --no-inder
  73    -Q, --load-request=file    Read DER encoded OCSP request from file
  74                                 - file must pre-exist
  75    -S, --load-response=file   Read DER encoded OCSP response from file
  76                                 - file must pre-exist
  77    -v, --version[=arg]        Output version information and exit
  78    -h, --help                 Display extended usage information and exit
  79    -!, --more-help            Extended usage information passed thru pager
  80
  81 Options are specified by doubled hyphens and their name or by a single
  82 hyphen and the flag character.
  83
  84
  85
  86 Ocsptool is a program that can parse and print information about OCSP
  87 requests/responses, generate requests and verify responses.
  88
  89 please send bug reports to:  bug-gnutls@@gnu.org
  90 @end example
  91 @exampleindent 4
  92
  93 @anchor{ocsptool debug}
  94 @subheading debug option (-d)
  95
  96 This is the ``enable debugging.'' option.
  97 This option takes an argument number.
  98 Specifies the debug level.
  99 @anchor{ocsptool ask}
 100 @subheading ask option
 101
 102 This is the ``ask an ocsp/http server on a certificate validity'' option.
 103 This option takes an optional argument string @file{server name|url}.
 104
 105 @noindent
 106 This option has some usage constraints.  It:
 107 @itemize @bullet
 108 @item
 109 must appear in combination with the following options:
 110 load-cert, load-issuer.
 111 @end itemize
 112
 113 Connects to the specified HTTP OCSP server and queries on the validity of the loaded certificate.
 114 @anchor{ocsptool exit status}
 115 @subheading ocsptool exit status
 116
 117 One of the following exit values will be returned:
 118 @table @samp
 119 @item 0 (EXIT_SUCCESS)
 120 Successful program execution.
 121 @item 1 (EXIT_FAILURE)
 122 The operation failed or the command syntax was not valid.
 123 @end table
 124 @anchor{ocsptool See Also}
 125 @subheading ocsptool See Also
 126     certtool (1)
 127
 128 @anchor{ocsptool Examples}
 129 @subheading ocsptool Examples
 130 @subheading Print information about an OCSP request
 131
 132 To parse an OCSP request and print information about the content, the
 133 @code{-i} or @code{--request-info} parameter may be used as follows.
 134 The @code{-Q} parameter specify the name of the file containing the
 135 OCSP request, and it should contain the OCSP request in binary DER
 136 format.
 137
 138 @example
 139 $ ocsptool -i -Q ocsp-request.der
 140 @end example
 141
 142 The input file may also be sent to standard input like this:
 143
 144 @example
 145 $ cat ocsp-request.der | ocsptool --request-info
 146 @end example
 147
 148 @subheading Print information about an OCSP response
 149
 150 Similar to parsing OCSP requests, OCSP responses can be parsed using
 151 the @code{-j} or @code{--response-info} as follows.
 152
 153 @example
 154 $ ocsptool -j -Q ocsp-response.der
 155 $ cat ocsp-response.der | ocsptool --response-info
 156 @end example
 157
 158 @subheading Generate an OCSP request
 159
 160 The @code{-q} or @code{--generate-request} parameters are used to
 161 generate an OCSP request.  By default the OCSP request is written to
 162 standard output in binary DER format, but can be stored in a file
 163 using @code{--outfile}.  To generate an OCSP request the issuer of the
 164 certificate to check needs to be specified with @code{--load-issuer}
 165 and the certificate to check with @code{--load-cert}.  By default PEM
 166 format is used for these files, although @code{--inder} can be used to
 167 specify that the input files are in DER format.
 168
 169 @example
 170 $ ocsptool -q --load-issuer issuer.pem --load-cert client.pem \
 171            --outfile ocsp-request.der
 172 @end example
 173
 174 When generating OCSP requests, the tool will add an OCSP extension
 175 containing a nonce.  This behaviour can be disabled by specifying
 176 @code{--no-nonce}.
 177
 178 @subheading Verify signature in OCSP response
 179
 180 To verify the signature in an OCSP response the @code{-e} or
 181 @code{--verify-response} parameter is used.  The tool will read an
 182 OCSP response in DER format from standard input, or from the file
 183 specified by @code{--load-response}.  The OCSP response is verified
 184 against a set of trust anchors, which are specified using
 185 @code{--load-trust}.  The trust anchors are concatenated certificates
 186 in PEM format.  The certificate that signed the OCSP response needs to
 187 be in the set of trust anchors, or the issuer of the signer
 188 certificate needs to be in the set of trust anchors and the OCSP
 189 Extended Key Usage bit has to be asserted in the signer certificate.
 190
 191 @example
 192 $ ocsptool -e --load-trust issuer.pem \
 193            --load-response ocsp-response.der
 194 @end example
 195
 196 The tool will print status of verification.
 197
 198 @subheading Verify signature in OCSP response against given certificate
 199
 200 It is possible to override the normal trust logic if you know that a
 201 certain certificate is supposed to have signed the OCSP response, and
 202 you want to use it to check the signature.  This is achieved using
 203 @code{--load-signer} instead of @code{--load-trust}.  This will load
 204 one certificate and it will be used to verify the signature in the
 205 OCSP response.  It will not check the Extended Key Usage bit.
 206
 207 @example
 208 $ ocsptool -e --load-signer ocsp-signer.pem \
 209            --load-response ocsp-response.der
 210 @end example
 211
 212 This approach is normally only relevant in two situations.  The first
 213 is when the OCSP response does not contain a copy of the signer
 214 certificate, so the @code{--load-trust} code would fail.  The second
 215 is if you want to avoid the indirect mode where the OCSP response
 216 signer certificate is signed by a trust anchor.
 217
 218 @subheading Real-world example
 219
 220 Here is an example of how to generate an OCSP request for a
 221 certificate and to verify the response.  For illustration we'll use
 222 the @code{blog.josefsson.org} host, which (as of writing) uses a
 223 certificate from CACert.  First we'll use @code{gnutls-cli} to get a
 224 copy of the server certificate chain.  The server is not required to
 225 send this information, but this particular one is configured to do so.
 226
 227 @example
 228 $ echo | gnutls-cli -p 443 blog.josefsson.org --print-cert > chain.pem
 229 @end example
 230
 231 Use a text editor on @code{chain.pem} to create three files for each
 232 separate certificates, called @code{cert.pem} for the first
 233 certificate for the domain itself, secondly @code{issuer.pem} for the
 234 intermediate certificate and @code{root.pem} for the final root
 235 certificate.
 236
 237 The domain certificate normally contains a pointer to where the OCSP
 238 responder is located, in the Authority Information Access Information
 239 extension.  For example, from @code{certtool -i < cert.pem} there is
 240 this information:
 241
 242 @example
 243 Authority Information Access Information (not critical):
 244 Access Method: 1.3.6.1.5.5.7.48.1 (id-ad-ocsp)
 245 Access Location URI: http://ocsp.CAcert.org/
 246 @end example
 247
 248 This means the CA support OCSP queries over HTTP.  We are now ready to
 249 create a OCSP request for the certificate.
 250
 251 @example
 252 $ ocsptool --ask ocsp.CAcert.org --load-issuer issuer.pem \
 253            --load-cert cert.pem --outfile ocsp-response.der
 254 @end example
 255
 256 The request is sent via HTTP to the OCSP server address specified. If the
 257 address is ommited ocsptool will use the address stored in the certificate.
 258
 259