doc/invoke-certtool.texi

   1 @node certtool Invocation
   2 @section Invoking certtool
   3 @pindex certtool
   4 @ignore
   5 #  -*- buffer-read-only: t -*- vi: set ro:
   6 #
   7 # DO NOT EDIT THIS FILE   (invoke-certtool.texi)
   8 #
   9 # It has been AutoGen-ed  November 20, 2012 at 12:17:13 AM by AutoGen 5.16
  10 # From the definitions    ../src/certtool-args.def
  11 # and the template file   agtexi-cmd.tpl
  12 @end ignore
  13
  14
  15 Tool to parse and generate X.509 certificates, requests and private keys.
  16 It can be used interactively or non interactively by
  17 specifying the template command line option.
  18
  19 This section was generated by @strong{AutoGen},
  20 using the @code{agtexi-cmd} template and the option descriptions for the @code{certtool} program.
  21 This software is released under the GNU General Public License, version 3 or later.
  22
  23
  24 @anchor{certtool usage}
  25 @subheading certtool help/usage (-h)
  26 @cindex certtool help
  27
  28 This is the automatically generated usage text for certtool.
  29 The text printed is the same whether for the @code{help} option (-h) or the @code{more-help} option (-!).  @code{more-help} will print
  30 the usage text by passing it through a pager program.
  31 @code{more-help} is disabled on platforms without a working
  32 @code{fork(2)} function.  The @code{PAGER} environment variable is
  33 used to select the program, defaulting to @file{more}.  Both will exit
  34 with a status code of 0.
  35
  36 @exampleindent 0
  37 @example
  38 certtool - GnuTLS certificate tool - Ver. @@VERSION@@
  39 USAGE:  certtool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]...
  40
  41    -d, --debug=num            Enable debugging.
  42                                 - It must be in the range:
  43                                   0 to 9999
  44    -V, --verbose              More verbose output
  45                                 - may appear multiple times
  46        --infile=file          Input file
  47                                 - file must pre-exist
  48        --outfile=str          Output file
  49    -s, --generate-self-signed  Generate a self-signed certificate
  50    -c, --generate-certificate  Generate a signed certificate
  51        --generate-proxy       Generates a proxy certificate
  52        --generate-crl         Generate a CRL
  53    -u, --update-certificate   Update a signed certificate
  54    -p, --generate-privkey     Generate a private key
  55    -q, --generate-request     Generate a PKCS #10 certificate request
  56    -e, --verify-chain         Verify a PEM encoded certificate chain.
  57        --verify               Verify a PEM encoded certificate chain using a trusted list.
  58                                 - requires these options:
  59                                 load-ca-certificate
  60        --verify-crl           Verify a CRL using a trusted list.
  61                                 - requires these options:
  62                                 load-ca-certificate
  63        --generate-dh-params   Generate PKCS #3 encoded Diffie-Hellman parameters.
  64        --get-dh-params        Get the included PKCS #3 encoded Diffie-Hellman parameters.
  65        --dh-info              Print information PKCS #3 encoded Diffie-Hellman parameters
  66        --load-privkey=str     Loads a private key file
  67        --load-pubkey=str      Loads a public key file
  68        --load-request=file    Loads a certificate request file
  69                                 - file must pre-exist
  70        --load-certificate=str Loads a certificate file
  71        --load-ca-privkey=str  Loads the certificate authority's private key file
  72        --load-ca-certificate=str Loads the certificate authority's certificate file
  73        --password=str         Password to use
  74        --null-password        Enforce a NULL password
  75    -i, --certificate-info     Print information on the given certificate
  76        --certificate-pubkey   Print certificate's public key
  77        --pgp-certificate-info  Print information on the given OpenPGP certificate
  78        --pgp-ring-info        Print information on the given OpenPGP keyring structure
  79    -l, --crl-info             Print information on the given CRL structure
  80        --crq-info             Print information on the given certificate request
  81        --no-crq-extensions    Do not use extensions in certificate requests
  82        --p12-info             Print information on a PKCS #12 structure
  83        --p7-info              Print information on a PKCS #7 structure
  84        --smime-to-p7          Convert S/MIME to PKCS #7 structure
  85    -k, --key-info             Print information on a private key
  86        --pgp-key-info         Print information on an OpenPGP private key
  87        --pubkey-info          Print information on a public key
  88        --v1                   Generate an X.509 version 1 certificate (with no extensions)
  89        --to-p12               Generate a PKCS #12 structure
  90                                 - requires these options:
  91                                 load-certificate
  92        --to-p8                Generate a PKCS #8 structure
  93    -8, --pkcs8                Use PKCS #8 format for private keys
  94        --rsa                  Generate RSA key
  95        --dsa                  Generate DSA key
  96        --ecc                  Generate ECC (ECDSA) key
  97        --hash=str             Hash algorithm to use for signing.
  98        --inder                Use DER format for input certificates and private keys.
  99                                 - disabled as --no-inder
 100        --inraw                This is an alias for 'inder'
 101        --outder               Use DER format for output certificates and private keys
 102                                 - disabled as --no-outder
 103        --outraw               This is an alias for 'outder'
 104        --bits=num             Specify the number of bits for key generate
 105        --sec-param=str        Specify the security level [low, legacy, normal, high, ultra].
 106        --disable-quick-random  No effect
 107        --template=file        Template file to use for non-interactive operation
 108                                 - file must pre-exist
 109        --pkcs-cipher=str      Cipher to use for PKCS #8 and #12 operations
 110    -v, --version[=arg]        Output version information and exit
 111    -h, --help                 Display extended usage information and exit
 112    -!, --more-help            Extended usage information passed thru pager
 113
 114 Options are specified by doubled hyphens and their name or by a single
 115 hyphen and the flag character.
 116
 117
 118
 119 Tool to parse and generate X.509 certificates, requests and private keys.
 120 It can be used interactively or non interactively by specifying the
 121 template command line option.
 122
 123 please send bug reports to:  bug-gnutls@@gnu.org
 124 @end example
 125 @exampleindent 4
 126
 127 @anchor{certtool debug}
 128 @subheading debug option (-d)
 129
 130 This is the ``enable debugging.'' option.
 131 This option takes an argument number.
 132 Specifies the debug level.
 133 @anchor{certtool verify-chain}
 134 @subheading verify-chain option (-e)
 135
 136 This is the ``verify a pem encoded certificate chain.'' option.
 137 The last certificate in the chain must be a self signed one.
 138 @anchor{certtool verify}
 139 @subheading verify option
 140
 141 This is the ``verify a pem encoded certificate chain using a trusted list.'' option.
 142
 143 @noindent
 144 This option has some usage constraints.  It:
 145 @itemize @bullet
 146 @item
 147 must appear in combination with the following options:
 148 load-ca-certificate.
 149 @end itemize
 150
 151 The trusted certificate list must be loaded with --load-ca-certificate.
 152 @anchor{certtool verify-crl}
 153 @subheading verify-crl option
 154
 155 This is the ``verify a crl using a trusted list.'' option.
 156
 157 @noindent
 158 This option has some usage constraints.  It:
 159 @itemize @bullet
 160 @item
 161 must appear in combination with the following options:
 162 load-ca-certificate.
 163 @end itemize
 164
 165 The trusted certificate list must be loaded with --load-ca-certificate.
 166 @anchor{certtool get-dh-params}
 167 @subheading get-dh-params option
 168
 169 This is the ``get the included pkcs #3 encoded diffie-hellman parameters.'' option.
 170 Returns stored DH parameters in GnuTLS. Those parameters are used in the SRP protocol. The parameters returned by fresh generation
 171 are more efficient since GnuTLS 3.0.9.
 172 @anchor{certtool load-privkey}
 173 @subheading load-privkey option
 174
 175 This is the ``loads a private key file'' option.
 176 This option takes an argument string.
 177 This can be either a file or a PKCS #11 URL
 178 @anchor{certtool load-pubkey}
 179 @subheading load-pubkey option
 180
 181 This is the ``loads a public key file'' option.
 182 This option takes an argument string.
 183 This can be either a file or a PKCS #11 URL
 184 @anchor{certtool load-certificate}
 185 @subheading load-certificate option
 186
 187 This is the ``loads a certificate file'' option.
 188 This option takes an argument string.
 189 This can be either a file or a PKCS #11 URL
 190 @anchor{certtool load-ca-privkey}
 191 @subheading load-ca-privkey option
 192
 193 This is the ``loads the certificate authority's private key file'' option.
 194 This option takes an argument string.
 195 This can be either a file or a PKCS #11 URL
 196 @anchor{certtool load-ca-certificate}
 197 @subheading load-ca-certificate option
 198
 199 This is the ``loads the certificate authority's certificate file'' option.
 200 This option takes an argument string.
 201 This can be either a file or a PKCS #11 URL
 202 @anchor{certtool null-password}
 203 @subheading null-password option
 204
 205 This is the ``enforce a null password'' option.
 206 This option enforces a NULL password. This may be different than the empty password in some schemas.
 207 @anchor{certtool pubkey-info}
 208 @subheading pubkey-info option
 209
 210 This is the ``print information on a public key'' option.
 211 The option combined with --load-pubkey, --load-privkey and --load-certificate will extract the public key of the object in question.
 212 @anchor{certtool to-p12}
 213 @subheading to-p12 option
 214
 215 This is the ``generate a pkcs #12 structure'' option.
 216
 217 @noindent
 218 This option has some usage constraints.  It:
 219 @itemize @bullet
 220 @item
 221 must appear in combination with the following options:
 222 load-certificate.
 223 @end itemize
 224
 225 It requires a certificate, a private key and possibly a CA certificate to be specified.
 226 @anchor{certtool hash}
 227 @subheading hash option
 228
 229 This is the ``hash algorithm to use for signing.'' option.
 230 This option takes an argument string.
 231 Available hash functions are SHA1, RMD160, SHA256, SHA384, SHA512.
 232 @anchor{certtool inder}
 233 @subheading inder option
 234
 235 This is the ``use der format for input certificates and private keys.'' option.
 236 The input files will be assumed to be in DER or RAW format.
 237 Unlike options that in PEM input would allow multiple input data (e.g. multiple
 238 certificates), when reading in DER format a single data structure is read.
 239 @anchor{certtool inraw}
 240 @subheading inraw option
 241
 242 This is an alias for the inder option,
 243 @pxref{certtool inder, the inder option documentation}.
 244
 245 @anchor{certtool outder}
 246 @subheading outder option
 247
 248 This is the ``use der format for output certificates and private keys'' option.
 249 The output will be in DER or RAW format.
 250 @anchor{certtool outraw}
 251 @subheading outraw option
 252
 253 This is an alias for the outder option,
 254 @pxref{certtool outder, the outder option documentation}.
 255
 256 @anchor{certtool sec-param}
 257 @subheading sec-param option
 258
 259 This is the ``specify the security level [low, legacy, normal, high, ultra].'' option.
 260 This option takes an argument string @file{Security parameter}.
 261 This is alternative to the bits option.
 262 @anchor{certtool pkcs-cipher}
 263 @subheading pkcs-cipher option
 264
 265 This is the ``cipher to use for pkcs #8 and #12 operations'' option.
 266 This option takes an argument string @file{Cipher}.
 267 Cipher may be one of 3des, 3des-pkcs12, aes-128, aes-192, aes-256, rc2-40, arcfour.
 268 @anchor{certtool exit status}
 269 @subheading certtool exit status
 270
 271 One of the following exit values will be returned:
 272 @table @samp
 273 @item 0 (EXIT_SUCCESS)
 274 Successful program execution.
 275 @item 1 (EXIT_FAILURE)
 276 The operation failed or the command syntax was not valid.
 277 @end table
 278 @anchor{certtool See Also}
 279 @subheading certtool See Also
 280     p11tool (1)
 281
 282 @anchor{certtool Examples}
 283 @subheading certtool Examples
 284 @subheading Generating private keys
 285 To create an RSA private key, run:
 286 @example
 287 $ certtool --generate-privkey --outfile key.pem --rsa
 288 @end example
 289
 290 To create a DSA or elliptic curves (ECDSA) private key use the
 291 above command combined with 'dsa' or 'ecc' options.
 292
 293 @subheading Generating certificate requests
 294 To create a certificate request (needed when the certificate is  issued  by
 295 another party), run:
 296 @example
 297 certtool --generate-request --load-privkey key.pem \
 298    --outfile request.pem
 299 @end example
 300
 301 If the private key is stored in a smart card you can generate
 302 a request by specifying the private key object URL.
 303 @example
 304 $ ./certtool --generate-request --load-privkey "pkcs11:..." \
 305   --load-pubkey "pkcs11:..." --outfile request.pem
 306 @end example
 307
 308
 309 @subheading Generating a self-signed certificate
 310 To create a self signed certificate, use the command:
 311 @example
 312 $ certtool --generate-privkey --outfile ca-key.pem
 313 $ certtool --generate-self-signed --load-privkey ca-key.pem \
 314    --outfile ca-cert.pem
 315 @end example
 316
 317 Note that a self-signed certificate usually belongs to a certificate
 318 authority, that signs other certificates.
 319
 320 @subheading Generating a certificate
 321 To generate a certificate using the previous request, use the command:
 322 @example
 323 $ certtool --generate-certificate --load-request request.pem \
 324    --outfile cert.pem --load-ca-certificate ca-cert.pem \
 325    --load-ca-privkey ca-key.pem
 326 @end example
 327
 328 To generate a certificate using the private key only, use the command:
 329 @example
 330 $ certtool --generate-certificate --load-privkey key.pem \
 331    --outfile cert.pem --load-ca-certificate ca-cert.pem \
 332    --load-ca-privkey ca-key.pem
 333 @end example
 334
 335 @subheading Certificate information
 336 To view the certificate information, use:
 337 @example
 338 $ certtool --certificate-info --infile cert.pem
 339 @end example
 340
 341 @subheading PKCS #12 structure generation
 342 To generate a PKCS #12 structure using the previous key and certificate,
 343 use the command:
 344 @example
 345 $ certtool --load-certificate cert.pem --load-privkey key.pem \
 346    --to-p12 --outder --outfile key.p12
 347 @end example
 348
 349 Some tools (reportedly web browsers) have problems with that file
 350 because it does not contain the CA certificate for the certificate.
 351 To work around that problem in the tool, you can use the
 352 --load-ca-certificate parameter as follows:
 353
 354 @example
 355 $ certtool --load-ca-certificate ca.pem \
 356   --load-certificate cert.pem --load-privkey key.pem \
 357   --to-p12 --outder --outfile key.p12
 358 @end example
 359
 360 @subheading Diffie-Hellman parameter generation
 361 To generate parameters for Diffie-Hellman key exchange, use the command:
 362 @example
 363 $ certtool --generate-dh-params --outfile dh.pem --sec-param normal
 364 @end example
 365
 366 @subheading Proxy certificate generation
 367 Proxy certificate can be used to delegate your credential to a
 368 temporary, typically short-lived, certificate.  To create one from the
 369 previously created certificate, first create a temporary key and then
 370 generate a proxy certificate for it, using the commands:
 371
 372 @example
 373 $ certtool --generate-privkey > proxy-key.pem
 374 $ certtool --generate-proxy --load-ca-privkey key.pem \
 375   --load-privkey proxy-key.pem --load-certificate cert.pem \
 376   --outfile proxy-cert.pem
 377 @end example
 378
 379 @subheading Certificate revocation list generation
 380 To create an empty Certificate Revocation List (CRL) do:
 381
 382 @example
 383 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
 384            --load-ca-certificate x509-ca.pem
 385 @end example
 386
 387 To create a CRL that contains some revoked certificates, place the
 388 certificates in a file and use @code{--load-certificate} as follows:
 389
 390 @example
 391 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
 392   --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
 393 @end example
 394
 395 To verify a Certificate Revocation List (CRL) do:
 396
 397 @example
 398 $ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
 399 @end example
 400
 401 @anchor{certtool Files}
 402 @subheading certtool Files
 403 @subheading Certtool's template file format
 404 A template file can be used to avoid the interactive questions of
 405 certtool. Initially create a file named 'cert.cfg' that contains the information
 406 about the certificate. The template can be used as below:
 407
 408 @example
 409 $ certtool --generate-certificate cert.pem --load-privkey key.pem  \
 410    --template cert.cfg \
 411    --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
 412 @end example
 413
 414 An example certtool template file that can be used to generate a certificate
 415 request or a self signed certificate follows.
 416
 417 @example
 418 # X.509 Certificate options
 419 #
 420 # DN options
 421
 422 # The organization of the subject.
 423 organization = "Koko inc."
 424
 425 # The organizational unit of the subject.
 426 unit = "sleeping dept."
 427
 428 # The locality of the subject.
 429 # locality =
 430
 431 # The state of the certificate owner.
 432 state = "Attiki"
 433
 434 # The country of the subject. Two letter code.
 435 country = GR
 436
 437 # The common name of the certificate owner.
 438 cn = "Cindy Lauper"
 439
 440 # A user id of the certificate owner.
 441 #uid = "clauper"
 442
 443 # Set domain components
 444 #dc = "name"
 445 #dc = "domain"
 446
 447 # If the supported DN OIDs are not adequate you can set
 448 # any OID here.
 449 # For example set the X.520 Title and the X.520 Pseudonym
 450 # by using OID and string pairs.
 451 #dn_oid = 2.5.4.12 Dr.
 452 #dn_oid = 2.5.4.65 jackal
 453
 454 # This is deprecated and should not be used in new
 455 # certificates.
 456 # pkcs9_email = "none@@none.org"
 457
 458 # The serial number of the certificate
 459 serial = 007
 460
 461 # In how many days, counting from today, this certificate will expire.
 462 expiration_days = 700
 463
 464 # X.509 v3 extensions
 465
 466 # A dnsname in case of a WWW server.
 467 #dns_name = "www.none.org"
 468 #dns_name = "www.morethanone.org"
 469
 470 # A subject alternative name URI
 471 #uri = "http://www.example.com"
 472
 473 # An IP address in case of a server.
 474 #ip_address = "192.168.1.1"
 475
 476 # An email in case of a person
 477 email = "none@@none.org"
 478
 479 # Challenge password used in certificate requests
 480 challenge_passwd = 123456
 481
 482 # An URL that has CRLs (certificate revocation lists)
 483 # available. Needed in CA certificates.
 484 #crl_dist_points = "http://www.getcrl.crl/getcrl/"
 485
 486 # Whether this is a CA certificate or not
 487 #ca
 488
 489 # for microsoft smart card logon
 490 # key_purpose_oid = 1.3.6.1.4.1.311.20.2.2
 491
 492 ### Other predefined key purpose OIDs
 493
 494 # Whether this certificate will be used for a TLS client
 495 #tls_www_client
 496
 497 # Whether this certificate will be used for a TLS server
 498 #tls_www_server
 499
 500 # Whether this certificate will be used to sign data (needed
 501 # in TLS DHE ciphersuites).
 502 signing_key
 503
 504 # Whether this certificate will be used to encrypt data (needed
 505 # in TLS RSA ciphersuites). Note that it is preferred to use different
 506 # keys for encryption and signing.
 507 #encryption_key
 508
 509 # Whether this key will be used to sign other certificates.
 510 #cert_signing_key
 511
 512 # Whether this key will be used to sign CRLs.
 513 #crl_signing_key
 514
 515 # Whether this key will be used to sign code.
 516 #code_signing_key
 517
 518 # Whether this key will be used to sign OCSP data.
 519 #ocsp_signing_key
 520
 521 # Whether this key will be used for time stamping.
 522 #time_stamping_key
 523
 524 # Whether this key will be used for IPsec IKE operations.
 525 #ipsec_ike_key
 526
 527 ### end of key purpose OIDs
 528
 529 # When generating a certificate from a certificate
 530 # request, then honor the extensions stored in the request
 531 # and store them in the real certificate.
 532 #honor_crq_extensions
 533
 534 # Path length contraint. Sets the maximum number of
 535 # certificates that can be used to certify this certificate.
 536 # (i.e. the certificate chain length)
 537 #path_len = -1
 538 #path_len = 2
 539
 540 # OCSP URI
 541 # ocsp_uri = http://my.ocsp.server/ocsp
 542
 543 # CA issuers URI
 544 # ca_issuers_uri = http://my.ca.issuer
 545
 546 # Certificate policies
 547 # policy = 1.3.6.1.4.1.5484.1.10.99.1.0
 548 # policy1_txt = "This is a long policy to summarize"
 549 # policy1_url = http://www.example.com/a-policy-to-read
 550
 551 # policy = 1.3.6.1.4.1.5484.1.10.99.1.1
 552 # policy2_txt = "This is a short policy"
 553 # policy2_url = http://www.example.com/another-policy-to-read
 554
 555
 556 # Options for proxy certificates
 557 # proxy_policy_language = 1.3.6.1.5.5.7.21.1
 558
 559
 560 # Options for generating a CRL
 561
 562 # next CRL update will be in 43 days (wow)
 563 #crl_next_update = 43
 564
 565 # this is the 5th CRL by this CA
 566 #crl_number = 5
 567
 568 @end example
 569
 570