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