doc/invoke-certtool.texi

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