1 @node certtool Invocation
2 @section Invoking certtool
4 @cindex GnuTLS PKCS #11 tool
6 # -*- buffer-read-only: t -*- vi: set ro:
8 # DO NOT EDIT THIS FILE (invoke-certtool.texi)
10 # It has been AutoGen-ed October 9, 2012 at 10:59:40 PM by AutoGen 5.16
11 # From the definitions ../src/certtool-args.def
12 # and the template file agtexi-cmd.tpl
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.
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.
25 @anchor{certtool usage}
26 @subheading certtool help/usage (-h)
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.
39 certtool - GnuTLS PKCS #11 tool - Ver. @@VERSION@@
40 USAGE: certtool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]...
42 -d, --debug=num Enable debugging.
43 - It must be in the range:
45 -V, --verbose More verbose output
46 - may appear multiple times
47 --infile=file Input file
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:
61 --verify-crl Verify a CRL using a trusted list.
62 - requires these options:
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
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:
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 --dane-tlsa-rr Print the DANE RR data on a certificate or public key
112 - requires these options:
114 --dane-host=str Specify the hostname to be used in the DANE RR
115 --dane-proto=str The protocol set for DANE data (tcp, udp etc.)
116 --dane-port=num Specify the port number for the DANE data.
117 --dane-ca Whether the provided certificate or public key is a Certificate
119 --dane-x509 Use the hash of the X.509 certificate, rather than the public key.
120 --dane-local The provided certificate or public key is a local entity.
121 -v, --version[=arg] Output version information and exit
122 -h, --help Display extended usage information and exit
123 -!, --more-help Extended usage information passed thru pager
125 Options are specified by doubled hyphens and their name or by a single
126 hyphen and the flag character.
130 Tool to parse and generate X.509 certificates, requests and private keys.
131 It can be used interactively or non interactively by specifying the
132 template command line option.
134 please send bug reports to: bug-gnutls@@gnu.org
138 @anchor{certtool debug}
139 @subheading debug option (-d)
140 @cindex certtool-debug
142 This is the ``enable debugging.'' option.
143 This option takes an argument number.
144 Specifies the debug level.
145 @anchor{certtool verify-chain}
146 @subheading verify-chain option (-e)
147 @cindex certtool-verify-chain
149 This is the ``verify a pem encoded certificate chain.'' option.
150 The last certificate in the chain must be a self signed one.
151 @anchor{certtool verify}
152 @subheading verify option
153 @cindex certtool-verify
155 This is the ``verify a pem encoded certificate chain using a trusted list.'' option.
158 This option has some usage constraints. It:
161 must appear in combination with the following options:
165 The trusted certificate list must be loaded with --load-ca-certificate.
166 @anchor{certtool verify-crl}
167 @subheading verify-crl option
168 @cindex certtool-verify-crl
170 This is the ``verify a crl using a trusted list.'' option.
173 This option has some usage constraints. It:
176 must appear in combination with the following options:
180 The trusted certificate list must be loaded with --load-ca-certificate.
181 @anchor{certtool get-dh-params}
182 @subheading get-dh-params option
183 @cindex certtool-get-dh-params
185 This is the ``get the included pkcs #3 encoded diffie-hellman parameters.'' option.
186 Returns stored DH parameters in GnuTLS. Those parameters are used in the SRP protocol. The parameters returned by fresh generation
187 are more efficient since GnuTLS 3.0.9.
188 @anchor{certtool load-privkey}
189 @subheading load-privkey option
190 @cindex certtool-load-privkey
192 This is the ``loads a private key file'' option.
193 This option takes an argument string.
194 This can be either a file or a PKCS #11 URL
195 @anchor{certtool load-pubkey}
196 @subheading load-pubkey option
197 @cindex certtool-load-pubkey
199 This is the ``loads a public key file'' option.
200 This option takes an argument string.
201 This can be either a file or a PKCS #11 URL
202 @anchor{certtool load-certificate}
203 @subheading load-certificate option
204 @cindex certtool-load-certificate
206 This is the ``loads a certificate file'' option.
207 This option takes an argument string.
208 This can be either a file or a PKCS #11 URL
209 @anchor{certtool load-ca-privkey}
210 @subheading load-ca-privkey option
211 @cindex certtool-load-ca-privkey
213 This is the ``loads the certificate authority's private key file'' option.
214 This option takes an argument string.
215 This can be either a file or a PKCS #11 URL
216 @anchor{certtool load-ca-certificate}
217 @subheading load-ca-certificate option
218 @cindex certtool-load-ca-certificate
220 This is the ``loads the certificate authority's certificate file'' option.
221 This option takes an argument string.
222 This can be either a file or a PKCS #11 URL
223 @anchor{certtool null-password}
224 @subheading null-password option
225 @cindex certtool-null-password
227 This is the ``enforce a null password'' option.
228 This option enforces a NULL password. This may be different than the empty password in some schemas.
229 @anchor{certtool to-p12}
230 @subheading to-p12 option
231 @cindex certtool-to-p12
233 This is the ``generate a pkcs #12 structure'' option.
236 This option has some usage constraints. It:
239 must appear in combination with the following options:
243 It requires a certificate, a private key and possibly a CA certificate to be specified.
244 @anchor{certtool hash}
245 @subheading hash option
246 @cindex certtool-hash
248 This is the ``hash algorithm to use for signing.'' option.
249 This option takes an argument string.
250 Available hash functions are SHA1, RMD160, SHA256, SHA384, SHA512.
251 @anchor{certtool inder}
252 @subheading inder option
253 @cindex certtool-inder
255 This is the ``use der format for input certificates and private keys.'' option.
256 The input files will be assumed to be in DER or RAW format.
257 Unlike options that in PEM input would allow multiple input data (e.g. multiple
258 certificates), when reading in DER format a single data structure is read.
259 @anchor{certtool inraw}
260 @subheading inraw option
261 @cindex certtool-inraw
263 This is an alias for the inder option,
264 @pxref{certtool inder, the inder option documentation}.
266 @anchor{certtool outder}
267 @subheading outder option
268 @cindex certtool-outder
270 This is the ``use der format for output certificates and private keys'' option.
271 The output will be in DER or RAW format.
272 @anchor{certtool outraw}
273 @subheading outraw option
274 @cindex certtool-outraw
276 This is an alias for the outder option,
277 @pxref{certtool outder, the outder option documentation}.
279 @anchor{certtool sec-param}
280 @subheading sec-param option
281 @cindex certtool-sec-param
283 This is the ``specify the security level [low, legacy, normal, high, ultra].'' option.
284 This option takes an argument string @file{Security parameter}.
285 This is alternative to the bits option.
286 @anchor{certtool pkcs-cipher}
287 @subheading pkcs-cipher option
288 @cindex certtool-pkcs-cipher
290 This is the ``cipher to use for pkcs #8 and #12 operations'' option.
291 This option takes an argument string @file{Cipher}.
292 Cipher may be one of 3des, 3des-pkcs12, aes-128, aes-192, aes-256, rc2-40, arcfour.
293 @anchor{certtool dane-tlsa-rr}
294 @subheading dane-tlsa-rr option
295 @cindex certtool-dane-tlsa-rr
297 This is the ``print the dane rr data on a certificate or public key'' option.
300 This option has some usage constraints. It:
303 must appear in combination with the following options:
307 This command prints the DANE RR data needed to enable DANE on a DNS server.
308 @anchor{certtool dane-host}
309 @subheading dane-host option
310 @cindex certtool-dane-host
312 This is the ``specify the hostname to be used in the dane rr'' option.
313 This option takes an argument string @file{Hostname}.
314 This command sets the hostname for the DANE RR.
315 @anchor{certtool dane-proto}
316 @subheading dane-proto option
317 @cindex certtool-dane-proto
319 This is the ``the protocol set for dane data (tcp, udp etc.)'' option.
320 This option takes an argument string @file{Protocol}.
321 This command specifies the protocol for the service set in the DANE data.
322 @anchor{certtool dane-ca}
323 @subheading dane-ca option
324 @cindex certtool-dane-ca
326 This is the ``whether the provided certificate or public key is a certificate authority.'' option.
327 Marks the DANE RR as a CA certificate if specified.
328 @anchor{certtool dane-x509}
329 @subheading dane-x509 option
330 @cindex certtool-dane-x509
332 This is the ``use the hash of the x.509 certificate, rather than the public key.'' option.
333 This option forces the generated record to contain the hash of the full X.509 certificate. By default only the hash of the public key is used.
334 @anchor{certtool dane-local}
335 @subheading dane-local option
336 @cindex certtool-dane-local
338 This is the ``the provided certificate or public key is a local entity.'' option.
339 DANE distinguishes certificates and public keys offered via the DNSSEC to trusted and local entities. Use this flag if this is a local (and possibly unsigned) entity.
340 @anchor{certtool exit status}
341 @subheading certtool exit status
343 One of the following exit values will be returned:
345 @item 0 (EXIT_SUCCESS)
346 Successful program execution.
347 @item 1 (EXIT_FAILURE)
348 The operation failed or the command syntax was not valid.
350 @anchor{certtool See Also}
351 @subheading certtool See Also
354 @anchor{certtool Examples}
355 @subheading certtool Examples
356 @subheading Generating private keys
357 To create an RSA private key, run:
359 $ certtool --generate-privkey --outfile key.pem --rsa
362 To create a DSA or elliptic curves (ECDSA) private key use the
363 above command combined with 'dsa' or 'ecc' options.
365 @subheading Generating certificate requests
366 To create a certificate request (needed when the certificate is issued by
369 certtool --generate-request --load-privkey key.pem \
370 --outfile request.pem
373 If the private key is stored in a smart card you can generate
374 a request by specifying the private key object URL.
376 $ ./certtool --generate-request --load-privkey "pkcs11:..." \
377 --load-pubkey "pkcs11:..." --outfile request.pem
381 @subheading Generating a self-signed certificate
382 To create a self signed certificate, use the command:
384 $ certtool --generate-privkey --outfile ca-key.pem
385 $ certtool --generate-self-signed --load-privkey ca-key.pem \
386 --outfile ca-cert.pem
389 Note that a self-signed certificate usually belongs to a certificate
390 authority, that signs other certificates.
392 @subheading Generating a certificate
393 To generate a certificate using the previous request, use the command:
395 $ certtool --generate-certificate --load-request request.pem \
396 --outfile cert.pem --load-ca-certificate ca-cert.pem \
397 --load-ca-privkey ca-key.pem
400 To generate a certificate using the private key only, use the command:
402 $ certtool --generate-certificate --load-privkey key.pem \
403 --outfile cert.pem --load-ca-certificate ca-cert.pem \
404 --load-ca-privkey ca-key.pem
407 @subheading Certificate information
408 To view the certificate information, use:
410 $ certtool --certificate-info --infile cert.pem
413 @subheading PKCS #12 structure generation
414 To generate a PKCS #12 structure using the previous key and certificate,
417 $ certtool --load-certificate cert.pem --load-privkey key.pem \
418 --to-p12 --outder --outfile key.p12
421 Some tools (reportedly web browsers) have problems with that file
422 because it does not contain the CA certificate for the certificate.
423 To work around that problem in the tool, you can use the
424 --load-ca-certificate parameter as follows:
427 $ certtool --load-ca-certificate ca.pem \
428 --load-certificate cert.pem --load-privkey key.pem \
429 --to-p12 --outder --outfile key.p12
432 @subheading Diffie-Hellman parameter generation
433 To generate parameters for Diffie-Hellman key exchange, use the command:
435 $ certtool --generate-dh-params --outfile dh.pem --sec-param normal
438 @subheading Proxy certificate generation
439 Proxy certificate can be used to delegate your credential to a
440 temporary, typically short-lived, certificate. To create one from the
441 previously created certificate, first create a temporary key and then
442 generate a proxy certificate for it, using the commands:
445 $ certtool --generate-privkey > proxy-key.pem
446 $ certtool --generate-proxy --load-ca-privkey key.pem \
447 --load-privkey proxy-key.pem --load-certificate cert.pem \
448 --outfile proxy-cert.pem
451 @subheading Certificate revocation list generation
452 To create an empty Certificate Revocation List (CRL) do:
455 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
456 --load-ca-certificate x509-ca.pem
459 To create a CRL that contains some revoked certificates, place the
460 certificates in a file and use @code{--load-certificate} as follows:
463 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
464 --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
467 To verify a Certificate Revocation List (CRL) do:
470 $ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
473 @subheading DANE TLSA RR generation
476 To create a DANE TLSA resource record for a CA signed certificate use the following commands.
479 $ certtool --dane-tlsa-rr --dane-host www.example.com --load-certificate cert.pem
482 For a self signed certificate use:
484 $ certtool --dane-tlsa-rr --dane-host www.example.com --load-certificate cert.pem \
488 The latter is useful to add in your DNS entry even if your certificate is signed
489 by a CA. That way even users who do not trust your CA will be able to verify your
490 certificate using DANE.
492 In order to create a record for the signer of your certificate use:
494 $ certtool --dane-tlsa-rr --dane-host www.example.com --load-certificate cert.pem \
498 @anchor{certtool Files}
499 @subheading certtool Files
500 @subheading Certtool's template file format
501 A template file can be used to avoid the interactive questions of
502 certtool. Initially create a file named 'cert.cfg' that contains the information
503 about the certificate. The template can be used as below:
506 $ certtool --generate-certificate cert.pem --load-privkey key.pem \
507 --template cert.cfg \
508 --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
511 An example certtool template file that can be used to generate a certificate
512 request or a self signed certificate follows.
515 # X.509 Certificate options
519 # The organization of the subject.
520 organization = "Koko inc."
522 # The organizational unit of the subject.
523 unit = "sleeping dept."
525 # The locality of the subject.
528 # The state of the certificate owner.
531 # The country of the subject. Two letter code.
534 # The common name of the certificate owner.
537 # A user id of the certificate owner.
540 # Set domain components
544 # If the supported DN OIDs are not adequate you can set
546 # For example set the X.520 Title and the X.520 Pseudonym
547 # by using OID and string pairs.
548 #dn_oid = 2.5.4.12 Dr.
549 #dn_oid = 2.5.4.65 jackal
551 # This is deprecated and should not be used in new
553 # pkcs9_email = "none@@none.org"
555 # The serial number of the certificate
558 # In how many days, counting from today, this certificate will expire.
559 expiration_days = 700
561 # X.509 v3 extensions
563 # A dnsname in case of a WWW server.
564 #dns_name = "www.none.org"
565 #dns_name = "www.morethanone.org"
567 # A subject alternative name URI
568 #uri = "http://www.example.com"
570 # An IP address in case of a server.
571 #ip_address = "192.168.1.1"
573 # An email in case of a person
574 email = "none@@none.org"
576 # Challenge password used in certificate requests
577 challenge_passwd = 123456
579 # An URL that has CRLs (certificate revocation lists)
580 # available. Needed in CA certificates.
581 #crl_dist_points = "http://www.getcrl.crl/getcrl/"
583 # Whether this is a CA certificate or not
586 # for microsoft smart card logon
587 # key_purpose_oid = 1.3.6.1.4.1.311.20.2.2
589 ### Other predefined key purpose OIDs
591 # Whether this certificate will be used for a TLS client
594 # Whether this certificate will be used for a TLS server
597 # Whether this certificate will be used to sign data (needed
598 # in TLS DHE ciphersuites).
601 # Whether this certificate will be used to encrypt data (needed
602 # in TLS RSA ciphersuites). Note that it is preferred to use different
603 # keys for encryption and signing.
606 # Whether this key will be used to sign other certificates.
609 # Whether this key will be used to sign CRLs.
612 # Whether this key will be used to sign code.
615 # Whether this key will be used to sign OCSP data.
618 # Whether this key will be used for time stamping.
621 # Whether this key will be used for IPsec IKE operations.
624 ### end of key purpose OIDs
626 # When generating a certificate from a certificate
627 # request, then honor the extensions stored in the request
628 # and store them in the real certificate.
629 #honor_crq_extensions
631 # Path length contraint. Sets the maximum number of
632 # certificates that can be used to certify this certificate.
633 # (i.e. the certificate chain length)
638 # ocsp_uri = http://my.ocsp.server/ocsp
641 # ca_issuers_uri = http://my.ca.issuer
643 # Options for proxy certificates
644 # proxy_policy_language = 1.3.6.1.5.5.7.21.1
646 # Options for generating a CRL
648 # next CRL update will be in 43 days (wow)
649 #crl_next_update = 43
651 # this is the 5th CRL by this CA