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 };
 246
 247 flag = {
 248     name      = to-p8;
 249     descrip   = "Generate a PKCS #8 structure";
 250     doc = "";
 251 };
 252
 253 flag = {
 254     name      = pkcs8;
 255     value     = 8;
 256     descrip   = "Use PKCS #8 format for private keys";
 257     doc = "";
 258 };
 259
 260 flag = {
 261     name      = rsa;
 262     descrip   = "Generate RSA key";
 263     doc = "";
 264 };
 265
 266 flag = {
 267     name      = dsa;
 268     descrip   = "Generate DSA key";
 269     doc = "";
 270 };
 271
 272 flag = {
 273     name      = ecc;
 274     descrip   = "Generate ECC (ECDSA) key";
 275     doc = "";
 276 };
 277
 278 flag = {
 279     name      = hash;
 280     arg-type  = string;
 281     descrip   = "Hash algorithm to use for signing.";
 282     doc = "Available hash functions are SHA1, RMD160, SHA256, SHA384, SHA512.";
 283 };
 284
 285 flag = {
 286     name      = inder;
 287     descrip   = "Use DER format for input certificates and private keys.";
 288     disabled;
 289     disable   = "no";
 290     doc       = "The input files will be assumed to be in DER or RAW format.
 291 Unlike options that in PEM input would allow multiple input data (e.g. multiple
 292 certificates), when reading in DER format a single data structure is read.";
 293 };
 294
 295 flag = {
 296     name      = inraw;
 297     aliases   = inder;
 298 };
 299
 300 flag = {
 301     name      = outder;
 302     descrip   = "Use DER format for output certificates and private keys";
 303     disabled;
 304     disable   = "no";
 305     doc       = "The output will be in DER or RAW format.";
 306 };
 307
 308 flag = {
 309     name      = outraw;
 310     aliases   = outder;
 311 };
 312
 313 flag = {
 314     name      = bits;
 315     arg-type  = number;
 316     descrip   = "Specify the number of bits for key generate";
 317     doc      = "";
 318 };
 319
 320 flag = {
 321     name      = sec-param;
 322     arg-type  = string;
 323     arg-name  = "Security parameter";
 324     descrip   = "Specify the security level [low, legacy, normal, high, ultra].";
 325     doc      = "This is alternative to the bits option.";
 326 };
 327
 328 flag = {
 329     name      = disable-quick-random;
 330     descrip   = "No effect";
 331     doc      = "";
 332 };
 333
 334 flag = {
 335     name      = template;
 336     arg-type  = file;
 337     file-exists = yes;
 338     descrip   = "Template file to use for non-interactive operation";
 339     doc   = "";
 340 };
 341
 342 flag = {
 343     name      = pkcs-cipher;
 344     arg-type  = string;
 345     arg-name  = "Cipher";
 346     descrip   = "Cipher to use for PKCS #8 and #12 operations";
 347     doc   = "Cipher may be one of 3des, 3des-pkcs12, aes-128, aes-192, aes-256, rc2-40, arcfour.";
 348 };
 349
 350 doc-section = {
 351   ds-type = 'SEE ALSO';
 352   ds-format = 'texi';
 353   ds-text   = <<-_EOT_
 354     p11tool (1)
 355 _EOT_;
 356 };
 357
 358 doc-section = {
 359   ds-type = 'EXAMPLES';
 360   ds-format = 'texi';
 361   ds-text   = <<-_EOT_
 362 @subheading Generating private keys
 363 To create an RSA private key, run:
 364 @example
 365 $ certtool --generate-privkey --outfile key.pem --rsa
 366 @end example
 367
 368 To create a DSA or elliptic curves (ECDSA) private key use the
 369 above command combined with 'dsa' or 'ecc' options.
 370
 371 @subheading Generating certificate requests
 372 To create a certificate request (needed when the certificate is  issued  by
 373 another party), run:
 374 @example
 375 certtool --generate-request --load-privkey key.pem \
 376    --outfile request.pem
 377 @end example
 378
 379 If the private key is stored in a smart card you can generate
 380 a request by specifying the private key object URL.
 381 @example
 382 $ ./certtool --generate-request --load-privkey "pkcs11:..." \
 383   --load-pubkey "pkcs11:..." --outfile request.pem
 384 @end example
 385
 386
 387 @subheading Generating a self-signed certificate
 388 To create a self signed certificate, use the command:
 389 @example
 390 $ certtool --generate-privkey --outfile ca-key.pem
 391 $ certtool --generate-self-signed --load-privkey ca-key.pem \
 392    --outfile ca-cert.pem
 393 @end example
 394
 395 Note that a self-signed certificate usually belongs to a certificate
 396 authority, that signs other certificates.
 397
 398 @subheading Generating a certificate
 399 To generate a certificate using the previous request, use the command:
 400 @example
 401 $ certtool --generate-certificate --load-request request.pem \
 402    --outfile cert.pem --load-ca-certificate ca-cert.pem \
 403    --load-ca-privkey ca-key.pem
 404 @end example
 405
 406 To generate a certificate using the private key only, use the command:
 407 @example
 408 $ certtool --generate-certificate --load-privkey key.pem \
 409    --outfile cert.pem --load-ca-certificate ca-cert.pem \
 410    --load-ca-privkey ca-key.pem
 411 @end example
 412
 413 @subheading Certificate information
 414 To view the certificate information, use:
 415 @example
 416 $ certtool --certificate-info --infile cert.pem
 417 @end example
 418
 419 @subheading PKCS #12 structure generation
 420 To generate a PKCS #12 structure using the previous key and certificate,
 421 use the command:
 422 @example
 423 $ certtool --load-certificate cert.pem --load-privkey key.pem \
 424    --to-p12 --outder --outfile key.p12
 425 @end example
 426
 427 Some tools (reportedly web browsers) have problems with that file
 428 because it does not contain the CA certificate for the certificate.
 429 To work around that problem in the tool, you can use the
 430 --load-ca-certificate parameter as follows:
 431
 432 @example
 433 $ certtool --load-ca-certificate ca.pem \
 434   --load-certificate cert.pem --load-privkey key.pem \
 435   --to-p12 --outder --outfile key.p12
 436 @end example
 437
 438 @subheading Diffie-Hellman parameter generation
 439 To generate parameters for Diffie-Hellman key exchange, use the command:
 440 @example
 441 $ certtool --generate-dh-params --outfile dh.pem --sec-param normal
 442 @end example
 443
 444 @subheading Proxy certificate generation
 445 Proxy certificate can be used to delegate your credential to a
 446 temporary, typically short-lived, certificate.  To create one from the
 447 previously created certificate, first create a temporary key and then
 448 generate a proxy certificate for it, using the commands:
 449
 450 @example
 451 $ certtool --generate-privkey > proxy-key.pem
 452 $ certtool --generate-proxy --load-ca-privkey key.pem \
 453   --load-privkey proxy-key.pem --load-certificate cert.pem \
 454   --outfile proxy-cert.pem
 455 @end example
 456
 457 @subheading Certificate revocation list generation
 458 To create an empty Certificate Revocation List (CRL) do:
 459
 460 @example
 461 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
 462            --load-ca-certificate x509-ca.pem
 463 @end example
 464
 465 To create a CRL that contains some revoked certificates, place the
 466 certificates in a file and use @code{--load-certificate} as follows:
 467
 468 @example
 469 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
 470   --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
 471 @end example
 472
 473 To verify a Certificate Revocation List (CRL) do:
 474
 475 @example
 476 $ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
 477 @end example
 478 _EOT_;
 479 };
 480
 481
 482 doc-section = {
 483   ds-type = 'FILES';
 484   ds-format = 'texi';
 485   ds-text   = <<-_EOT_
 486 @subheading Certtool's template file format
 487 A template file can be used to avoid the interactive questions of
 488 certtool. Initially create a file named 'cert.cfg' that contains the information
 489 about the certificate. The template can be used as below:
 490
 491 @example
 492 $ certtool --generate-certificate cert.pem --load-privkey key.pem  \
 493    --template cert.cfg \
 494    --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
 495 @end example
 496
 497 An example certtool template file that can be used to generate a certificate
 498 request or a self signed certificate follows.
 499
 500 @example
 501 # X.509 Certificate options
 502 #
 503 # DN options
 504
 505 # The organization of the subject.
 506 organization = "Koko inc."
 507
 508 # The organizational unit of the subject.
 509 unit = "sleeping dept."
 510
 511 # The locality of the subject.
 512 # locality =
 513
 514 # The state of the certificate owner.
 515 state = "Attiki"
 516
 517 # The country of the subject. Two letter code.
 518 country = GR
 519
 520 # The common name of the certificate owner.
 521 cn = "Cindy Lauper"
 522
 523 # A user id of the certificate owner.
 524 #uid = "clauper"
 525
 526 # Set domain components
 527 #dc = "name"
 528 #dc = "domain"
 529
 530 # If the supported DN OIDs are not adequate you can set
 531 # any OID here.
 532 # For example set the X.520 Title and the X.520 Pseudonym
 533 # by using OID and string pairs.
 534 #dn_oid = 2.5.4.12 Dr.
 535 #dn_oid = 2.5.4.65 jackal
 536
 537 # This is deprecated and should not be used in new
 538 # certificates.
 539 # pkcs9_email = "none@@none.org"
 540
 541 # The serial number of the certificate
 542 serial = 007
 543
 544 # In how many days, counting from today, this certificate will expire.
 545 expiration_days = 700
 546
 547 # X.509 v3 extensions
 548
 549 # A dnsname in case of a WWW server.
 550 #dns_name = "www.none.org"
 551 #dns_name = "www.morethanone.org"
 552
 553 # A subject alternative name URI
 554 #uri = "http://www.example.com"
 555
 556 # An IP address in case of a server.
 557 #ip_address = "192.168.1.1"
 558
 559 # An email in case of a person
 560 email = "none@@none.org"
 561
 562 # Challenge password used in certificate requests
 563 challenge_passwd = 123456
 564
 565 # An URL that has CRLs (certificate revocation lists)
 566 # available. Needed in CA certificates.
 567 #crl_dist_points = "http://www.getcrl.crl/getcrl/"
 568
 569 # Whether this is a CA certificate or not
 570 #ca
 571
 572 # for microsoft smart card logon
 573 # key_purpose_oid = 1.3.6.1.4.1.311.20.2.2
 574
 575 ### Other predefined key purpose OIDs
 576
 577 # Whether this certificate will be used for a TLS client
 578 #tls_www_client
 579
 580 # Whether this certificate will be used for a TLS server
 581 #tls_www_server
 582
 583 # Whether this certificate will be used to sign data (needed
 584 # in TLS DHE ciphersuites).
 585 signing_key
 586
 587 # Whether this certificate will be used to encrypt data (needed
 588 # in TLS RSA ciphersuites). Note that it is preferred to use different
 589 # keys for encryption and signing.
 590 #encryption_key
 591
 592 # Whether this key will be used to sign other certificates.
 593 #cert_signing_key
 594
 595 # Whether this key will be used to sign CRLs.
 596 #crl_signing_key
 597
 598 # Whether this key will be used to sign code.
 599 #code_signing_key
 600
 601 # Whether this key will be used to sign OCSP data.
 602 #ocsp_signing_key
 603
 604 # Whether this key will be used for time stamping.
 605 #time_stamping_key
 606
 607 # Whether this key will be used for IPsec IKE operations.
 608 #ipsec_ike_key
 609
 610 ### end of key purpose OIDs
 611
 612 # When generating a certificate from a certificate
 613 # request, then honor the extensions stored in the request
 614 # and store them in the real certificate.
 615 #honor_crq_extensions
 616
 617 # Path length contraint. Sets the maximum number of
 618 # certificates that can be used to certify this certificate.
 619 # (i.e. the certificate chain length)
 620 #path_len = -1
 621 #path_len = 2
 622
 623 # OCSP URI
 624 # ocsp_uri = http://my.ocsp.server/ocsp
 625
 626 # CA issuers URI
 627 # ca_issuers_uri = http://my.ca.issuer
 628
 629 # Options for proxy certificates
 630 # proxy_policy_language = 1.3.6.1.5.5.7.21.1
 631
 632 # Options for generating a CRL
 633
 634 # next CRL update will be in 43 days (wow)
 635 #crl_next_update = 43
 636
 637 # this is the 5th CRL by this CA
 638 #crl_number = 5
 639
 640 @end example
 641
 642 _EOT_;
 643 };
 644