src/certtool-args.def

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