src/ocsptool-args.def

   1 AutoGen Definitions options;
   2 prog-name     = ocsptool;
   3 prog-title    = "GnuTLS OCSP tool";
   4 prog-desc     = "Program to handle OCSP request/responses.";
   5 detail    = "Ocsptool is a program that can parse and print information about
   6 OCSP requests/responses, generate requests and verify responses.
   7 ";
   8 short-usage   = "ocsptool [options]\nocsptool --help for usage instructions.\n";
   9 explain       = "";
  10
  11 #define  INFILE_OPT   1
  12 #define  OUTFILE_OPT  1
  13 #define  VERBOSE_OPT  1
  14 #include args-std.def
  15
  16 flag = {
  17     name      = ask;
  18     arg-type  = string;
  19     arg-name  = "server name|url";
  20     arg-optional;
  21     descrip   = "Ask an OCSP/HTTP server on a certificate validity";
  22     flags-must = load-cert;
  23     flags-must = load-issuer;
  24     doc = "Connects to the specified HTTP OCSP server and queries on the validity of the loaded certificate.";
  25 };
  26
  27 flag = {
  28     name      = verify-response;
  29     value     = e;
  30     descrip   = "Verify response";
  31     doc = "";
  32 };
  33
  34 flag = {
  35     name      = request-info;
  36     value     = i;
  37     descrip   = "Print information on a OCSP request";
  38     doc = "";
  39 };
  40
  41 flag = {
  42     name      = response-info;
  43     value     = j;
  44     descrip   = "Print information on a OCSP response";
  45     doc = "";
  46 };
  47
  48 flag = {
  49     name      = generate-request;
  50     value     = q;
  51     descrip   = "Generate an OCSP request";
  52     doc = "";
  53 };
  54
  55 flag = {
  56     name      = nonce;
  57     disabled  = yes;
  58     disable   = "no";
  59     descrip   = "Don't add nonce to OCSP request";
  60     doc = "";
  61 };
  62
  63 flag = {
  64     name      = load-issuer;
  65     arg-type  = file;
  66     file-exists = yes;
  67     descrip   = "Read issuer certificate from file";
  68     doc = "";
  69 };
  70
  71 flag = {
  72     name      = load-cert;
  73     arg-type  = file;
  74     file-exists = yes;
  75     descrip   = "Read certificate to check from file";
  76     doc = "";
  77 };
  78
  79 flag = {
  80     name      = load-trust;
  81     arg-type  = file;
  82     file-exists = yes;
  83     descrip   = "Read OCSP trust anchors from file";
  84     flags-cant = load-signer;
  85     doc = "";
  86 };
  87
  88 flag = {
  89     name      = load-signer;
  90     arg-type  = file;
  91     file-exists = yes;
  92     descrip   = "Read OCSP response signer from file";
  93     flags-cant = load-trust;
  94     doc = "";
  95 };
  96
  97 flag = {
  98     name      = inder;
  99     disabled;
 100     disable   = "no";
 101     descrip   = "Use DER format for input certificates and private keys";
 102     doc      = "";
 103 };
 104
 105 flag = {
 106     name      = load-request;
 107     value     = Q;
 108     arg-type  = file;
 109     file-exists = yes;
 110     descrip   = "Read DER encoded OCSP request from file";
 111     doc      = "";
 112 };
 113
 114 flag = {
 115     name      = load-response;
 116     value     = S;
 117     arg-type  = file;
 118     file-exists = yes;
 119     descrip   = "Read DER encoded OCSP response from file";
 120     doc      = "";
 121 };
 122
 123 doc-section = {
 124   ds-type = 'SEE ALSO';
 125   ds-format = 'texi';
 126   ds-text   = <<-_EOT_
 127     certtool (1)
 128 _EOT_;
 129 };
 130
 131 doc-section = {
 132   ds-type = 'EXAMPLES';
 133   ds-format = 'texi';
 134   ds-text   = <<-_EOF_
 135 @subheading Print information about an OCSP request
 136
 137 To parse an OCSP request and print information about the content, the
 138 @code{-i} or @code{--request-info} parameter may be used as follows.
 139 The @code{-Q} parameter specify the name of the file containing the
 140 OCSP request, and it should contain the OCSP request in binary DER
 141 format.
 142
 143 @example
 144 $ ocsptool -i -Q ocsp-request.der
 145 @end example
 146
 147 The input file may also be sent to standard input like this:
 148
 149 @example
 150 $ cat ocsp-request.der | ocsptool --request-info
 151 @end example
 152
 153 @subheading Print information about an OCSP response
 154
 155 Similar to parsing OCSP requests, OCSP responses can be parsed using
 156 the @code{-j} or @code{--response-info} as follows.
 157
 158 @example
 159 $ ocsptool -j -Q ocsp-response.der
 160 $ cat ocsp-response.der | ocsptool --response-info
 161 @end example
 162
 163 @subheading Generate an OCSP request
 164
 165 The @code{-q} or @code{--generate-request} parameters are used to
 166 generate an OCSP request.  By default the OCSP request is written to
 167 standard output in binary DER format, but can be stored in a file
 168 using @code{--outfile}.  To generate an OCSP request the issuer of the
 169 certificate to check needs to be specified with @code{--load-issuer}
 170 and the certificate to check with @code{--load-cert}.  By default PEM
 171 format is used for these files, although @code{--inder} can be used to
 172 specify that the input files are in DER format.
 173
 174 @example
 175 $ ocsptool -q --load-issuer issuer.pem --load-cert client.pem \
 176            --outfile ocsp-request.der
 177 @end example
 178
 179 When generating OCSP requests, the tool will add an OCSP extension
 180 containing a nonce.  This behaviour can be disabled by specifying
 181 @code{--no-nonce}.
 182
 183 @subheading Verify signature in OCSP response
 184
 185 To verify the signature in an OCSP response the @code{-e} or
 186 @code{--verify-response} parameter is used.  The tool will read an
 187 OCSP response in DER format from standard input, or from the file
 188 specified by @code{--load-response}.  The OCSP response is verified
 189 against a set of trust anchors, which are specified using
 190 @code{--load-trust}.  The trust anchors are concatenated certificates
 191 in PEM format.  The certificate that signed the OCSP response needs to
 192 be in the set of trust anchors, or the issuer of the signer
 193 certificate needs to be in the set of trust anchors and the OCSP
 194 Extended Key Usage bit has to be asserted in the signer certificate.
 195
 196 @example
 197 $ ocsptool -e --load-trust issuer.pem \
 198            --load-response ocsp-response.der
 199 @end example
 200
 201 The tool will print status of verification.
 202
 203 @subheading Verify signature in OCSP response against given certificate
 204
 205 It is possible to override the normal trust logic if you know that a
 206 certain certificate is supposed to have signed the OCSP response, and
 207 you want to use it to check the signature.  This is achieved using
 208 @code{--load-signer} instead of @code{--load-trust}.  This will load
 209 one certificate and it will be used to verify the signature in the
 210 OCSP response.  It will not check the Extended Key Usage bit.
 211
 212 @example
 213 $ ocsptool -e --load-signer ocsp-signer.pem \
 214            --load-response ocsp-response.der
 215 @end example
 216
 217 This approach is normally only relevant in two situations.  The first
 218 is when the OCSP response does not contain a copy of the signer
 219 certificate, so the @code{--load-trust} code would fail.  The second
 220 is if you want to avoid the indirect mode where the OCSP response
 221 signer certificate is signed by a trust anchor.
 222
 223 @subheading Real-world example
 224
 225 Here is an example of how to generate an OCSP request for a
 226 certificate and to verify the response.  For illustration we'll use
 227 the @code{blog.josefsson.org} host, which (as of writing) uses a
 228 certificate from CACert.  First we'll use @code{gnutls-cli} to get a
 229 copy of the server certificate chain.  The server is not required to
 230 send this information, but this particular one is configured to do so.
 231
 232 @example
 233 $ echo | gnutls-cli -p 443 blog.josefsson.org --print-cert > chain.pem
 234 @end example
 235
 236 Use a text editor on @code{chain.pem} to create three files for each
 237 separate certificates, called @code{cert.pem} for the first
 238 certificate for the domain itself, secondly @code{issuer.pem} for the
 239 intermediate certificate and @code{root.pem} for the final root
 240 certificate.
 241
 242 The domain certificate normally contains a pointer to where the OCSP
 243 responder is located, in the Authority Information Access Information
 244 extension.  For example, from @code{certtool -i < cert.pem} there is
 245 this information:
 246
 247 @example
 248                 Authority Information Access Information (not critical):
 249                         Access Method: 1.3.6.1.5.5.7.48.1 (id-ad-ocsp)
 250                         Access Location URI: http://ocsp.CAcert.org/
 251 @end example
 252
 253 This means the CA support OCSP queries over HTTP.  We are now ready to
 254 create a OCSP request for the certificate.
 255
 256 @example
 257 $ ocsptool --ask ocsp.CAcert.org --load-issuer issuer.pem \
 258            --load-cert cert.pem --outfile ocsp-response.der
 259 @end example
 260
 261 The request is sent via HTTP to the OCSP server address specified. If the
 262 address is ommited ocsptool will use the address stored in the certificate.
 263
 264 _EOF_;
 265 };
 266