1GKEYTOOL(1) GNU GKEYTOOL(1)
2
6 gkeytool - Manage private keys and public certificates
7
9 keytool [COMMAND] ...
10
12 Cryptographic credentials, in a Java environment, are usually stored in
13 a Key Store. The Java SDK specifies a Key Store as a persistent con‐
14 tainer of two types of objects: Key Entries and Trusted Certificates.
15 The security tool keytool is a Java-based application for managing
16 those types of objects.
17 A Key Entry represents the private key part of a key-pair used in Pub‐
19 lic-Key Cryptography, and a signed X.509 certificate which authenti‐
20 cates the public key part for a known entity; i.e. the owner of the
21 key-pair. The X.509 certificate itself contains the public key part of
22 the key-pair.
23 A Trusted Certificate is a signed X.509 certificate issued by a trusted
25 entity. The Trust in this context is relative to the User of the key‐
26 tool. In other words, the existence of a Trusted Certificate in the Key
27 Store processed by a keytool command implies that the User trusts the
28 Issuer of that Trusted Certificate to also sign, and hence authenti‐
29 cates, other Subjects the tool may process.
30 Trusted Certificates are important because they allow the tool to
32 mechanically construct Chains of Trust starting from one of the Trusted
33 Certificates in a Key Store and ending with a certificate whose Issuer
34 is potentially unknown. A valid chain is an ordered list, starting with
35 a Trusted Certificate (also called the anchor), ending with the target
36 certificate, and satisfying the condition that the Subject of certifi‐
37 cate "#i" is the Issuer of certificate "#i + 1".
38 The keytool is invoked from the command line as follows:
40 keytool [COMMAND] ...
42 Multiple COMMANDs may be specified at once, each complete with its own
44 options. keytool will parse all the arguments, before processing, and
45 executing, each "COMMAND". If an exception occurs while executing one
46 COMMAND keytool will abort. Note however that because the implementa‐
47 tion of the tool uses code to parse command line options that also sup‐
48 ports GNU-style options, you have to separate each command group with a
49 double-hyphen; e.g
50 keytool -list -- -printcert -alias mykey
52
54 - Add/Update commands
55 -genkey [OPTION]...
56 Generate a new Key Entry, eventually creating a new key store.
57 -import [OPTION]...
59 Add, to a key store, Key Entries (private keys and certificate
60 chains authenticating the public keys) and Trusted Certificates
61 (3rd party certificates which can be used as Trust Anchors when
62 building chains-of-trust).
63 -selfcert [OPTION]...
65 Generate a new self-signed Trusted Certificate.
66 -cacert [OPTION]...
68 Import a CA Trusted Certificate.
69 -identitydb [OPTION]...
71 NOT IMPLEMENTED YET.Import a JDK 1.1 style Identity Database.
72 - Export commands
74 -certreq [OPTION]...
75 Issue a Certificate Signing Request (CSR) which can be then
76 sent to a Certification Authority (CA) to issue a certificate
77 signed (by the CA) and authenticating the Subject of the
78 request.
79 -export [OPTION]...
81 Export a certificate from a key store.
82 - Display commands
84 -list [OPTION]...
85 Print one or all certificates in a key store to "STDOUT".
86 -printcert [OPTION]...
88 Print a human-readable form of a certificate, in a designated
89 file, to "STDOUT".
90 - Management commands
92 -keyclone [OPTION]...
93 Clone a Key Entry in a key store.
94 -storepasswd [OPTION]...
96 Change the password protecting a key store.
97 -keypasswd [OPTION]...
99 Change the password protecting a Key Entry in a key store.
100 -delete [OPTION]...
102 Delete a Key Entry or a Trusted Certificate from a key store.
103 Common options
105 The following OPTIONs are used in more than one COMMAND. They are
107 described here to reduce redundancy.
108 -alias Alias
110 Every entry, be it a Key Entry or a Trusted Certificate, in a key
111 store is uniquely identified by a user-defined Alias string. Use
112 this option to specify the Alias to use when referring to an entry
113 in the key store. Unless specified otherwise, a default value of
114 "mykey" shall be used when this option is omitted from the command
115 line.
116 -keyalg ALGORITHM
118 Use this option to specify the canonical name of the key-pair gen‐
119 eration algorithm. The default value for this option is "DSS" (a
120 synonym for the Digital Signature Algorithm also known as DSA).
121 -keysize SIZE
123 Use this option to specify the number of bits of the shared modulus
124 (for both the public and private keys) to use when generating new
125 keys. A default value of 1024 will be used if this option is omit‐
126 ted from the command line.
127 -validity DAY_COUNT
129 Use this option to specify the number of days a newly generated
130 certificate will be valid for. The default value is 90 (days) if
131 this option is omitted from the command line.
132 -storetype STORE_TYPE
134 Use this option to specify the type of the key store to use. The
135 default value, if this option is omitted, is that of the property
136 "keystore.type" in the security properties file, which is obtained
137 by invoking the static method call "getDefaultType()" in
138 "java.security.KeyStore".
139 -storepass PASSWORD
141 Use this option to specify the password protecting the key store.
142 If this option is omitted from the command line, you will be
143 prompted to provide a password.
144 -keystore URL
146 Use this option to specify the location of the key store to use.
147 The default value is a file URL referencing the file named .key‐
148 store located in the path returned by the call to "java.lang.Sys‐
149 tem#getProperty(String)" using "user.home" as argument.
150 If a URL was specified, but was found to be malformed --e.g. miss‐
152 ing protocol element-- the tool will attempt to use the URL value
153 as a file-name (with absolute or relative path-name) of a key store
154 --as if the protocol was "file:".
155 -provider PROVIDER_CLASS_NAME
157 A fully qualified class name of a Security Provider to add to the
158 current list of Security Providers already installed in the JVM
159 in-use. If a provider class is specified with this option, and was
160 successfully added to the runtime --i.e. it was not already
161 installed-- then the tool will attempt to removed this Security
162 Provider before exiting.
163 -file FILE
165 Use this option to designate a file to use with a command. When
166 specified with this option, the value is expected to be the fully
167 qualified path of a file accessible by the File System. Depending
168 on the command, the file may be used as input or as output. When
169 this option is omitted from the command line, "STDIN" will be used
170 instead, as the source of input, and "STDOUT" will be used instead
171 as the output destination.
172 -v Unless specified otherwise, use this option to enable more verbose
174 output.
175 Add/Update commands
177 The -genkey command
179 Use this command to generate a new key-pair (both private and public
181 keys), and save these credentials in the key store as a Key Entry,
182 associated with the designated (if was specified with the -alias
183 option) or default (if the -alias option is omitted) Alias.
184 The private key material will be protected with a user-defined password
186 (see -keypass option). The public key on the other hand will be part of
187 a self-signed X.509 certificate, which will form a 1-element chain and
188 will be saved in the key store.
189 -alias ALIAS
191 See Common Options for more details.
192 -keyalg ALGORITHM
194 See Common Options for more details.
195 -keysize KEY_SIZE
197 See Common Options for more details.
198 -sigalg ALGORITHM
200 The canonical name of the digital signature algorithm to use for
201 signing certificates. If this option is omitted, a default value
202 will be chosen based on the type of the key-pair; i.e. the algo‐
203 rithm that ends up being used by the -keyalg option. If the key-
204 pair generation algorithm is "DSA", the value for the signature
205 algorithm will be "SHA1withDSA". If on the other hand the key-pair
206 generation algorithm is "RSA", then the tool will use "MD5withRSA"
207 as the signature algorithm.
208 -dname NAME
210 This a mandatory value for the command. If no value is specified
211 --i.e. the -dname option is omitted-- the tool will prompt you to
212 enter a Distinguished Name to use as both the Owner and Issuer of
213 the generated self-signed certificate.
214 See Common Options for more details.
216 -keypass PASSWORD
218 Use this option to specify the password which the tool will use to
219 protect the newly created Key Entry.
220 If this option is omitted, you will be prompted to provide a pass‐
222 word.
223 -validity DAY_COUNT
225 See Common Options for more details.
226 -storetype STORE_TYPE
228 See Common Options for more details.
229 -keystore URL
231 See Common Options for more details.
232 -storepass PASSWORD
234 See Common Options for more details.
235 -provider PROVIDER_CLASS_NAME
237 See Common Options for more details.
238 -v See Common Options for more details.
240 The -import command
242 Use this command to read an X.509 certificate, or a PKCS#7 Certificate
244 Reply from a designated input source and incorporate the certificates
245 into the key store.
246 If the Alias does not already exist in the key store, the tool treats
248 the certificate read from the input source as a new Trusted Certifi‐
249 cate. It then attempts to discover a chain-of-trust, starting from that
250 certificate and ending at another Trusted Certificate, already stored
251 in the key store. If the -trustcacerts option is present, an additional
252 key store, of type "JKS" named cacerts, and assumed to be present in
253 ${JAVA_HOME}/lib/security will also be consulted if found
254 --"${JAVA_HOME}" refers to the location of an installed Java Runtime
255 Environment (JRE). If no chain-of-trust can be established, and unless
256 the "-noprompt" option has been specified, the certificate is printed
257 to "STDOUT" and the user is prompted for a confirmation.
258 If Alias exists in the key store, the tool will treat the certifi‐
260 cate(s) read from the input source as a Certificate Reply, which can be
261 a chain of certificates, that eventually would replace the chain of
262 certificates associated with the Key Entry of that Alias. The substitu‐
263 tion of the certificates only occurs if a chain-of-trust can be estab‐
264 lished between the bottom certificate of the chain read from the input
265 file and the Trusted Certificates already present in the key store.
266 Again, if the -trustcacerts option is specified, additional Trusted
267 Certificates in the same cacerts key store will be considered. If no
268 chain-of-trust can be established, the operation will abort.
269 -alias ALIAS
271 See Common Options for more details.
272 -file FILE
274 See Common Options for more details.
275 -keypass PASSWORD
277 Use this option to specify the password which the tool will use to
278 protect the Key Entry associated with the designated Alias, when
279 replacing this Alias' chain of certificates with that found in the
280 certificate reply.
281 If this option is omitted, and the chain-of-trust for the certifi‐
283 cate reply has been established, the tool will first attempt to
284 unlock the Key Entry using the same password protecting the key
285 store. If this fails, you will then be prompted to provide a pass‐
286 word.
287 -noprompt
289 Use this option to prevent the tool from prompting the user.
290 -trustcacerts
292 Use this option to indicate to the tool that a key store, of type
293 "JKS", named cacerts, and usually located in lib/security in an
294 installed Java Runtime Environment should be considered when trying
295 to establish chain-of-trusts.
296 -storetype STORE_TYPE
298 See Common Options for more details.
299 -keystore URL
301 See Common Options for more details.
302 -storepass PASSWORD
304 See Common Options for more details.
305 -provider PROVIDER_CLASS_NAME
307 See Common Options for more details.
308 -v See Common Options for more details.
310 The -selfcert command
312 Use this command to generate a self-signed X.509 version 1 certificate.
314 The newly generated certificate will form a chain of one element which
315 will replace the previous chain associated with the designated Alias
316 (if -alias option was specified), or the default Alias (if -alias
317 option was omitted).
318 -alias ALIAS
320 See Common Options for more details.
321 -sigalg ALGORITHM
323 The canonical name of the digital signature algorithm to use for
324 signing the certificate. If this option is omitted, a default value
325 will be chosen based on the type of the private key associated with
326 the designated Alias. If the private key is a "DSA" one, the value
327 for the signature algorithm will be "SHA1withDSA". If on the other
328 hand the private key is an "RSA" one, then the tool will use
329 "MD5withRSA" as the signature algorithm.
330 -dname NAME
332 Use this option to specify the Distinguished Name of the newly gen‐
333 erated self-signed certificate. If this option is omitted, the
334 existing Distinguished Name of the base certificate in the chain
335 associated with the designated Alias will be used instead.
336 See Common Options for more details.
338 -validity DAY_COUNT
340 See Common Options for more details.
341 -keypass PASSWORD
343 Use this option to specify the password which the tool will use to
344 unlock the Key Entry associated with the designated Alias.
345 If this option is omitted, the tool will first attempt to unlock
347 the Key Entry using the same password protecting the key store. If
348 this fails, you will then be prompted to provide a password.
349 -storetype STORE_TYPE
351 See Common Options for more details.
352 -keystore URL
354 See Common Options for more details.
355 -storepass PASSWORD
357 See Common Options for more details.
358 -provider PROVIDER_CLASS_NAME
360 See Common Options for more details.
361 -v See Common Options for more details.
363 The -cacert command
365 Use this command to import, a CA certificate and add it to the key
367 store as a Trusted Certificate. The Alias for this new entry will be
368 constructed from the FILE's base-name after replacing hyphens and dots
369 with underscores.
370 This command is useful when used in a script that recursively visits a
372 directory of CA certificates to populate a "cacerts.gkr" Key Store of
373 trusted certificates which can then be used commands that specify the
374 -trustcacerts option.
375 -file FILE
377 See Common Options for more details.
378 -storetype STORE_TYPE
380 See Common Options for more details.
381 -keystore URL
383 See Common Options for more details.
384 -storepass PASSWORD
386 See Common Options for more details.
387 -provider PROVIDER_CLASS_NAME
389 See Common Options for more details.
390 -v See Common Options for more details.
392 The -identitydb command
394 NOT IMPLEMENTED YET.
396 Use this command to import a JDK 1.1 style Identity Database.
398 -file FILE
400 See Common Options for more details.
401 -storetype STORE_TYPE
403 See Common Options for more details.
404 -keystore URL
406 See Common Options for more details.
407 -storepass PASSWORD
409 See Common Options for more details.
410 -provider PROVIDER_CLASS_NAME
412 See Common Options for more details.
413 -v See Common Options for more details.
415 Export commands
417 The -certreq command
419 Use this command to generate a PKCS#10 Certificate Signing Request
421 (CSR) and write it to a designated output destination. The contents of
422 the destination should look something like the following:
423 -----BEGIN NEW CERTIFICATE REQUEST-----
425 MI...QAwXzEUMBIGA1UEAwwLcnNuQGdudS5vcmcxGzAZBgNVBAoMElUg
426 Q2...A0GA1UEBwwGU3lkbmV5MQwwCgYDVQQIDANOU1cxCzAJBgNVBACC
427 ...
428 FC...IVwNVOfQLRX+O5kAhQ/a4RTZme2L8PnpvgRwrf7Eg8D6w==
429 -----END NEW CERTIFICATE REQUEST-----
430 IMPORTANT: Some documentation (e.g. RSA examples) claims that the
432 "Attributes" field, in the CSR is "OPTIONAL" while RFC-2986 implies the
433 opposite. This implementation considers this field, by default, as
434 "OPTIONAL", unless the option -attributes is specified on the command
435 line.
436 -alias ALIAS
438 See Common Options for more details.
439 -sigalg ALGORITHM
441 The canonical name of the digital signature algorithm to use for
442 signing the certificate. If this option is omitted, a default value
443 will be chosen based on the type of the private key associated with
444 the designated Alias. If the private key is a "DSA" one, the value
445 for the signature algorithm will be "SHA1withDSA". If on the other
446 hand the private key is an "RSA" one, then the tool will use
447 "MD5withRSA" as the signature algorithm.
448 -file FILE
450 See Common Options for more details.
451 -keypass PASSWORD
453 Use this option to specify the password which the tool will use to
454 unlock the Key Entry associated with the designated Alias.
455 If this option is omitted, the tool will first attempt to unlock
457 the Key Entry using the same password protecting the key store. If
458 this fails, you will then be prompted to provide a password.
459 -storetype STORE_TYPE
461 See Common Options for more details.
462 -keystore URL
464 See Common Options for more details.
465 -storepass PASSWORD
467 See Common Options for more details.
468 -provider PROVIDER_CLASS_NAME
470 See Common Options for more details.
471 -v See Common Options for more details.
473 -attributes
475 Use this option to force the tool to encode a "NULL" DER value in
476 the CSR as the value of the "Attributes" field.
477 The -export command
479 Use this command to export a certificate stored in a key store to a
481 designated output destination, either in binary format (if the -v
482 option is specified), or in RFC-1421 compliant encoding (if the -rfc
483 option is specified instead).
484 -alias ALIAS
486 See Common Options for more details.
487 -file FILE
489 See Common Options for more details.
490 -storetype STORE_TYPE
492 See Common Options for more details.
493 -keystore URL
495 See Common Options for more details.
496 -storepass PASSWORD
498 See Common Options for more details.
499 -provider PROVIDER_CLASS_NAME
501 See Common Options for more details.
502 -rfc
504 Use RFC-1421 specifications when encoding the output.
505 -v Output the certificate in binary DER encoding. This is the default
507 output format of the command if neither -rfc nor "-v" options were
508 detected on the command line. If both this option and the -rfc
509 option are detected on the command line, the tool will opt for the
510 RFC-1421 style encoding.
511 Display commands
513 The -list command
515 Use this command to print one or all of a key store entries to "STD‐
517 OUT". Usually this command will only print a fingerprint of the cer‐
518 tificate, unless either the -rfc or the -v option is specified.
519 -alias ALIAS
521 If this option is omitted, the tool will print ALL the entries
522 found in the key store.
523 See Common Options for more details.
525 -storetype STORE_TYPE
527 See Common Options for more details.
528 -keystore URL
530 See Common Options for more details.
531 -storepass PASSWORD
533 See Common Options for more details.
534 -provider PROVIDER_CLASS_NAME
536 See Common Options for more details.
537 -rfc
539 Use RFC-1421 specifications when encoding the output.
540 -v Output the certificate in human-readable format. If both this
542 option and the -rfc option are detected on the command line, the
543 tool will opt for the human-readable form and will not abort the
544 command.
545 The -printcert command
547 Use this command to read a certificate from a designated input source
549 and print it to "STDOUT" in a human-readable form.
550 -file FILE
552 See Common Options for more details.
553 -v See Common Options for more details.
555 Management commands
557 The -keyclone command
559 Use this command to clone an existing Key Entry and store it under a
561 new (different) Alias protecting, its private key material with possi‐
562 bly a new password.
563 -alias ALIAS
565 See Common Options for more details.
566 -dest ALIAS
568 Use this option to specify the new Alias which will be used to
569 identify the cloned copy of the Key Entry.
570 -keypass PASSWORD
572 Use this option to specify the password which the tool will use to
573 unlock the Key Entry associated with the designated Alias.
574 If this option is omitted, the tool will first attempt to unlock
576 the Key Entry using the same password protecting the key store. If
577 this fails, you will then be prompted to provide a password.
578 -new PASSWORD
580 Use this option to specify the password protecting the private key
581 material of the newly cloned copy of the Key Entry.
582 -storetype STORE_TYPE
584 See Common Options for more details.
585 -keystore URL
587 See Common Options for more details.
588 -storepass PASSWORD
590 See Common Options for more details.
591 -provider PROVIDER_CLASS_NAME
593 See Common Options for more details.
594 -v See Common Options for more details.
596 The -storepasswd command
598 Use this command to change the password protecting a key store.
600 -new PASSWORD
602 The new, and different, password which will be used to protect the
603 designated key store.
604 -storetype STORE_TYPE
606 See Common Options for more details.
607 -keystore URL
609 See Common Options for more details.
610 -storepass PASSWORD
612 See Common Options for more details.
613 -provider PROVIDER_CLASS_NAME
615 See Common Options for more details.
616 -v See Common Options for more details.
618 The -keypasswd command
620 Use this command to change the password protecting the private key
622 material of a designated Key Entry.
623 -alias ALIAS
625 See Common Options for more details.
626 Use this option to specify the password which the tool will use to
628 unlock the Key Entry associated with the designated Alias.
629 If this option is omitted, the tool will first attempt to unlock
631 the Key Entry using the same password protecting the key store. If
632 this fails, you will then be prompted to provide a password.
633 -new PASSWORD
635 The new, and different, password which will be used to protect the
636 private key material of the designated Key Entry.
637 -storetype STORE_TYPE
639 See Common Options for more details.
640 -keystore URL
642 See Common Options for more details.
643 -storepass PASSWORD
645 See Common Options for more details.
646 -provider PROVIDER_CLASS_NAME
648 See Common Options for more details.
649 -v See Common Options for more details.
651 The -delete command
653 Use this command to delete a designated key store entry.
655 -alias ALIAS
657 See Common Options for more details.
658 -storetype STORE_TYPE
660 See Common Options for more details.
661 -keystore URL
663 See Common Options for more details.
664 -storepass PASSWORD
666 See Common Options for more details.
667 -provider PROVIDER_CLASS_NAME
669 See Common Options for more details.
670 -v See Common Options for more details.
672
674gcc-4.1.2 2007-09-25 GKEYTOOL(1)