src/certtool-args.def

   1 AutoGen Definitions options;
   2 prog-name     = certtool;
   3 prog-title    = "GnuTLS PKCS #11 tool";
   4 prog-desc     = "Manipulate certificates and private keys.";
   5 detail    = "Tool to parse and generate X.509 certificates, requests and private keys.
   6 It can be used interactively or non interactively by
   7 specifying the template command line option.";
   8 short-usage   = "certtool [options] [url]\ncerttool --help for usage instructions.\n";
   9 explain       = "";
  10
  11 #define  INFILE_OPT    1
  12 #define  OUTFILE_OPT   1
  13 #include args-std.def
  14
  15 flag = {
  16     name      = generate-self-signed;
  17     value     = s;
  18     descrip   = "Generate a self-signed certificate";
  19     doc = "";
  20 };
  21
  22 flag = {
  23     name      = generate-certificate;
  24     value     = c;
  25     descrip   = "Generate a signed certificate";
  26     doc = "";
  27 };
  28
  29 flag = {
  30     name      = generate-proxy;
  31     descrip   = "Generates a proxy certificate";
  32     doc = "";
  33 };
  34
  35 flag = {
  36     name      = generate-crl;
  37     descrip   = "Generate a CRL";
  38     doc = "";
  39 };
  40
  41 flag = {
  42     name      = update-certificate;
  43     value     = u;
  44     descrip   = "Update a signed certificate";
  45     doc = "";
  46 };
  47
  48 flag = {
  49     name      = generate-privkey;
  50     value     = p;
  51     descrip   = "Generate a private key";
  52     doc = "";
  53 };
  54
  55 flag = {
  56     name      = generate-request;
  57     value     = q;
  58     descrip   = "Generate a PKCS #10 certificate request";
  59     doc = "";
  60 };
  61
  62 flag = {
  63     name      = verify-chain;
  64     value     = e;
  65     descrip   = "Verify a PEM encoded certificate chain.";
  66     doc = "The last certificate in the chain must be a self signed one.";
  67 };
  68
  69 flag = {
  70     name      = verify;
  71     descrip   = "Verify a PEM encoded certificate chain using a trusted list.";
  72     doc = "The trusted certificate list must be loaded with --load-ca-certificate.";
  73     flags-must = load-ca-certificate;
  74 };
  75
  76 flag = {
  77     name      = verify-crl;
  78     descrip   = "Verify a CRL using a trusted list.";
  79     doc = "The trusted certificate list must be loaded with --load-ca-certificate.";
  80     flags-must = load-ca-certificate;
  81 };
  82
  83 flag = {
  84     name      = generate-dh-params;
  85     descrip   = "Generate PKCS #3 encoded Diffie-Hellman parameters.";
  86     doc = "";
  87 };
  88
  89 flag = {
  90     name      = get-dh-params;
  91     descrip   = "Get the included PKCS #3 encoded Diffie-Hellman parameters.";
  92     doc = "Returns stored DH parameters in GnuTLS. Those parameters are used in the SRP protocol. The parameters returned by fresh generation
  93 are more efficient since GnuTLS 3.0.9.";
  94 };
  95
  96 flag = {
  97     name      = dh-info;
  98     descrip   = "Print information PKCS #3 encoded Diffie-Hellman parameters";
  99     doc = "";
 100 };
 101
 102 flag = {
 103     name      = load-privkey;
 104     descrip   = "Loads a private key file";
 105     arg-type  = string;
 106     doc = "This can be either a file or a PKCS #11 URL";
 107 };
 108
 109 flag = {
 110     name      = load-pubkey;
 111     descrip   = "Loads a public key file";
 112     arg-type  = string;
 113     doc = "This can be either a file or a PKCS #11 URL";
 114 };
 115
 116 flag = {
 117     name      = load-request;
 118     descrip   = "Loads a certificate request file";
 119     arg-type  = file;
 120     file-exists = yes;
 121     doc = "";
 122 };
 123
 124 flag = {
 125     name      = load-certificate;
 126     descrip   = "Loads a certificate file";
 127     arg-type  = string;
 128     doc = "This can be either a file or a PKCS #11 URL";
 129 };
 130
 131 flag = {
 132     name      = load-ca-privkey;
 133     descrip   = "Loads the certificate authority's private key file";
 134     arg-type  = string;
 135     doc = "This can be either a file or a PKCS #11 URL";
 136 };
 137
 138 flag = {
 139     name      = load-ca-certificate;
 140     descrip   = "Loads the certificate authority's certificate file";
 141     arg-type  = string;
 142     doc = "This can be either a file or a PKCS #11 URL";
 143 };
 144
 145 flag = {
 146     name      = password;
 147     arg-type  = string;
 148     descrip   = "Password to use";
 149     doc   = "";
 150 };
 151
 152 flag = {
 153     name      = certificate-info;
 154     value     = i;
 155     descrip   = "Print information on the given certificate";
 156     doc       = "";
 157 };
 158
 159 flag = {
 160     name      = certificate-pubkey;
 161     descrip   = "Print certificate's public key";
 162     doc       = "";
 163 };
 164
 165 flag = {
 166     name      = pgp-certificate-info;
 167     descrip   = "Print information on the given OpenPGP certificate";
 168     doc       = "";
 169 };
 170
 171 flag = {
 172     name      = pgp-ring-info;
 173     descrip   = "Print information on the given OpenPGP keyring structure";
 174     doc       = "";
 175 };
 176
 177 flag = {
 178     name      = crl-info;
 179     value     = l;
 180     descrip   = "Print information on the given CRL structure";
 181     doc       = "";
 182 };
 183
 184 flag = {
 185     name      = crq-info;
 186     descrip   = "Print information on the given certificate request";
 187     doc       = "";
 188 };
 189
 190
 191 flag = {
 192     name      = no-crq-extensions;
 193     descrip   = "Do not use extensions in certificate requests";
 194     doc       = "";
 195 };
 196
 197 flag = {
 198     name      = p12-info;
 199     descrip   = "Print information on a PKCS #12 structure";
 200     doc       = "";
 201 };
 202
 203 flag = {
 204     name      = p7-info;
 205     descrip   = "Print information on a PKCS #7 structure";
 206     doc       = "";
 207 };
 208
 209 flag = {
 210     name      = smime-to-p7;
 211     descrip   = "Convert S/MIME to PKCS #7 structure";
 212     doc       = "";
 213 };
 214
 215 flag = {
 216     name      = key-info;
 217     value     = k;
 218     descrip   = "Print information on a private key";
 219     doc = "";
 220 };
 221
 222 flag = {
 223     name      = pgp-key-info;
 224     descrip   = "Print information on an OpenPGP private key";
 225     doc = "";
 226 };
 227
 228 flag = {
 229     name      = pubkey-info;
 230     descrip   = "Print information on a public key";
 231     doc = "";
 232 };
 233
 234 flag = {
 235     name      = v1;
 236     descrip   = "Generate an X.509 version 1 certificate (with no extensions)";
 237     doc = "";
 238 };
 239
 240 flag = {
 241     name      = to-p12;
 242     descrip   = "Generate a PKCS #12 structure";
 243     doc = "It requires a certificate, a private key and possibly a CA certificate to be specified.";
 244     flags-must = load-certificate;
 245     flags-must = load-privkey;
 246 };
 247
 248 flag = {
 249     name      = to-p8;
 250     descrip   = "Generate a PKCS #8 structure";
 251     doc = "";
 252 };
 253
 254 flag = {
 255     name      = pkcs8;
 256     value     = 8;
 257     descrip   = "Use PKCS #8 format for private keys";
 258     doc = "";
 259 };
 260
 261 flag = {
 262     name      = rsa;
 263     descrip   = "Generate RSA key";
 264     doc = "";
 265 };
 266
 267 flag = {
 268     name      = dsa;
 269     descrip   = "Generate DSA key";
 270     doc = "";
 271 };
 272
 273 flag = {
 274     name      = ecc;
 275     descrip   = "Generate ECC (ECDSA) key";
 276     doc = "";
 277 };
 278
 279 flag = {
 280     name      = hash;
 281     arg-type  = string;
 282     descrip   = "Hash algorithm to use for signing.";
 283     doc = "Available hash functions are SHA1, RMD160, SHA256, SHA384, SHA512.";
 284 };
 285
 286 flag = {
 287     name      = inder;
 288     descrip   = "Use DER format for input certificates and private keys.";
 289     disabled;
 290     disable   = "no";
 291     doc       = "";
 292 };
 293
 294 flag = {
 295     name      = inraw;
 296     aliases   = inder;
 297 };
 298
 299 flag = {
 300     name      = outder;
 301     descrip   = "Use DER format for output certificates and private keys";
 302     disabled;
 303     disable   = "no";
 304     doc       = "";
 305 };
 306
 307 flag = {
 308     name      = outraw;
 309     aliases   = outder;
 310 };
 311
 312 flag = {
 313     name      = bits;
 314     arg-type  = number;
 315     descrip   = "Specify the number of bits for key generate";
 316     doc      = "";
 317 };
 318
 319 flag = {
 320     name      = sec-param;
 321     arg-type  = string;
 322     arg-name  = "Security parameter";
 323     descrip   = "Specify the security level [low| legacy| normal| high| ultra].";
 324     doc      = "This is alternative to the bits option.";
 325 };
 326
 327 flag = {
 328     name      = disable-quick-random;
 329     descrip   = "No effect";
 330     doc      = "";
 331 };
 332
 333 flag = {
 334     name      = template;
 335     arg-type  = file;
 336     file-exists = yes;
 337     descrip   = "Template file to use for non-interactive operation";
 338     doc   = "";
 339 };
 340
 341 flag = {
 342     name      = pkcs-cipher;
 343     arg-type  = string;
 344     arg-name  = "Cipher";
 345     descrip   = "Cipher to use for PKCS #8 and #12 operations";
 346     doc   = "Cipher may be one of 3des, 3des-pkcs12, aes-128, aes-192, aes-256, rc2-40, arcfour.";
 347 };
 348
 349 doc-section = {
 350   ds-type = 'SEE ALSO';
 351   ds-format = 'texi';
 352   ds-text   = <<-_EOT_
 353     p11tool (1)
 354 _EOT_;
 355 };
 356
 357 doc-section = {
 358   ds-type = 'EXAMPLES';
 359   ds-format = 'texi';
 360   ds-text   = <<-_EOT_
 361 @subheading Generating private keys
 362 To create an RSA private key, run:
 363 @example
 364 $ certtool --generate-privkey --outfile key.pem --rsa
 365 @end example
 366
 367 To create a DSA or elliptic curves (ECDSA) private key use the
 368 above command combined with 'dsa' or 'ecc' options.
 369
 370 @subheading Generating certificate requests
 371 To create a certificate request (needed when the certificate is  issued  by
 372 another party), run:
 373 @example
 374 certtool --generate-request --load-privkey key.pem \
 375    --outfile request.pem
 376 @end example
 377
 378 If the private key is stored in a smart card you can generate
 379 a request by specifying the private key object URL.
 380 @example
 381 $ ./certtool --generate-request --load-privkey "pkcs11:..." \
 382   --load-pubkey "pkcs11:..." --outfile request.pem
 383 @end example
 384
 385
 386 @subheading Generating a self-signed certificate
 387 To create a self signed certificate, use the command:
 388 @example
 389 $ certtool --generate-privkey --outfile ca-key.pem
 390 $ certtool --generate-self-signed --load-privkey ca-key.pem \
 391    --outfile ca-cert.pem
 392 @end example
 393
 394 Note that a self-signed certificate usually belongs to a certificate
 395 authority, that signs other certificates.
 396
 397 @subheading Generating a certificate
 398 To generate a certificate using the previous request, use the command:
 399 @example
 400 $ certtool --generate-certificate --load-request request.pem \
 401    --outfile cert.pem --load-ca-certificate ca-cert.pem \
 402    --load-ca-privkey ca-key.pem
 403 @end example
 404
 405 To generate a certificate using the private key only, use the command:
 406 @example
 407 $ certtool --generate-certificate --load-privkey key.pem \
 408    --outfile cert.pem --load-ca-certificate ca-cert.pem \
 409    --load-ca-privkey ca-key.pem
 410 @end example
 411
 412 @subheading Certificate information
 413 To view the certificate information, use:
 414 @example
 415 $ certtool --certificate-info --infile cert.pem
 416 @end example
 417
 418 @subheading PKCS #12 structure generation
 419 To generate a PKCS #12 structure using the previous key and certificate,
 420 use the command:
 421 @example
 422 $ certtool --load-certificate cert.pem --load-privkey key.pem \
 423    --to-p12 --outder --outfile key.p12
 424 @end example
 425
 426 Some tools (reportedly web browsers) have problems with that file
 427 because it does not contain the CA certificate for the certificate.
 428 To work around that problem in the tool, you can use the
 429 --load-ca-certificate parameter as follows:
 430
 431 @example
 432 $ certtool --load-ca-certificate ca.pem \
 433   --load-certificate cert.pem --load-privkey key.pem \
 434   --to-p12 --outder --outfile key.p12
 435 @end example
 436
 437 @subheading Diffie-Hellman parameter generation
 438 To generate parameters for Diffie-Hellman key exchange, use the command:
 439 @example
 440 $ certtool --generate-dh-params --outfile dh.pem --sec-param normal
 441 @end example
 442
 443 @subheading Proxy certificate generation
 444 Proxy certificate can be used to delegate your credential to a
 445 temporary, typically short-lived, certificate.  To create one from the
 446 previously created certificate, first create a temporary key and then
 447 generate a proxy certificate for it, using the commands:
 448
 449 @example
 450 $ certtool --generate-privkey > proxy-key.pem
 451 $ certtool --generate-proxy --load-ca-privkey key.pem \
 452   --load-privkey proxy-key.pem --load-certificate cert.pem \
 453   --outfile proxy-cert.pem
 454 @end example
 455
 456 @subheading Certificate revocation list generation
 457 To create an empty Certificate Revocation List (CRL) do:
 458
 459 @example
 460 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
 461            --load-ca-certificate x509-ca.pem
 462 @end example
 463
 464 To create a CRL that contains some revoked certificates, place the
 465 certificates in a file and use @code{--load-certificate} as follows:
 466
 467 @example
 468 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
 469   --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
 470 @end example
 471
 472 To verify a Certificate Revocation List (CRL) do:
 473
 474 @example
 475 $ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
 476 @end example
 477 _EOT_;
 478 };
 479
 480
 481 doc-section = {
 482   ds-type = 'FILES';
 483   ds-format = 'texi';
 484   ds-text   = <<-_EOT_
 485 @subheading Certtool's template file format
 486 A template file can be used to avoid the interactive questions of
 487 certtool. Initially create a file named 'cert.cfg' that contains the information
 488 about the certificate. The template can be used as below:
 489
 490 @example
 491 $ certtool --generate-certificate cert.pem --load-privkey key.pem  \
 492    --template cert.cfg \
 493    --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
 494 @end example
 495
 496 An example certtool template file that can be used to generate a certificate
 497 request or a self signed certificate follows.
 498
 499 @example
 500 # X.509 Certificate options
 501 #
 502 # DN options
 503
 504 # The organization of the subject.
 505 organization = "Koko inc."
 506
 507 # The organizational unit of the subject.
 508 unit = "sleeping dept."
 509
 510 # The locality of the subject.
 511 # locality =
 512
 513 # The state of the certificate owner.
 514 state = "Attiki"
 515
 516 # The country of the subject. Two letter code.
 517 country = GR
 518
 519 # The common name of the certificate owner.
 520 cn = "Cindy Lauper"
 521
 522 # A user id of the certificate owner.
 523 #uid = "clauper"
 524
 525 # Set domain components
 526 #dc = "name"
 527 #dc = "domain"
 528
 529 # If the supported DN OIDs are not adequate you can set
 530 # any OID here.
 531 # For example set the X.520 Title and the X.520 Pseudonym
 532 # by using OID and string pairs.
 533 #dn_oid = 2.5.4.12 Dr.
 534 #dn_oid = 2.5.4.65 jackal
 535
 536 # This is deprecated and should not be used in new
 537 # certificates.
 538 # pkcs9_email = "none@@none.org"
 539
 540 # The serial number of the certificate
 541 serial = 007
 542
 543 # In how many days, counting from today, this certificate will expire.
 544 expiration_days = 700
 545
 546 # X.509 v3 extensions
 547
 548 # A dnsname in case of a WWW server.
 549 #dns_name = "www.none.org"
 550 #dns_name = "www.morethanone.org"
 551
 552 # An IP address in case of a server.
 553 #ip_address = "192.168.1.1"
 554
 555 # An email in case of a person
 556 email = "none@@none.org"
 557
 558 # Challenge password used in certificate requests
 559 challenge_passwd = 123456
 560
 561 # An URL that has CRLs (certificate revocation lists)
 562 # available. Needed in CA certificates.
 563 #crl_dist_points = "http://www.getcrl.crl/getcrl/"
 564
 565 # Whether this is a CA certificate or not
 566 #ca
 567
 568 # for microsoft smart card logon
 569 # key_purpose_oid = 1.3.6.1.4.1.311.20.2.2
 570
 571 ### Other predefined key purpose OIDs
 572
 573 # Whether this certificate will be used for a TLS client
 574 #tls_www_client
 575
 576 # Whether this certificate will be used for a TLS server
 577 #tls_www_server
 578
 579 # Whether this certificate will be used to sign data (needed
 580 # in TLS DHE ciphersuites).
 581 signing_key
 582
 583 # Whether this certificate will be used to encrypt data (needed
 584 # in TLS RSA ciphersuites). Note that it is preferred to use different
 585 # keys for encryption and signing.
 586 #encryption_key
 587
 588 # Whether this key will be used to sign other certificates.
 589 #cert_signing_key
 590
 591 # Whether this key will be used to sign CRLs.
 592 #crl_signing_key
 593
 594 # Whether this key will be used to sign code.
 595 #code_signing_key
 596
 597 # Whether this key will be used to sign OCSP data.
 598 #ocsp_signing_key
 599
 600 # Whether this key will be used for time stamping.
 601 #time_stamping_key
 602
 603 # Whether this key will be used for IPsec IKE operations.
 604 #ipsec_ike_key
 605
 606 ### end of key purpose OIDs
 607
 608 # When generating a certificate from a certificate
 609 # request, then honor the extensions stored in the request
 610 # and store them in the real certificate.
 611 #honor_crq_extensions
 612
 613 # Path length contraint. Sets the maximum number of
 614 # certificates that can be used to certify this certificate.
 615 # (i.e. the certificate chain length)
 616 #path_len = -1
 617 #path_len = 2
 618
 619 # Options for proxy certificates
 620 # proxy_policy_language = 1.3.6.1.5.5.7.21.1
 621
 622 # Options for generating a CRL
 623
 624 # next CRL update will be in 43 days (wow)
 625 #crl_next_update = 43
 626
 627 # this is the 5th CRL by this CA
 628 #crl_number = 5
 629
 630 @end example
 631
 632 _EOT_;
 633 };
 634