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