doc/invoke-ocsptool.texi

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