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