1GKEYTOOL(1)                           GNU                          GKEYTOOL(1)
2
3
4

NAME

6       gkeytool - Manage private keys and public certificates
7

SYNOPSIS

9       keytool [COMMAND] ...
10

DESCRIPTION

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
14       container of two types of objects: Key Entries and Trusted
15       Certificates. The security tool keytool is a Java-based application for
16       managing those types of objects.
17
18       A Key Entry represents the private key part of a key-pair used in
19       Public-Key Cryptography, and a signed X.509 certificate which
20       authenticates the public key part for a known entity; i.e. the owner of
21       the key-pair. The X.509 certificate itself contains the public key part
22       of the key-pair.
23
24       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
26       keytool. In other words, the existence of a Trusted Certificate in the
27       Key Store processed by a keytool command implies that the User trusts
28       the Issuer of that Trusted Certificate to also sign, and hence
29       authenticates, other Subjects the tool may process.
30
31       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
37       certificate "#i" is the Issuer of certificate "#i + 1".
38
39       The keytool is invoked from the command line as follows:
40
41               keytool [COMMAND] ...
42
43       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
47       implementation of the tool uses code to parse command line options that
48       also supports GNU-style options, you have to separate each command
49       group with a double-hyphen; e.g
50
51               keytool -list -- -printcert -alias mykey
52

OPTIONS

54       - Add/Update commands
55           -genkey [OPTION]...
56               Generate a new Key Entry, eventually creating a new key store.
57
58           -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
64           -selfcert [OPTION]...
65               Generate a new self-signed Trusted Certificate.
66
67           -cacert [OPTION]...
68               Import a CA Trusted Certificate.
69
70           -identitydb [OPTION]...
71               NOT IMPLEMENTED YET.Import a JDK 1.1 style Identity Database.
72
73       - 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
80           -export [OPTION]...
81               Export a certificate from a key store.
82
83       - Display commands
84           -list [OPTION]...
85               Print one or all certificates in a key store to "STDOUT".
86
87           -printcert [OPTION]...
88               Print a human-readable form of a certificate, in a designated
89               file, to "STDOUT".
90
91       - Management commands
92           -keyclone [OPTION]...
93               Clone a Key Entry in a key store.
94
95           -storepasswd [OPTION]...
96               Change the password protecting a key store.
97
98           -keypasswd [OPTION]...
99               Change the password protecting a Key Entry in a key store.
100
101           -delete [OPTION]...
102               Delete a Key Entry or a Trusted Certificate from a key store.
103
104       Common options
105
106       The following OPTIONs are used in more than one COMMAND. They are
107       described here to reduce redundancy.
108
109       -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
117       -keyalg ALGORITHM
118           Use this option to specify the canonical name of the key-pair
119           generation algorithm. The default value for this option is "DSS" (a
120           synonym for the Digital Signature Algorithm also known as DSA).
121
122       -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
126           omitted from the command line.
127
128       -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
133       -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
140       -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
145       -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
148           .keystore located in the path returned by the call to
149           "java.lang.System#getProperty(String)" using "user.home" as
150           argument.
151
152           If a URL was specified, but was found to be malformed --e.g.
153           missing protocol element-- the tool will attempt to use the URL
154           value as a file-name (with absolute or relative path-name) of a key
155           store --as if the protocol was "file:".
156
157       -provider PROVIDER_CLASS_NAME
158           A fully qualified class name of a Security Provider to add to the
159           current list of Security Providers already installed in the JVM in-
160           use. If a provider class is specified with this option, and was
161           successfully added to the runtime --i.e. it was not already
162           installed-- then the tool will attempt to removed this Security
163           Provider before exiting.
164
165       -file FILE
166           Use this option to designate a file to use with a command. When
167           specified with this option, the value is expected to be the fully
168           qualified path of a file accessible by the File System. Depending
169           on the command, the file may be used as input or as output. When
170           this option is omitted from the command line, "STDIN" will be used
171           instead, as the source of input, and "STDOUT" will be used instead
172           as the output destination.
173
174       -v  Unless specified otherwise, use this option to enable more verbose
175           output.
176
177       Add/Update commands
178
179       The -genkey command
180
181       Use this command to generate a new key-pair (both private and public
182       keys), and save these credentials in the key store as a Key Entry,
183       associated with the designated (if was specified with the -alias
184       option) or default (if the -alias option is omitted) Alias.
185
186       The private key material will be protected with a user-defined password
187       (see -keypass option). The public key on the other hand will be part of
188       a self-signed X.509 certificate, which will form a 1-element chain and
189       will be saved in the key store.
190
191       -alias ALIAS
192           See Common Options for more details.
193
194       -keyalg ALGORITHM
195           See Common Options for more details.
196
197       -keysize KEY_SIZE
198           See Common Options for more details.
199
200       -sigalg ALGORITHM
201           The canonical name of the digital signature algorithm to use for
202           signing certificates. If this option is omitted, a default value
203           will be chosen based on the type of the key-pair; i.e., the
204           algorithm that ends up being used by the -keyalg option. If the
205           key-pair generation algorithm is "DSA", the value for the signature
206           algorithm will be "SHA1withDSA". If on the other hand the key-pair
207           generation algorithm is "RSA", then the tool will use "MD5withRSA"
208           as the signature algorithm.
209
210       -dname NAME
211           This a mandatory value for the command. If no value is specified
212           --i.e. the -dname option is omitted-- the tool will prompt you to
213           enter a Distinguished Name to use as both the Owner and Issuer of
214           the generated self-signed certificate.
215
216           See Common Options for more details.
217
218       -keypass PASSWORD
219           Use this option to specify the password which the tool will use to
220           protect the newly created Key Entry.
221
222           If this option is omitted, you will be prompted to provide a
223           password.
224
225       -validity DAY_COUNT
226           See Common Options for more details.
227
228       -storetype STORE_TYPE
229           See Common Options for more details.
230
231       -keystore URL
232           See Common Options for more details.
233
234       -storepass PASSWORD
235           See Common Options for more details.
236
237       -provider PROVIDER_CLASS_NAME
238           See Common Options for more details.
239
240       -v  See Common Options for more details.
241
242       The -import command
243
244       Use this command to read an X.509 certificate, or a PKCS#7 Certificate
245       Reply from a designated input source and incorporate the certificates
246       into the key store.
247
248       If the Alias does not already exist in the key store, the tool treats
249       the certificate read from the input source as a new Trusted
250       Certificate. It then attempts to discover a chain-of-trust, starting
251       from that certificate and ending at another Trusted Certificate,
252       already stored in the key store. If the -trustcacerts option is
253       present, an additional key store, of type "JKS" named cacerts, and
254       assumed to be present in ${JAVA_HOME}/lib/security will also be
255       consulted if found --"${JAVA_HOME}" refers to the location of an
256       installed Java Runtime Environment (JRE). If no chain-of-trust can be
257       established, and unless the "-noprompt" option has been specified, the
258       certificate is printed to "STDOUT" and the user is prompted for a
259       confirmation.
260
261       If Alias exists in the key store, the tool will treat the
262       certificate(s) read from the input source as a Certificate Reply, which
263       can be a chain of certificates, that eventually would replace the chain
264       of certificates associated with the Key Entry of that Alias. The
265       substitution of the certificates only occurs if a chain-of-trust can be
266       established between the bottom certificate of the chain read from the
267       input file and the Trusted Certificates already present in the key
268       store. Again, if the -trustcacerts option is specified, additional
269       Trusted Certificates in the same cacerts key store will be considered.
270       If no chain-of-trust can be established, the operation will abort.
271
272       -alias ALIAS
273           See Common Options for more details.
274
275       -file FILE
276           See Common Options for more details.
277
278       -keypass PASSWORD
279           Use this option to specify the password which the tool will use to
280           protect the Key Entry associated with the designated Alias, when
281           replacing this Alias' chain of certificates with that found in the
282           certificate reply.
283
284           If this option is omitted, and the chain-of-trust for the
285           certificate reply has been established, the tool will first attempt
286           to unlock the Key Entry using the same password protecting the key
287           store. If this fails, you will then be prompted to provide a
288           password.
289
290       -noprompt
291           Use this option to prevent the tool from prompting the user.
292
293       -trustcacerts
294           Use this option to indicate to the tool that a key store, of type
295           "JKS", named cacerts, and usually located in lib/security in an
296           installed Java Runtime Environment should be considered when trying
297           to establish chain-of-trusts.
298
299       -storetype STORE_TYPE
300           See Common Options for more details.
301
302       -keystore URL
303           See Common Options for more details.
304
305       -storepass PASSWORD
306           See Common Options for more details.
307
308       -provider PROVIDER_CLASS_NAME
309           See Common Options for more details.
310
311       -v  See Common Options for more details.
312
313       The -selfcert command
314
315       Use this command to generate a self-signed X.509 version 1 certificate.
316       The newly generated certificate will form a chain of one element which
317       will replace the previous chain associated with the designated Alias
318       (if -alias option was specified), or the default Alias (if -alias
319       option was omitted).
320
321       -alias ALIAS
322           See Common Options for more details.
323
324       -sigalg ALGORITHM
325           The canonical name of the digital signature algorithm to use for
326           signing the certificate. If this option is omitted, a default value
327           will be chosen based on the type of the private key associated with
328           the designated Alias. If the private key is a "DSA" one, the value
329           for the signature algorithm will be "SHA1withDSA". If on the other
330           hand the private key is an "RSA" one, then the tool will use
331           "MD5withRSA" as the signature algorithm.
332
333       -dname NAME
334           Use this option to specify the Distinguished Name of the newly
335           generated self-signed certificate. If this option is omitted, the
336           existing Distinguished Name of the base certificate in the chain
337           associated with the designated Alias will be used instead.
338
339           See Common Options for more details.
340
341       -validity DAY_COUNT
342           See Common Options for more details.
343
344       -keypass PASSWORD
345           Use this option to specify the password which the tool will use to
346           unlock the Key Entry associated with the designated Alias.
347
348           If this option is omitted, the tool will first attempt to unlock
349           the Key Entry using the same password protecting the key store. If
350           this fails, you will then be prompted to provide a password.
351
352       -storetype STORE_TYPE
353           See Common Options for more details.
354
355       -keystore URL
356           See Common Options for more details.
357
358       -storepass PASSWORD
359           See Common Options for more details.
360
361       -provider PROVIDER_CLASS_NAME
362           See Common Options for more details.
363
364       -v  See Common Options for more details.
365
366       The -cacert command
367
368       Use this command to import, a CA certificate and add it to the key
369       store as a Trusted Certificate. The Alias for this new entry will be
370       constructed from the FILE's base-name after replacing hyphens and dots
371       with underscores.
372
373       This command is useful when used in a script that recursively visits a
374       directory of CA certificates to populate a "cacerts.gkr" Key Store of
375       trusted certificates which can then be used commands that specify the
376       -trustcacerts option.
377
378       -file FILE
379           See Common Options for more details.
380
381       -storetype STORE_TYPE
382           See Common Options for more details.
383
384       -keystore URL
385           See Common Options for more details.
386
387       -storepass PASSWORD
388           See Common Options for more details.
389
390       -provider PROVIDER_CLASS_NAME
391           See Common Options for more details.
392
393       -v  See Common Options for more details.
394
395       The -identitydb command
396
397       NOT IMPLEMENTED YET.
398
399       Use this command to import a JDK 1.1 style Identity Database.
400
401       -file FILE
402           See Common Options for more details.
403
404       -storetype STORE_TYPE
405           See Common Options for more details.
406
407       -keystore URL
408           See Common Options for more details.
409
410       -storepass PASSWORD
411           See Common Options for more details.
412
413       -provider PROVIDER_CLASS_NAME
414           See Common Options for more details.
415
416       -v  See Common Options for more details.
417
418       Export commands
419
420       The -certreq command
421
422       Use this command to generate a PKCS#10 Certificate Signing Request
423       (CSR) and write it to a designated output destination. The contents of
424       the destination should look something like the following:
425
426               -----BEGIN NEW CERTIFICATE REQUEST-----
427               MI...QAwXzEUMBIGA1UEAwwLcnNuQGdudS5vcmcxGzAZBgNVBAoMElUg
428               Q2...A0GA1UEBwwGU3lkbmV5MQwwCgYDVQQIDANOU1cxCzAJBgNVBACC
429               ...
430               FC...IVwNVOfQLRX+O5kAhQ/a4RTZme2L8PnpvgRwrf7Eg8D6w==
431               -----END NEW CERTIFICATE REQUEST-----
432
433       IMPORTANT: Some documentation (e.g. RSA examples) claims that the
434       "Attributes" field, in the CSR is "OPTIONAL" while RFC-2986 implies the
435       opposite. This implementation considers this field, by default, as
436       "OPTIONAL", unless the option -attributes is specified on the command
437       line.
438
439       -alias ALIAS
440           See Common Options for more details.
441
442       -sigalg ALGORITHM
443           The canonical name of the digital signature algorithm to use for
444           signing the certificate. If this option is omitted, a default value
445           will be chosen based on the type of the private key associated with
446           the designated Alias. If the private key is a "DSA" one, the value
447           for the signature algorithm will be "SHA1withDSA". If on the other
448           hand the private key is an "RSA" one, then the tool will use
449           "MD5withRSA" as the signature algorithm.
450
451       -file FILE
452           See Common Options for more details.
453
454       -keypass PASSWORD
455           Use this option to specify the password which the tool will use to
456           unlock the Key Entry associated with the designated Alias.
457
458           If this option is omitted, the tool will first attempt to unlock
459           the Key Entry using the same password protecting the key store. If
460           this fails, you will then be prompted to provide a password.
461
462       -storetype STORE_TYPE
463           See Common Options for more details.
464
465       -keystore URL
466           See Common Options for more details.
467
468       -storepass PASSWORD
469           See Common Options for more details.
470
471       -provider PROVIDER_CLASS_NAME
472           See Common Options for more details.
473
474       -v  See Common Options for more details.
475
476       -attributes
477           Use this option to force the tool to encode a "NULL" DER value in
478           the CSR as the value of the "Attributes" field.
479
480       The -export command
481
482       Use this command to export a certificate stored in a key store to a
483       designated output destination, either in binary format (if the -v
484       option is specified), or in RFC-1421 compliant encoding (if the -rfc
485       option is specified instead).
486
487       -alias ALIAS
488           See Common Options for more details.
489
490       -file FILE
491           See Common Options for more details.
492
493       -storetype STORE_TYPE
494           See Common Options for more details.
495
496       -keystore URL
497           See Common Options for more details.
498
499       -storepass PASSWORD
500           See Common Options for more details.
501
502       -provider PROVIDER_CLASS_NAME
503           See Common Options for more details.
504
505       -rfc
506           Use RFC-1421 specifications when encoding the output.
507
508       -v  Output the certificate in binary DER encoding. This is the default
509           output format of the command if neither -rfc nor "-v" options were
510           detected on the command line. If both this option and the -rfc
511           option are detected on the command line, the tool will opt for the
512           RFC-1421 style encoding.
513
514       Display commands
515
516       The -list command
517
518       Use this command to print one or all of a key store entries to
519       "STDOUT". Usually this command will only print a fingerprint of the
520       certificate, unless either the -rfc or the -v option is specified.
521
522       -alias ALIAS
523           If this option is omitted, the tool will print ALL the entries
524           found in the key store.
525
526           See Common Options for more details.
527
528       -storetype STORE_TYPE
529           See Common Options for more details.
530
531       -keystore URL
532           See Common Options for more details.
533
534       -storepass PASSWORD
535           See Common Options for more details.
536
537       -provider PROVIDER_CLASS_NAME
538           See Common Options for more details.
539
540       -rfc
541           Use RFC-1421 specifications when encoding the output.
542
543       -v  Output the certificate in human-readable format. If both this
544           option and the -rfc option are detected on the command line, the
545           tool will opt for the human-readable form and will not abort the
546           command.
547
548       The -printcert command
549
550       Use this command to read a certificate from a designated input source
551       and print it to "STDOUT" in a human-readable form.
552
553       -file FILE
554           See Common Options for more details.
555
556       -v  See Common Options for more details.
557
558       Management commands
559
560       The -keyclone command
561
562       Use this command to clone an existing Key Entry and store it under a
563       new (different) Alias protecting, its private key material with
564       possibly a new password.
565
566       -alias ALIAS
567           See Common Options for more details.
568
569       -dest ALIAS
570           Use this option to specify the new Alias which will be used to
571           identify the cloned copy of the Key Entry.
572
573       -keypass PASSWORD
574           Use this option to specify the password which the tool will use to
575           unlock the Key Entry associated with the designated Alias.
576
577           If this option is omitted, the tool will first attempt to unlock
578           the Key Entry using the same password protecting the key store. If
579           this fails, you will then be prompted to provide a password.
580
581       -new PASSWORD
582           Use this option to specify the password protecting the private key
583           material of the newly cloned copy of the Key Entry.
584
585       -storetype STORE_TYPE
586           See Common Options for more details.
587
588       -keystore URL
589           See Common Options for more details.
590
591       -storepass PASSWORD
592           See Common Options for more details.
593
594       -provider PROVIDER_CLASS_NAME
595           See Common Options for more details.
596
597       -v  See Common Options for more details.
598
599       The -storepasswd command
600
601       Use this command to change the password protecting a key store.
602
603       -new PASSWORD
604           The new, and different, password which will be used to protect the
605           designated key store.
606
607       -storetype STORE_TYPE
608           See Common Options for more details.
609
610       -keystore URL
611           See Common Options for more details.
612
613       -storepass PASSWORD
614           See Common Options for more details.
615
616       -provider PROVIDER_CLASS_NAME
617           See Common Options for more details.
618
619       -v  See Common Options for more details.
620
621       The -keypasswd command
622
623       Use this command to change the password protecting the private key
624       material of a designated Key Entry.
625
626       -alias ALIAS
627           See Common Options for more details.
628
629           Use this option to specify the password which the tool will use to
630           unlock the Key Entry associated with the designated Alias.
631
632           If this option is omitted, the tool will first attempt to unlock
633           the Key Entry using the same password protecting the key store. If
634           this fails, you will then be prompted to provide a password.
635
636       -new PASSWORD
637           The new, and different, password which will be used to protect the
638           private key material of the designated Key Entry.
639
640       -storetype STORE_TYPE
641           See Common Options for more details.
642
643       -keystore URL
644           See Common Options for more details.
645
646       -storepass PASSWORD
647           See Common Options for more details.
648
649       -provider PROVIDER_CLASS_NAME
650           See Common Options for more details.
651
652       -v  See Common Options for more details.
653
654       The -delete command
655
656       Use this command to delete a designated key store entry.
657
658       -alias ALIAS
659           See Common Options for more details.
660
661       -storetype STORE_TYPE
662           See Common Options for more details.
663
664       -keystore URL
665           See Common Options for more details.
666
667       -storepass PASSWORD
668           See Common Options for more details.
669
670       -provider PROVIDER_CLASS_NAME
671           See Common Options for more details.
672
673       -v  See Common Options for more details.
674

BUGS

SEE ALSO

AUTHOR

6780.98                              2010-04-27                       GKEYTOOL(1)
Impressum