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