doc/invoke-certtool.texi

   1 @node certtool Invocation
   2 @section Invoking certtool
   3 @pindex certtool
   4 @cindex GnuTLS PKCS #11 tool
   5 @ignore
   6 #  -*- buffer-read-only: t -*- vi: set ro:
   7 #
   8 # DO NOT EDIT THIS FILE   (invoke-certtool.texi)
   9 #
  10 # It has been AutoGen-ed  October  8, 2012 at 04:55:06 PM by AutoGen 5.16
  11 # From the definitions    ../src/certtool-args.def
  12 # and the template file   agtexi-cmd.tpl
  13 @end ignore
  14
  15
  16 Tool to parse and generate X.509 certificates, requests and private keys.
  17 It can be used interactively or non interactively by
  18 specifying the template command line option.
  19
  20 This section was generated by @strong{AutoGen},
  21 using the @code{agtexi-cmd} template and the option descriptions for the @code{certtool} program.
  22 This software is released under the GNU General Public License, version 3 or later.
  23
  24
  25 @anchor{certtool usage}
  26 @subheading certtool help/usage (-h)
  27 @cindex certtool help
  28
  29 This is the automatically generated usage text for certtool.
  30 The text printed is the same whether for the @code{help} option (-h) or the @code{more-help} option (-!).  @code{more-help} will print
  31 the usage text by passing it through a pager program.
  32 @code{more-help} is disabled on platforms without a working
  33 @code{fork(2)} function.  The @code{PAGER} environment variable is
  34 used to select the program, defaulting to @file{more}.  Both will exit
  35 with a status code of 0.
  36
  37 @exampleindent 0
  38 @example
  39 certtool - GnuTLS PKCS #11 tool - Ver. @@VERSION@@
  40 USAGE:  certtool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]...
  41
  42    -d, --debug=num            Enable debugging.
  43                                 - It must be in the range:
  44                                   0 to 9999
  45        --infile=file          Input file
  46                                 - file must pre-exist
  47        --outfile=str          Output file
  48    -s, --generate-self-signed  Generate a self-signed certificate
  49    -c, --generate-certificate  Generate a signed certificate
  50        --generate-proxy       Generates a proxy certificate
  51        --generate-crl         Generate a CRL
  52    -u, --update-certificate   Update a signed certificate
  53    -p, --generate-privkey     Generate a private key
  54    -q, --generate-request     Generate a PKCS #10 certificate request
  55    -e, --verify-chain         Verify a PEM encoded certificate chain.
  56        --verify               Verify a PEM encoded certificate chain using a trusted list.
  57                                 - requires these options:
  58                                 load-ca-certificate
  59        --verify-crl           Verify a CRL using a trusted list.
  60                                 - requires these options:
  61                                 load-ca-certificate
  62        --generate-dh-params   Generate PKCS #3 encoded Diffie-Hellman parameters.
  63        --get-dh-params        Get the included PKCS #3 encoded Diffie-Hellman parameters.
  64        --dh-info              Print information PKCS #3 encoded Diffie-Hellman parameters
  65        --load-privkey=str     Loads a private key file
  66        --load-pubkey=str      Loads a public key file
  67        --load-request=file    Loads a certificate request file
  68                                 - file must pre-exist
  69        --load-certificate=str Loads a certificate file
  70        --load-ca-privkey=str  Loads the certificate authority's private key file
  71        --load-ca-certificate=str Loads the certificate authority's certificate file
  72        --password=str         Password to use
  73        --null-password        Enforce a NULL password
  74    -i, --certificate-info     Print information on the given certificate
  75        --certificate-pubkey   Print certificate's public key
  76        --pgp-certificate-info  Print information on the given OpenPGP certificate
  77        --pgp-ring-info        Print information on the given OpenPGP keyring structure
  78    -l, --crl-info             Print information on the given CRL structure
  79        --crq-info             Print information on the given certificate request
  80        --no-crq-extensions    Do not use extensions in certificate requests
  81        --p12-info             Print information on a PKCS #12 structure
  82        --p7-info              Print information on a PKCS #7 structure
  83        --smime-to-p7          Convert S/MIME to PKCS #7 structure
  84    -k, --key-info             Print information on a private key
  85        --pgp-key-info         Print information on an OpenPGP private key
  86        --pubkey-info          Print information on a public key
  87        --v1                   Generate an X.509 version 1 certificate (with no extensions)
  88        --to-p12               Generate a PKCS #12 structure
  89                                 - requires these options:
  90                                 load-certificate
  91        --to-p8                Generate a PKCS #8 structure
  92    -8, --pkcs8                Use PKCS #8 format for private keys
  93        --rsa                  Generate RSA key
  94        --dsa                  Generate DSA key
  95        --ecc                  Generate ECC (ECDSA) key
  96        --hash=str             Hash algorithm to use for signing.
  97        --inder                Use DER format for input certificates and private keys.
  98                                 - disabled as --no-inder
  99        --inraw                This is an alias for 'inder'
 100        --outder               Use DER format for output certificates and private keys
 101                                 - disabled as --no-outder
 102        --outraw               This is an alias for 'outder'
 103        --bits=num             Specify the number of bits for key generate
 104        --sec-param=str        Specify the security level [low, legacy, normal, high, ultra].
 105        --disable-quick-random  No effect
 106        --template=file        Template file to use for non-interactive operation
 107                                 - file must pre-exist
 108        --pkcs-cipher=str      Cipher to use for PKCS #8 and #12 operations
 109        --dane-rr              Print the DANE RR data on a certificate or public key
 110                                 - requires these options:
 111                                 dane-host
 112        --dane-host=str        Specify the hostname to be used in the DANE RR
 113        --dane-proto=str       The protocol set for DANE data (tcp, udp etc.)
 114        --dane-port=num        Specify the port number for the DANE data.
 115        --dane-ca              Whether the provided certificate or public key is a Certificate
 116 authority.
 117        --dane-local           Whether the provided certificate or public key is an unsigned local
 118 entity.
 119    -v, --version[=arg]        Output version information and exit
 120    -h, --help                 Display extended usage information and exit
 121    -!, --more-help            Extended usage information passed thru pager
 122
 123 Options are specified by doubled hyphens and their name or by a single
 124 hyphen and the flag character.
 125
 126
 127
 128 Tool to parse and generate X.509 certificates, requests and private keys.
 129 It can be used interactively or non interactively by specifying the
 130 template command line option.
 131
 132 please send bug reports to:  bug-gnutls@@gnu.org
 133 @end example
 134 @exampleindent 4
 135
 136 @anchor{certtool debug}
 137 @subheading debug option (-d)
 138 @cindex certtool-debug
 139
 140 This is the ``enable debugging.'' option.
 141 This option takes an argument number.
 142 Specifies the debug level.
 143 @anchor{certtool verify-chain}
 144 @subheading verify-chain option (-e)
 145 @cindex certtool-verify-chain
 146
 147 This is the ``verify a pem encoded certificate chain.'' option.
 148 The last certificate in the chain must be a self signed one.
 149 @anchor{certtool verify}
 150 @subheading verify option
 151 @cindex certtool-verify
 152
 153 This is the ``verify a pem encoded certificate chain using a trusted list.'' option.
 154
 155 @noindent
 156 This option has some usage constraints.  It:
 157 @itemize @bullet
 158 @item
 159 must appear in combination with the following options:
 160 load-ca-certificate.
 161 @end itemize
 162
 163 The trusted certificate list must be loaded with --load-ca-certificate.
 164 @anchor{certtool verify-crl}
 165 @subheading verify-crl option
 166 @cindex certtool-verify-crl
 167
 168 This is the ``verify a crl using a trusted list.'' option.
 169
 170 @noindent
 171 This option has some usage constraints.  It:
 172 @itemize @bullet
 173 @item
 174 must appear in combination with the following options:
 175 load-ca-certificate.
 176 @end itemize
 177
 178 The trusted certificate list must be loaded with --load-ca-certificate.
 179 @anchor{certtool get-dh-params}
 180 @subheading get-dh-params option
 181 @cindex certtool-get-dh-params
 182
 183 This is the ``get the included pkcs #3 encoded diffie-hellman parameters.'' option.
 184 Returns stored DH parameters in GnuTLS. Those parameters are used in the SRP protocol. The parameters returned by fresh generation
 185 are more efficient since GnuTLS 3.0.9.
 186 @anchor{certtool load-privkey}
 187 @subheading load-privkey option
 188 @cindex certtool-load-privkey
 189
 190 This is the ``loads a private key file'' option.
 191 This option takes an argument string.
 192 This can be either a file or a PKCS #11 URL
 193 @anchor{certtool load-pubkey}
 194 @subheading load-pubkey option
 195 @cindex certtool-load-pubkey
 196
 197 This is the ``loads a public key file'' option.
 198 This option takes an argument string.
 199 This can be either a file or a PKCS #11 URL
 200 @anchor{certtool load-certificate}
 201 @subheading load-certificate option
 202 @cindex certtool-load-certificate
 203
 204 This is the ``loads a certificate file'' option.
 205 This option takes an argument string.
 206 This can be either a file or a PKCS #11 URL
 207 @anchor{certtool load-ca-privkey}
 208 @subheading load-ca-privkey option
 209 @cindex certtool-load-ca-privkey
 210
 211 This is the ``loads the certificate authority's private key file'' option.
 212 This option takes an argument string.
 213 This can be either a file or a PKCS #11 URL
 214 @anchor{certtool load-ca-certificate}
 215 @subheading load-ca-certificate option
 216 @cindex certtool-load-ca-certificate
 217
 218 This is the ``loads the certificate authority's certificate file'' option.
 219 This option takes an argument string.
 220 This can be either a file or a PKCS #11 URL
 221 @anchor{certtool null-password}
 222 @subheading null-password option
 223 @cindex certtool-null-password
 224
 225 This is the ``enforce a null password'' option.
 226 This option enforces a NULL password. This may be different than the empty password in some schemas.
 227 @anchor{certtool to-p12}
 228 @subheading to-p12 option
 229 @cindex certtool-to-p12
 230
 231 This is the ``generate a pkcs #12 structure'' option.
 232
 233 @noindent
 234 This option has some usage constraints.  It:
 235 @itemize @bullet
 236 @item
 237 must appear in combination with the following options:
 238 load-certificate.
 239 @end itemize
 240
 241 It requires a certificate, a private key and possibly a CA certificate to be specified.
 242 @anchor{certtool hash}
 243 @subheading hash option
 244 @cindex certtool-hash
 245
 246 This is the ``hash algorithm to use for signing.'' option.
 247 This option takes an argument string.
 248 Available hash functions are SHA1, RMD160, SHA256, SHA384, SHA512.
 249 @anchor{certtool inder}
 250 @subheading inder option
 251 @cindex certtool-inder
 252
 253 This is the ``use der format for input certificates and private keys.'' option.
 254 The input files will be assumed to be in DER or RAW format.
 255 Unlike options that in PEM input would allow multiple input data (e.g. multiple
 256 certificates), when reading in DER format a single data structure is read.
 257 @anchor{certtool inraw}
 258 @subheading inraw option
 259 @cindex certtool-inraw
 260
 261 This is an alias for the inder option,
 262 @pxref{certtool inder, the inder option documentation}.
 263
 264 @anchor{certtool outder}
 265 @subheading outder option
 266 @cindex certtool-outder
 267
 268 This is the ``use der format for output certificates and private keys'' option.
 269 The output will be in DER or RAW format.
 270 @anchor{certtool outraw}
 271 @subheading outraw option
 272 @cindex certtool-outraw
 273
 274 This is an alias for the outder option,
 275 @pxref{certtool outder, the outder option documentation}.
 276
 277 @anchor{certtool sec-param}
 278 @subheading sec-param option
 279 @cindex certtool-sec-param
 280
 281 This is the ``specify the security level [low, legacy, normal, high, ultra].'' option.
 282 This option takes an argument string @file{Security parameter}.
 283 This is alternative to the bits option.
 284 @anchor{certtool pkcs-cipher}
 285 @subheading pkcs-cipher option
 286 @cindex certtool-pkcs-cipher
 287
 288 This is the ``cipher to use for pkcs #8 and #12 operations'' option.
 289 This option takes an argument string @file{Cipher}.
 290 Cipher may be one of 3des, 3des-pkcs12, aes-128, aes-192, aes-256, rc2-40, arcfour.
 291 @anchor{certtool dane-rr}
 292 @subheading dane-rr option
 293 @cindex certtool-dane-rr
 294
 295 This is the ``print the dane rr data on a certificate or public key'' option.
 296
 297 @noindent
 298 This option has some usage constraints.  It:
 299 @itemize @bullet
 300 @item
 301 must appear in combination with the following options:
 302 dane-host.
 303 @end itemize
 304
 305 This command prints the DANE RR data needed to enable DANE on a DNS server.
 306 @anchor{certtool dane-host}
 307 @subheading dane-host option
 308 @cindex certtool-dane-host
 309
 310 This is the ``specify the hostname to be used in the dane rr'' option.
 311 This option takes an argument string @file{Hostname}.
 312 This command sets the hostname for the DANE RR.
 313 @anchor{certtool dane-proto}
 314 @subheading dane-proto option
 315 @cindex certtool-dane-proto
 316
 317 This is the ``the protocol set for dane data (tcp, udp etc.)'' option.
 318 This option takes an argument string @file{Protocol}.
 319 This command specifies the protocol for the service set in the DANE data.
 320 @anchor{certtool dane-ca}
 321 @subheading dane-ca option
 322 @cindex certtool-dane-ca
 323
 324 This is the ``whether the provided certificate or public key is a certificate authority.'' option.
 325 Marks the DANE RR as a CA certificate if specified.
 326 @anchor{certtool dane-local}
 327 @subheading dane-local option
 328 @cindex certtool-dane-local
 329
 330 This is the ``whether the provided certificate or public key is an unsigned local entity.'' option.
 331 DANE distinguishes certificates and public keys offered via the DNSSEC to trusted and local entities. Use this flag if this is a local entity.
 332 @anchor{certtool exit status}
 333 @subheading certtool exit status
 334
 335 One of the following exit values will be returned:
 336 @table @samp
 337 @item 0 (EXIT_SUCCESS)
 338 Successful program execution.
 339 @item 1 (EXIT_FAILURE)
 340 The operation failed or the command syntax was not valid.
 341 @end table
 342 @anchor{certtool See Also}
 343 @subheading certtool See Also
 344     p11tool (1)
 345
 346 @anchor{certtool Examples}
 347 @subheading certtool Examples
 348 @subheading Generating private keys
 349 To create an RSA private key, run:
 350 @example
 351 $ certtool --generate-privkey --outfile key.pem --rsa
 352 @end example
 353
 354 To create a DSA or elliptic curves (ECDSA) private key use the
 355 above command combined with 'dsa' or 'ecc' options.
 356
 357 @subheading Generating certificate requests
 358 To create a certificate request (needed when the certificate is  issued  by
 359 another party), run:
 360 @example
 361 certtool --generate-request --load-privkey key.pem \
 362    --outfile request.pem
 363 @end example
 364
 365 If the private key is stored in a smart card you can generate
 366 a request by specifying the private key object URL.
 367 @example
 368 $ ./certtool --generate-request --load-privkey "pkcs11:..." \
 369   --load-pubkey "pkcs11:..." --outfile request.pem
 370 @end example
 371
 372
 373 @subheading Generating a self-signed certificate
 374 To create a self signed certificate, use the command:
 375 @example
 376 $ certtool --generate-privkey --outfile ca-key.pem
 377 $ certtool --generate-self-signed --load-privkey ca-key.pem \
 378    --outfile ca-cert.pem
 379 @end example
 380
 381 Note that a self-signed certificate usually belongs to a certificate
 382 authority, that signs other certificates.
 383
 384 @subheading Generating a certificate
 385 To generate a certificate using the previous request, use the command:
 386 @example
 387 $ certtool --generate-certificate --load-request request.pem \
 388    --outfile cert.pem --load-ca-certificate ca-cert.pem \
 389    --load-ca-privkey ca-key.pem
 390 @end example
 391
 392 To generate a certificate using the private key only, use the command:
 393 @example
 394 $ certtool --generate-certificate --load-privkey key.pem \
 395    --outfile cert.pem --load-ca-certificate ca-cert.pem \
 396    --load-ca-privkey ca-key.pem
 397 @end example
 398
 399 @subheading Certificate information
 400 To view the certificate information, use:
 401 @example
 402 $ certtool --certificate-info --infile cert.pem
 403 @end example
 404
 405 @subheading PKCS #12 structure generation
 406 To generate a PKCS #12 structure using the previous key and certificate,
 407 use the command:
 408 @example
 409 $ certtool --load-certificate cert.pem --load-privkey key.pem \
 410    --to-p12 --outder --outfile key.p12
 411 @end example
 412
 413 Some tools (reportedly web browsers) have problems with that file
 414 because it does not contain the CA certificate for the certificate.
 415 To work around that problem in the tool, you can use the
 416 --load-ca-certificate parameter as follows:
 417
 418 @example
 419 $ certtool --load-ca-certificate ca.pem \
 420   --load-certificate cert.pem --load-privkey key.pem \
 421   --to-p12 --outder --outfile key.p12
 422 @end example
 423
 424 @subheading Diffie-Hellman parameter generation
 425 To generate parameters for Diffie-Hellman key exchange, use the command:
 426 @example
 427 $ certtool --generate-dh-params --outfile dh.pem --sec-param normal
 428 @end example
 429
 430 @subheading Proxy certificate generation
 431 Proxy certificate can be used to delegate your credential to a
 432 temporary, typically short-lived, certificate.  To create one from the
 433 previously created certificate, first create a temporary key and then
 434 generate a proxy certificate for it, using the commands:
 435
 436 @example
 437 $ certtool --generate-privkey > proxy-key.pem
 438 $ certtool --generate-proxy --load-ca-privkey key.pem \
 439   --load-privkey proxy-key.pem --load-certificate cert.pem \
 440   --outfile proxy-cert.pem
 441 @end example
 442
 443 @subheading Certificate revocation list generation
 444 To create an empty Certificate Revocation List (CRL) do:
 445
 446 @example
 447 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
 448            --load-ca-certificate x509-ca.pem
 449 @end example
 450
 451 To create a CRL that contains some revoked certificates, place the
 452 certificates in a file and use @code{--load-certificate} as follows:
 453
 454 @example
 455 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
 456   --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
 457 @end example
 458
 459 To verify a Certificate Revocation List (CRL) do:
 460
 461 @example
 462 $ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
 463 @end example
 464
 465 @subheading DANE RR generation
 466 To create a DANE resource record for a CA signed certificate use the following commands.
 467
 468 @example
 469 $ certtool --dane-rr --dane-host www.example.com --load-certificate cert.pem
 470 @end example
 471
 472 For a self signed certificate use:
 473 @example
 474 $ certtool --dane-rr --dane-host www.example.com --load-certificate cert.pem \
 475   --dane-local
 476 @end example
 477
 478 In order to create a record for the signer of your certificate use:
 479 @example
 480 $ certtool --dane-rr --dane-host www.example.com --load-certificate cert.pem \
 481   --dane-ca
 482 @end example
 483
 484 @anchor{certtool Files}
 485 @subheading certtool Files
 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