1KEYTOOL(1) JDK Commands KEYTOOL(1)
2
6 keytool - a key and certificate management utility
7
9 keytool [commands]
10 commands
12 Commands for keytool include the following:
13 · -certreq: Generates a certificate request
15 · -changealias: Changes an entry's alias
17 · -delete: Deletes an entry
19 · -exportcert: Exports certificate
21 · -genkeypair: Generates a key pair
23 · -genseckey: Generates a secret key
25 · -gencert: Generates a certificate from a certificate request
27 · -importcert: Imports a certificate or a certificate chain
29 · -importpass: Imports a password
31 · -importkeystore: Imports one or all entries from another key‐
33 store
34 · -keypasswd: Changes the key password of an entry
36 · -list: Lists entries in a keystore
38 · -printcert: Prints the content of a certificate
40 · -printcertreq: Prints the content of a certificate request
42 · -printcrl: Prints the content of a Certificate Revocation List
44 (CRL) file
45 · -storepasswd: Changes the store password of a keystore
47 · -showinfo: Displays security-related information
49 See Commands and Options for a description of these commands
51 with their options.
52
54 The keytool command is a key and certificate management utility. It
55 enables users to administer their own public/private key pairs and as‐
56 sociated certificates for use in self-authentication (where a user au‐
57 thenticates themselves to other users and services) or data integrity
58 and authentication services, by using digital signatures. The keytool
59 command also enables users to cache the public keys (in the form of
60 certificates) of their communicating peers.
61 A certificate is a digitally signed statement from one entity (person,
63 company, and so on), which says that the public key (and some other in‐
64 formation) of some other entity has a particular value. When data is
65 digitally signed, the signature can be verified to check the data in‐
66 tegrity and authenticity. Integrity means that the data hasn't been
67 modified or tampered with, and authenticity means that the data comes
68 from the individual who claims to have created and signed it.
69 The keytool command also enables users to administer secret keys and
71 passphrases used in symmetric encryption and decryption (Data Encryp‐
72 tion Standard). It can also display other security-related informa‐
73 tion.
74 The keytool command stores the keys and certificates in a keystore.
76
78 The following notes apply to the descriptions in Commands and Options:
79 · All command and option names are preceded by a hyphen sign (-).
81 · Only one command can be provided.
83 · Options for each command can be provided in any order.
85 · There are two kinds of options, one is single-valued which should be
87 only provided once. If a single-valued option is provided multiple
88 times, the value of the last one is used. The other type is mul‐
89 ti-valued, which can be provided multiple times and all values are
90 used. The only multi-valued option currently supported is the -ext
91 option used to generate X.509v3 certificate extensions.
92 · All items not italicized or in braces ({ }) or brackets ([ ]) are re‐
94 quired to appear as is.
95 · Braces surrounding an option signify that a default value is used
97 when the option isn't specified on the command line. Braces are also
98 used around the -v, -rfc, and -J options, which have meaning only
99 when they appear on the command line. They don't have any default
100 values.
101 · Brackets surrounding an option signify that the user is prompted for
103 the values when the option isn't specified on the command line. For
104 the -keypass option, if you don't specify the option on the command
105 line, then the keytool command first attempts to use the keystore
106 password to recover the private/secret key. If this attempt fails,
107 then the keytool command prompts you for the private/secret key pass‐
108 word.
109 · Items in italics (option values) represent the actual values that
111 must be supplied. For example, here is the format of the -printcert
112 command:
113 keytool -printcert {-file cert_file} {-v}
115 When you specify a -printcert command, replace cert_file with the ac‐
117 tual file name, as follows: keytool -printcert -file VScert.cer
118 · Option values must be enclosed in quotation marks when they contain a
120 blank (space).
121
123 The keytool commands and their options can be grouped by the tasks that
124 they perform.
125 Commands for Creating or Adding Data to the Keystore:
127 · -gencert
129 · -genkeypair
131 · -genseckey
133 · -importcert
135 · -importpass
137 Commands for Importing Contents from Another Keystore:
139 · -importkeystore
141 Commands for Generating a Certificate Request:
143 · -certreq
145 Commands for Exporting Data:
147 · -exportcert
149 Commands for Displaying Data:
151 · -list
153 · -printcert
155 · -printcertreq
157 · -printcrl
159 Commands for Managing the Keystore:
161 · -storepasswd
163 · -keypasswd
165 · -delete
167 · -changealias
169 Commands for Displaying Security-related Information:
171 · -showinfo
173
175 -gencert
176 The following are the available options for the -gencert com‐
177 mand:
178 · {-rfc}: Output in RFC (Request For Comment) style
180 · {-infile infile}: Input file name
182 · {-outfile outfile}: Output file name
184 · {-alias alias}: Alias name of the entry to process
186 · {-sigalg sigalg}: Signature algorithm name
188 · {-dname dname}: Distinguished name
190 · {-startdate startdate}: Certificate validity start date and
192 time
193 · {-ext ext}*: X.509 extension
195 · {-validity days}: Validity number of days
197 · [-keypass arg]: Key password
199 · {-keystore keystore}: Keystore name
201 · [-storepass arg]: Keystore password
203 · {-storetype type}: Keystore type
205 · {-providername name}: Provider name
207 · {-addprovider name [-providerarg arg]}: Adds a security
209 provider by name (such as SunPKCS11) with an optional config‐
210 ure argument. The value of the security provider is the name
211 of a security provider that is defined in a module.
212 For example,
214 keytool -addprovider SunPKCS11 -provider‐
216 arg some.cfg ...
217 Note:
219 For compatibility reasons, the SunPKCS11 and OracleUcrypto
221 providers can still be loaded with -providerclass sun.securi‐
222 ty.pkcs11.SunPKCS11 and -providerclass com.oracle.securi‐
223 ty.crypto.UcryptoProvider even if they are now defined in mod‐
224 ules. These are the only modules included in JDK that need a
225 configuration, and therefore the most widely used with the
226 -providerclass option. For legacy security providers located
227 on classpath and loaded by reflection, -providerclass should
228 still be used.
229 · {-providerclass class [-providerarg arg]}: Add security
231 provider by fully qualified class name with an optional con‐
232 figure argument.
233 For example, if MyProvider is a legacy provider loaded via re‐
235 flection,
236 keytool -providerclass com.example.MyProvider ...
238 · {-providerpath list}: Provider classpath
240 · {-v}: Verbose output
242 · {-protected}: Password provided through a protected mechanism
244 Use the -gencert command to generate a certificate as a response
246 to a certificate request file (which can be created by the key‐
247 tool -certreq command). The command reads the request either
248 from infile or, if omitted, from the standard input, signs it by
249 using the alias's private key, and outputs the X.509 certificate
250 into either outfile or, if omitted, to the standard output.
251 When -rfc is specified, the output format is Base64-encoded PEM;
252 otherwise, a binary DER is created.
253 The -sigalg value specifies the algorithm that should be used to
255 sign the certificate. The startdate argument is the start time
256 and date that the certificate is valid. The days argument tells
257 the number of days for which the certificate should be consid‐
258 ered valid.
259 When dname is provided, it is used as the subject of the gener‐
261 ated certificate. Otherwise, the one from the certificate re‐
262 quest is used.
263 The -ext value shows what X.509 extensions will be embedded in
265 the certificate. Read Common Command Options for the grammar of
266 -ext.
267 The -gencert option enables you to create certificate chains.
269 The following example creates a certificate, e1, that contains
270 three certificates in its certificate chain.
271 The following commands creates four key pairs named ca, ca1,
273 ca2, and e1:
274 keytool -alias ca -dname CN=CA -genkeypair
276 keytool -alias ca1 -dname CN=CA -genkeypair
277 keytool -alias ca2 -dname CN=CA -genkeypair
278 keytool -alias e1 -dname CN=E1 -genkeypair
279 The following two commands create a chain of signed certifi‐
281 cates; ca signs ca1 and ca1 signs ca2, all of which are self-is‐
282 sued:
283 keytool -alias ca1 -certreq |
285 keytool -alias ca -gencert -ext san=dns:ca1 |
286 keytool -alias ca1 -importcert
287 keytool -alias ca2 -certreq |
289 keytool -alias ca1 -gencert -ext san=dns:ca2 |
290 keytool -alias ca2 -importcert
291 The following command creates the certificate e1 and stores it
293 in the e1.cert file, which is signed by ca2. As a result, e1
294 should contain ca, ca1, and ca2 in its certificate chain:
295 keytool -alias e1 -certreq | key‐
297 tool -alias ca2 -gencert > e1.cert
298 -genkeypair
300 The following are the available options for the -genkeypair com‐
301 mand:
302 · {-alias alias}: Alias name of the entry to process
304 · {-keyalg alg}: Key algorithm name
306 · {-keysize size}: Key bit size
308 · {-groupname name}: Group name. For example, an Elliptic Curve
310 name.
311 · {-sigalg alg}: Signature algorithm name
313 · [-dname name]: Distinguished name
315 · {-startdate date}: Certificate validity start date and time
317 · [-ext value}*: X.509 extension
319 · {-validity days}: Validity number of days
321 · [-keypass arg]: Key password
323 · {-keystore keystore}: Keystore name
325 · [-storepass arg]: Keystore password
327 · {-storetype type}: Keystore type
329 · {-providername name}: Provider name
331 · {-addprovider name [-providerarg arg]}: Add security provider
333 by name (such as SunPKCS11) with an optional configure argu‐
334 ment.
335 · {-providerclass class [-providerarg arg] }: Add security
337 provider by fully qualified class name with an optional con‐
338 figure argument.
339 · {-providerpath list}: Provider classpath
341 · {-v}: Verbose output
343 · {-protected}: Password provided through a protected mechanism
345 Use the -genkeypair command to generate a key pair (a public key
347 and associated private key). Wraps the public key in an X.509
348 v3 self-signed certificate, which is stored as a single-element
349 certificate chain. This certificate chain and the private key
350 are stored in a new keystore entry that is identified by its
351 alias.
352 The -keyalg value specifies the algorithm to be used to generate
354 the key pair, and the -keysize value specifies the size of each
355 key to be generated. The -sigalg value specifies the algorithm
356 that should be used to sign the self-signed certificate. This
357 algorithm must be compatible with the -keyalg value.
358 The -groupname value specifies the named group (for example, the
360 standard or predefined name of an Elliptic Curve) of the key to
361 be generated. Only one of -groupname and -keysize can be speci‐
362 fied.
363 The -dname value specifies the X.500 Distinguished Name to be
365 associated with the value of -alias, and is used as the issuer
366 and subject fields in the self-signed certificate. If a distin‐
367 guished name is not provided at the command line, then the user
368 is prompted for one.
369 The value of -keypass is a password used to protect the private
371 key of the generated key pair. If a password is not provided,
372 then the user is prompted for it. If you press the Return key
373 at the prompt, then the key password is set to the same password
374 as the keystore password. The -keypass value must have at least
375 six characters.
376 The value of -startdate specifies the issue time of the certifi‐
378 cate, also known as the "Not Before" value of the X.509 certifi‐
379 cate's Validity field.
380 The option value can be set in one of these two forms:
382 ([+-]nnn[ymdHMS])+
384 [yyyy/mm/dd] [HH:MM:SS]
386 With the first form, the issue time is shifted by the specified
388 value from the current time. The value is a concatenation of a
389 sequence of subvalues. Inside each subvalue, the plus sign (+)
390 means shift forward, and the minus sign (-) means shift back‐
391 ward. The time to be shifted is nnn units of years, months,
392 days, hours, minutes, or seconds (denoted by a single character
393 of y, m, d, H, M, or S respectively). The exact value of the
394 issue time is calculated by using the java.util.GregorianCalen‐
395 dar.add(int field, int amount) method on each subvalue, from
396 left to right. For example, the issue time can be specified by:
397 Calendar c = new GregorianCalendar();
399 c.add(Calendar.YEAR, -1);
400 c.add(Calendar.MONTH, 1);
401 c.add(Calendar.DATE, -1);
402 return c.getTime()
403 With the second form, the user sets the exact issue time in two
405 parts, year/month/day and hour:minute:second (using the local
406 time zone). The user can provide only one part, which means the
407 other part is the same as the current date (or time). The user
408 must provide the exact number of digits shown in the format def‐
409 inition (padding with 0 when shorter). When both date and time
410 are provided, there is one (and only one) space character be‐
411 tween the two parts. The hour should always be provided in
412 24-hour format.
413 When the option isn't provided, the start date is the current
415 time. The option can only be provided one time.
416 The value of date specifies the number of days (starting at the
418 date specified by -startdate, or the current date when -start‐
419 date isn't specified) for which the certificate should be con‐
420 sidered valid.
421 -genseckey
423 The following are the available options for the -genseckey com‐
424 mand:
425 · {-alias alias}: Alias name of the entry to process
427 · [-keypass arg]: Key password
429 · {-keyalg alg}: Key algorithm name
431 · {-keysize size}: Key bit size
433 · {-keystore keystore}: Keystore name
435 · [-storepass arg]: Keystore password
437 · {-storetype type}: Keystore type
439 · {-providername name}: Provider name
441 · {-addprovider name [-providerarg arg]}: Add security provider
443 by name (such as SunPKCS11) with an optional configure argu‐
444 ment.
445 · {-providerclass class [-providerarg arg]}: Add security
447 provider by fully qualified class name with an optional con‐
448 figure argument.
449 · {-providerpath list}: Provider classpath
451 · {-v}: Verbose output
453 · {-protected}: Password provided through a protected mechanism
455 Use the -genseckey command to generate a secret key and store it
457 in a new KeyStore.SecretKeyEntry identified by alias.
458 The value of -keyalg specifies the algorithm to be used to gen‐
460 erate the secret key, and the value of -keysize specifies the
461 size of the key that is generated. The -keypass value is a
462 password that protects the secret key. If a password is not
463 provided, then the user is prompted for it. If you press the
464 Return key at the prompt, then the key password is set to the
465 same password that is used for the -keystore. The -keypass val‐
466 ue must contain at least six characters.
467 -importcert
469 The following are the available options for the -importcert com‐
470 mand:
471 · {-noprompt}: Do not prompt
473 · {-trustcacerts}: Trust certificates from cacerts
475 · {-protected}: Password is provided through protected mechanism
477 · {-alias alias}: Alias name of the entry to process
479 · {-file file}: Input file name
481 · [-keypass arg]: Key password
483 · {-keystore keystore}: Keystore name
485 · {-cacerts}: Access the cacerts keystore
487 · [-storepass arg]: Keystore password
489 · {-storetype type}: Keystore type
491 · {-providername name}: Provider name
493 · {-addprovider name [-providerarg arg]}: Add security provider
495 by name (such as SunPKCS11) with an optional configure argu‐
496 ment.
497 · {-providerclass class [-providerarg arg]}: Add security
499 provider by fully qualified class name with an optional con‐
500 figure argument.
501 · {-providerpath list}: Provider classpath
503 · {-v}: Verbose output
505 Use the -importcert command to read the certificate or certifi‐
507 cate chain (where the latter is supplied in a PKCS#7 formatted
508 reply or in a sequence of X.509 certificates) from -file file,
509 and store it in the keystore entry identified by -alias. If
510 -file file is not specified, then the certificate or certificate
511 chain is read from stdin.
512 The keytool command can import X.509 v1, v2, and v3 certifi‐
514 cates, and PKCS#7 formatted certificate chains consisting of
515 certificates of that type. The data to be imported must be pro‐
516 vided either in binary encoding format or in printable encoding
517 format (also known as Base64 encoding) as defined by the Inter‐
518 net RFC 1421 standard. In the latter case, the encoding must be
519 bounded at the beginning by a string that starts with -----BE‐
520 GIN, and bounded at the end by a string that starts with
521 -----END.
522 You import a certificate for two reasons: To add it to the list
524 of trusted certificates, and to import a certificate reply re‐
525 ceived from a certificate authority (CA) as the result of sub‐
526 mitting a Certificate Signing Request (CSR) to that CA. See the
527 -certreq command in Commands for Generating a Certificate Re‐
528 quest.
529 The type of import is indicated by the value of the -alias op‐
531 tion. If the alias doesn't point to a key entry, then the key‐
532 tool command assumes you are adding a trusted certificate entry.
533 In this case, the alias shouldn't already exist in the keystore.
534 If the alias does exist, then the keytool command outputs an er‐
535 ror because a trusted certificate already exists for that alias,
536 and doesn't import the certificate. If -alias points to a key
537 entry, then the keytool command assumes that you're importing a
538 certificate reply.
539 -importpass
541 The following are the available options for the -importpass com‐
542 mand:
543 · {-alias alias}: Alias name of the entry to process
545 · [-keypass arg]: Key password
547 · {-keyalg alg}: Key algorithm name
549 · {-keysize size}: Key bit size
551 · {-keystore keystore}: Keystore name
553 · [-storepass arg]: Keystore password
555 · {-storetype type}: Keystore type
557 · {-providername name}: Provider name
559 · {-addprovider name [-providerarg arg]}: Add security provider
561 by name (such as SunPKCS11) with an optional configure argu‐
562 ment.
563 · {-providerclass class [-providerarg arg]}: Add security
565 provider by fully qualified class name with an optional con‐
566 figure argument.
567 · {-providerpath list}: Provider classpath
569 · {-v}: Verbose output
571 · {-protected}: Password provided through a protected mechanism
573 Use the -importpass command to imports a passphrase and store it
575 in a new KeyStore.SecretKeyEntry identified by -alias. The
576 passphrase may be supplied via the standard input stream; other‐
577 wise the user is prompted for it. The -keypass option provides
578 a password to protect the imported passphrase. If a password is
579 not provided, then the user is prompted for it. If you press
580 the Return key at the prompt, then the key password is set to
581 the same password as that used for the keystore. The -keypass
582 value must contain at least six characters.
583
585 -importkeystore
586 The following are the available options for the -importkeystore
587 command:
588 · {-srckeystore keystore}: Source keystore name
590 · {-destkeystore keystore}: Destination keystore name
592 · {-srcstoretype type}: Source keystore type
594 · {-deststoretype type}: Destination keystore type
596 · [-srcstorepass arg]: Source keystore password
598 · [-deststorepass arg]: Destination keystore password
600 · {-srcprotected}: Source keystore password protected
602 · {-destprotected}: Destination keystore password protected
604 · {-srcprovidername name}: Source keystore provider name
606 · {-destprovidername name}: Destination keystore provider name
608 · {-srcalias alias}: Source alias
610 · {-destalias alias}: Destination alias
612 · [-srckeypass arg]: Source key password
614 · [-destkeypass arg]: Destination key password
616 · {-noprompt}: Do not prompt
618 · {-addprovider name [-providerarg arg]: Add security provider
620 by name (such as SunPKCS11) with an optional configure argu‐
621 ment.
622 · {-providerclass class [-providerarg arg]}: Add security
624 provider by fully qualified class name with an optional con‐
625 figure argument
626 · {-providerpath list}: Provider classpath
628 · {-v}: Verbose output
630 Note:
632 This is the first line of all options:
634 -srckeystore keystore -destkeystore keystore
636 Use the -importkeystore command to import a single entry or all
638 entries from a source keystore to a destination keystore.
639 Note:
641 If you do not specify -destkeystore when using the keytool -im‐
643 portkeystore command, then the default keystore used is
644 $HOME/.keystore.
645 When the -srcalias option is provided, the command imports the
647 single entry identified by the alias to the destination key‐
648 store. If a destination alias isn't provided with -destalias,
649 then -srcalias is used as the destination alias. If the source
650 entry is protected by a password, then -srckeypass is used to
651 recover the entry. If -srckeypass isn't provided, then the key‐
652 tool command attempts to use -srcstorepass to recover the entry.
653 If -srcstorepass is not provided or is incorrect, then the user
654 is prompted for a password. The destination entry is protected
655 with -destkeypass. If -destkeypass isn't provided, then the
656 destination entry is protected with the source entry password.
657 For example, most third-party tools require storepass and key‐
658 pass in a PKCS #12 keystore to be the same. To create a PKCS#12
659 keystore for these tools, always specify a -destkeypass that is
660 the same as -deststorepass.
661 If the -srcalias option isn't provided, then all entries in the
663 source keystore are imported into the destination keystore.
664 Each destination entry is stored under the alias from the source
665 entry. If the source entry is protected by a password, then
666 -srcstorepass is used to recover the entry. If -srcstorepass is
667 not provided or is incorrect, then the user is prompted for a
668 password. If a source keystore entry type isn't supported in
669 the destination keystore, or if an error occurs while storing an
670 entry into the destination keystore, then the user is prompted
671 either to skip the entry and continue or to quit. The destina‐
672 tion entry is protected with the source entry password.
673 If the destination alias already exists in the destination key‐
675 store, then the user is prompted either to overwrite the entry
676 or to create a new entry under a different alias name.
677 If the -noprompt option is provided, then the user isn't prompt‐
679 ed for a new destination alias. Existing entries are overwrit‐
680 ten with the destination alias name. Entries that can't be im‐
681 ported are skipped and a warning is displayed.
682
684 -certreq
685 The following are the available options for the -certreq com‐
686 mand:
687 · {-alias alias}: Alias name of the entry to process
689 · {-sigalg alg}: Signature algorithm name
691 · {-file file}: Output file name
693 · [ -keypass arg]: Key password
695 · {-keystore keystore}: Keystore name
697 · {-dname name}: Distinguished name
699 · {-ext value}: X.509 extension
701 · [-storepass arg]: Keystore password
703 · {-storetype type}: Keystore type
705 · {-providername name}: Provider name
707 · {-addprovider name [-providerarg arg]}: Add security provider
709 by name (such as SunPKCS11) with an optional configure argu‐
710 ment.
711 · {-providerclass class [-providerarg arg]}: Add security
713 provider by fully qualified class name with an optional con‐
714 figure argument.
715 · {-providerpath list}: Provider classpath
717 · {-v}: Verbose output
719 · {-protected}: Password provided through a protected mechanism
721 Use the -certreq command to generate a Certificate Signing Re‐
723 quest (CSR) using the PKCS #10 format.
724 A CSR is intended to be sent to a CA. The CA authenticates the
726 certificate requestor (usually offline) and returns a certifi‐
727 cate or certificate chain to replace the existing certificate
728 chain (initially a self-signed certificate) in the keystore.
729 The private key associated with alias is used to create the PKCS
731 #10 certificate request. To access the private key, the correct
732 password must be provided. If -keypass isn't provided at the
733 command line and is different from the password used to protect
734 the integrity of the keystore, then the user is prompted for it.
735 If -dname is provided, then it is used as the subject in the
736 CSR. Otherwise, the X.500 Distinguished Name associated with
737 alias is used.
738 The -sigalg value specifies the algorithm that should be used to
740 sign the CSR.
741 The CSR is stored in the -file file. If a file is not speci‐
743 fied, then the CSR is output to -stdout.
744 Use the -importcert command to import the response from the CA.
746
748 -exportcert
749 The following are the available options for the -exportcert com‐
750 mand:
751 · {-rfc}: Output in RFC style
753 · {-alias alias}: Alias name of the entry to process
755 · {-file file}: Output file name
757 · {-keystore keystore}: Keystore name
759 · {-cacerts}: Access the cacerts keystore
761 · [-storepass arg]: Keystore password
763 · {-storetype type}: Keystore type
765 · {-providername name}: Provider name
767 · {-addprovider name [-providerarg arg]}: Add security provider
769 by name (such as SunPKCS11) with an optional configure argu‐
770 ment.
771 · {-providerclass class [-providerarg arg] }: Add security
773 provider by fully qualified class name with an optional con‐
774 figure argument.
775 · {-providerpath list}: Provider classpath
777 · {-v}: Verbose output
779 · {-protected}: Password provided through a protected mechanism
781 Use the -exportcert command to read a certificate from the key‐
783 store that is associated with -alias alias and store it in the
784 -file file. When a file is not specified, the certificate is
785 output to stdout.
786 By default, the certificate is output in binary encoding. If
788 the -rfc option is specified, then the output in the printable
789 encoding format defined by the Internet RFC 1421 Certificate En‐
790 coding Standard.
791 If -alias refers to a trusted certificate, then that certificate
793 is output. Otherwise, -alias refers to a key entry with an as‐
794 sociated certificate chain. In that case, the first certificate
795 in the chain is returned. This certificate authenticates the
796 public key of the entity addressed by -alias.
797
799 -list The following are the available options for the -list command:
800 · {-rfc}: Output in RFC style
802 · {-alias alias}: Alias name of the entry to process
804 · {-keystore keystore}: Keystore name
806 · {-cacerts}: Access the cacerts keystore
808 · [-storepass arg]: Keystore password
810 · {-storetype type}: Keystore type
812 · {-providername name}: Provider name
814 · {-addprovider name [-providerarg arg]}: Add security provider
816 by name (such as SunPKCS11) with an optional configure argu‐
817 ment.
818 · {-providerclass class [-providerarg arg] }: Add security
820 provider by fully qualified class name with an optional con‐
821 figure argument.
822 · {-providerpath list}: Provider classpath
824 · {-v}: Verbose output
826 · {-protected}: Password provided through a protected mechanism
828 Use the -list command to print the contents of the keystore en‐
830 try identified by -alias to stdout. If -alias alias is not
831 specified, then the contents of the entire keystore are printed.
832 By default, this command prints the SHA-256 fingerprint of a
834 certificate. If the -v option is specified, then the certifi‐
835 cate is printed in human-readable format, with additional infor‐
836 mation such as the owner, issuer, serial number, and any exten‐
837 sions. If the -rfc option is specified, then the certificate
838 contents are printed by using the printable encoding format, as
839 defined by the Internet RFC 1421 Certificate Encoding Standard.
840 Note:
842 You can't specify both -v and -rfc in the same command. Other‐
844 wise, an error is reported.
845 -printcert
847 The following are the available options for the -printcert com‐
848 mand:
849 · {-rfc}: Output in RFC style
851 · {-file cert_file}: Input file name
853 · {-sslserver server[:port]}:: Secure Sockets Layer (SSL) server
855 host and port
856 · {-jarfile JAR_file}: Signed .jar file
858 · {-v}: Verbose output
860 Use the -printcert command to read and print the certificate
862 from -file cert_file, the SSL server located at -sslserver serv‐
863 er[:port], or the signed JAR file specified by -jarfile
864 JAR_file. It prints its contents in a human-readable format.
865 When a port is not specified, the standard HTTPS port 443 is as‐
866 sumed.
867 Note:
869 The -sslserver and -file options can't be provided in the same
871 command. Otherwise, an error is reported. If you don't specify
872 either option, then the certificate is read from stdin.
873 When-rfc is specified, the keytool command prints the certifi‐
875 cate in PEM mode as defined by the Internet RFC 1421 Certificate
876 Encoding standard.
877 If the certificate is read from a file or stdin, then it might
879 be either binary encoded or in printable encoding format, as de‐
880 fined by the RFC 1421 Certificate Encoding standard.
881 If the SSL server is behind a firewall, then the -J-Dhttps.prox‐
883 yHost=proxyhost and -J-Dhttps.proxyPort=proxyport options can be
884 specified on the command line for proxy tunneling.
885 Note:
887 This option can be used independently of a keystore.
889 -printcertreq
891 The following are the available options for the -printcertreq
892 command:
893 · {-file file}: Input file name
895 · {-v}: Verbose output
897 Use the -printcertreq command to print the contents of a PKCS
899 #10 format certificate request, which can be generated by the
900 keytool -certreq command. The command reads the request from
901 file. If there is no file, then the request is read from the
902 standard input.
903 -printcrl
905 The following are the available options for the -printcrl com‐
906 mand:
907 · -file crl: Input file name
909 · {-v}: Verbose output
911 Use the -printcrl command to read the Certificate Revocation
913 List (CRL) from -file crl . A CRL is a list of the digital cer‐
914 tificates that were revoked by the CA that issued them. The CA
915 generates the crl file.
916 Note:
918 This option can be used independently of a keystore.
920
922 -storepasswd
923 The following are the available options for the -storepasswd
924 command:
925 · [-new arg]: New password
927 · {-keystore keystore}: Keystore name
929 · {-cacerts}: Access the cacerts keystore
931 · [-storepass arg]: Keystore password
933 · {-storetype type}: Keystore type
935 · {-providername name}: Provider name
937 · {-addprovider name [-providerarg arg]}: Add security provider
939 by name (such as SunPKCS11) with an optional configure argu‐
940 ment.
941 · {-providerclass class [-providerarg arg]}: Add security
943 provider by fully qualified class name with an optional con‐
944 figure argument.
945 · {-providerpath list}: Provider classpath
947 · {-v}: Verbose output
949 Use the -storepasswd command to change the password used to pro‐
951 tect the integrity of the keystore contents. The new password
952 is set by -new arg and must contain at least six characters.
953 -keypasswd
955 The following are the available options for the -keypasswd com‐
956 mand:
957 · {-alias alias}: Alias name of the entry to process
959 · [-keypass old_keypass]: Key password
961 · [-new new_keypass]: New password
963 · {-keystore keystore}: Keystore name
965 · {-storepass arg}: Keystore password
967 · {-storetype type}: Keystore type
969 · {-providername name}: Provider name
971 · {-addprovider name [-providerarg arg]}: Add security provider
973 by name (such as SunPKCS11) with an optional configure argu‐
974 ment.
975 · {-providerclass class [-providerarg arg]}: Add security
977 provider by fully qualified class name with an optional con‐
978 figure argument.
979 · {-providerpath list}: Provider classpath
981 · {-v}: Verbose output
983 Use the -keypasswd command to change the password (under which
985 private/secret keys identified by -alias are protected) from
986 -keypass old_keypass to -new new_keypass. The password value
987 must contain at least six characters.
988 If the -keypass option isn't provided at the command line and
990 the -keypass password is different from the keystore password
991 (-storepass arg), then the user is prompted for it.
992 If the -new option isn't provided at the command line, then the
994 user is prompted for it.
995 -delete
997 The following are the available options for the -delete command:
998 · [-alias alias]: Alias name of the entry to process
1000 · {-keystore keystore}: Keystore name
1002 · {-cacerts}: Access the cacerts keystore
1004 · [-storepass arg]: Keystore password
1006 · {-storetype type}: Keystore type
1008 · {-providername name}: Provider name
1010 · {-addprovider name [-providerarg arg]}: Add security provider
1012 by name (such as SunPKCS11) with an optional configure argu‐
1013 ment.
1014 · {-providerclass class [-providerarg arg]}: Add security
1016 provider by fully qualified class name with an optional con‐
1017 figure argument.
1018 · {-providerpath list}: Provider classpath
1020 · {-v}: Verbose output
1022 · {-protected}: Password provided through a protected mechanism
1024 Use the -delete command to delete the -alias alias entry from
1026 the keystore. When not provided at the command line, the user
1027 is prompted for the alias.
1028 -changealias
1030 The following are the available options for the -changealias
1031 command:
1032 · {-alias alias}: Alias name of the entry to process
1034 · [-destalias alias]: Destination alias
1036 · [-keypass arg]: Key password
1038 · {-keystore keystore}: Keystore name
1040 · {-cacerts}: Access the cacerts keystore
1042 · [-storepass arg]: Keystore password
1044 · {-storetype type}: Keystore type
1046 · {-providername name}: Provider name
1048 · {-addprovider name [-providerarg arg]}: Add security provider
1050 by name (such as SunPKCS11) with an optional configure argu‐
1051 ment.
1052 · {-providerclass class [-providerarg arg]}: Add security
1054 provider by fully qualified class name with an optional con‐
1055 figure argument.
1056 · {-providerpath list}: Provider classpath
1058 · {-v}: Verbose output
1060 · {-protected}: Password provided through a protected mechanism
1062 Use the -changealias command to move an existing keystore entry
1064 from -alias alias to a new -destalias alias. If a destination
1065 alias is not provided, then the command prompts you for one. If
1066 the original entry is protected with an entry password, then the
1067 password can be supplied with the -keypass option. If a key
1068 password is not provided, then the -storepass (if provided) is
1069 attempted first. If the attempt fails, then the user is prompt‐
1070 ed for a password.
1071
1073 -showinfo
1074 The following are the available options for the -showinfo com‐
1075 mand:
1076 · {-tls}: Displays TLS configuration information
1078 · {-v}: Verbose output
1080 Use the -showinfo command to display various security-related
1082 information. The -tls option displays TLS configurations, such
1083 as the list of enabled protocols and cipher suites.
1084
1086 You can use --help to display a list of keytool commands or to display
1087 help information about a specific keytool command.
1088 · To display a list of keytool commands, enter:
1090 keytool --help
1092 · To display help information about a specific keytool command, enter:
1094 keytool -<command> --help
1096
1098 The -v option can appear for all commands except --help. When the -v
1099 option appears, it signifies verbose mode, which means that more infor‐
1100 mation is provided in the output.
1101 The -Joption argument can appear for any command. When the -Joption is
1103 used, the specified option string is passed directly to the Java inter‐
1104 preter. This option doesn't contain any spaces. It's useful for ad‐
1105 justing the execution environment or memory usage. For a list of pos‐
1106 sible interpreter options, enter java -h or java -X at the command
1107 line.
1108 These options can appear for all commands operating on a keystore:
1110 -storetype storetype
1112 This qualifier specifies the type of keystore to be instantiat‐
1113 ed.
1114 -keystore keystore
1116 The keystore location.
1117 If the JKS storetype is used and a keystore file doesn't yet ex‐
1119 ist, then certain keytool commands can result in a new keystore
1120 file being created. For example, if keytool -genkeypair is
1121 called and the -keystore option isn't specified, the default
1122 keystore file named .keystore is created in the user's home di‐
1123 rectory if it doesn't already exist. Similarly, if the -key‐
1124 store ks_file option is specified but ks_file doesn't exist,
1125 then it is created. For more information on the JKS storetype,
1126 see the KeyStore Implementation section in KeyStore aliases.
1127 Note that the input stream from the -keystore option is passed
1129 to the KeyStore.load method. If NONE is specified as the URL,
1130 then a null stream is passed to the KeyStore.load method. NONE
1131 should be specified if the keystore isn't file-based. For exam‐
1132 ple, when the keystore resides on a hardware token device.
1133 -cacerts cacerts
1135 Operates on the cacerts keystore . This option is equivalent to
1136 -keystore path_to_cacerts -storetype type_of_cacerts. An error
1137 is reported if the -keystore or -storetype option is used with
1138 the -cacerts option.
1139 -storepass [:env | :file ] argument
1141 The password that is used to protect the integrity of the key‐
1142 store.
1143 If the modifier env or file isn't specified, then the password
1145 has the value argument, which must contain at least six charac‐
1146 ters. Otherwise, the password is retrieved as follows:
1147 · env: Retrieve the password from the environment variable named
1149 argument.
1150 · file: Retrieve the password from the file named argument.
1152 Note: All other options that require passwords, such as -key‐
1154 pass, -srckeypass, -destkeypass, -srcstorepass, and -dest‐
1155 storepass, accept the env and file modifiers. Remember to sepa‐
1156 rate the password option and the modifier with a colon (:).
1157 The password must be provided to all commands that access the
1159 keystore contents. For such commands, when the -storepass op‐
1160 tion isn't provided at the command line, the user is prompted
1161 for it.
1162 When retrieving information from the keystore, the password is
1164 optional. If a password is not specified, then the integrity of
1165 the retrieved information can't be verified and a warning is
1166 displayed.
1167 -providername name
1169 Used to identify a cryptographic service provider's name when
1170 listed in the security properties file.
1171 -addprovider name
1173 Used to add a security provider by name (such as SunPKCS11) .
1174 -providerclass class
1176 Used to specify the name of a cryptographic service provider's
1177 master class file when the service provider isn't listed in the
1178 security properties file.
1179 -providerpath list
1181 Used to specify the provider classpath.
1182 -providerarg arg
1184 Used with the -addprovider or -providerclass option to represent
1185 an optional string input argument for the constructor of class
1186 name.
1187 -protected=true|false
1189 Specify this value as true when a password must be specified by
1190 way of a protected authentication path, such as a dedicated PIN
1191 reader. Because there are two keystores involved in the -im‐
1192 portkeystore command, the following two options, -srcprotected
1193 and -destprotected, are provided for the source keystore and the
1194 destination keystore respectively.
1195 -ext {name{:critical} {=value}}
1197 Denotes an X.509 certificate extension. The option can be used
1198 in -genkeypair and -gencert to embed extensions into the gener‐
1199 ated certificate, or in -certreq to show what extensions are re‐
1200 quested in the certificate request. The option can appear mul‐
1201 tiple times. The name argument can be a supported extension
1202 name (see Supported Named Extensions) or an arbitrary OID num‐
1203 ber. The value argument, when provided, denotes the argument
1204 for the extension. When value is omitted, the default value of
1205 the extension or the extension itself requires no argument. The
1206 :critical modifier, when provided, means the extension's isCrit‐
1207 ical attribute is true; otherwise, it is false. You can use :c
1208 in place of :critical.
1209 -conf file
1211 Specifies a pre-configured options file.
1212
1214 A pre-configured options file is a Java properties file that can be
1215 specified with the -conf option. Each property represents the default
1216 option(s) for a keytool command using "keytool.command_name" as the
1217 property name. A special property named "keytool.all" represents the
1218 default option(s) applied to all commands. A property value can in‐
1219 clude ${prop} which will be expanded to the system property associated
1220 with it. If an option value includes white spaces inside, it should be
1221 surrounded by quotation marks (" or '). All property names must be in
1222 lower case.
1223 When keytool is launched with a pre-configured options file, the value
1225 for "keytool.all" (if it exists) is prepended to the keytool command
1226 line first, with the value for the command name (if it exists) comes
1227 next, and the existing options on the command line at last. For a sin‐
1228 gle-valued option, this allows the property for a specific command to
1229 override the "keytool.all" value, and the value specified on the com‐
1230 mand line to override both. For multiple-valued options, all of them
1231 will be used by keytool.
1232 For example, given the following file named preconfig:
1234 # A tiny pre-configured options file
1236 keytool.all = -keystore ${user.home}/ks
1237 keytool.list = -v
1238 keytool.genkeypair = -keyalg rsa
1239 keytool -conf preconfig -list is identical to
1241 keytool -keystore ~/ks -v -list
1243 keytool -conf preconfig -genkeypair -alias me is identical to
1245 keytool -keystore ~/ks -keyalg rsa -genkeypair -alias me
1247 keytool -conf preconfig -genkeypair -alias you -keyalg ec is identical
1249 to
1250 keytool -keystore ~/ks -keyalg rsa -genkey‐
1252 pair -alias you -keyalg ec
1253 which is equivalent to
1255 keytool -keystore ~/ks -genkeypair -alias you -keyalg ec
1257 because -keyalg is a single-valued option and the ec value specified on
1259 the command line overrides the preconfigured options file.
1260
1262 The following examples show the defaults for various option values:
1263 -alias "mykey"
1265 -keyalg
1267 "DSA" (when using -genkeypair)
1268 "DES" (when using -genseckey)
1269 -keysize
1271 2048 (when using -genkeypair and -keyalg is "RSA")
1272 2048 (when using -genkeypair and -keyalg is "DSA")
1273 256 (when using -genkeypair and -keyalg is "EC")
1274 56 (when using -genseckey and -keyalg is "DES")
1275 168 (when using -genseckey and -keyalg is "DESede")
1276 -validity 90
1278 -keystore <the file named .keystore in the user's home directory>
1280 -destkeystore <the file named .keystore in the user's home directory>
1282 -storetype <the value of the "keystore.type" property in the
1284 security properties file, which is returned by the static
1285 getDefaultType method in java.security.KeyStore>
1286 -file
1288 stdin (if reading)
1289 stdout (if writing)
1290 -protected false
1292 When generating a certificate or a certificate request, the default
1294 signature algorithm (-sigalg option) is derived from the algorithm of
1295 the underlying private key to provide an appropriate level of security
1296 strength as follows:
1297 keyalg keysize default sigalg
1299 ─────────────────────────────────────
1300 DSA any size SHA256withDSA
1301 RSA <= 3072 SHA256withRSA
1302 <= 7680 SHA384withRSA
1303 > 7680 SHA512withRSA
1304 EC < 384 SHA256withECDSA
1305 < 512 SHA384withECDSA
1306 = 512 SHA512withECDSA
1307 Note:
1309 To improve out of the box security, default key size and signature al‐
1311 gorithm names are periodically updated to stronger values with each re‐
1312 lease of the JDK. If interoperability with older releases of the JDK
1313 is important, make sure that the defaults are supported by those re‐
1314 leases. Alternatively, you can use the -keysize or -sigalg options to
1315 override the default values at your own risk.
1316
1318 The keytool command supports these named extensions. The names aren't
1319 case-sensitive.
1320 BC or BasicContraints
1322 Values:
1323 The full form is ca:{true|false}[,pathlen:len] or len, which is
1325 short for ca:true,pathlen:len.
1326 When len is omitted, the resulting value is ca:true.
1328 KU or KeyUsage
1330 Values:
1331 usage(, usage)*
1333 usage can be one of the following:
1335 · digitalSignature
1337 · nonRepudiation (contentCommitment)
1339 · keyEncipherment
1341 · dataEncipherment
1343 · keyAgreement
1345 · keyCertSign
1347 · cRLSign
1349 · encipherOnly
1351 · decipherOnly
1353 Provided there is no ambiguity, the usage argument can be abbre‐
1355 viated with the first few letters (such as dig for digitalSigna‐
1356 ture) or in camel-case style (such as dS for digitalSignature or
1357 cRLS for cRLSign). The usage values are case-sensitive.
1358 EKU or ExtendedKeyUsage
1360 Values:
1361 usage(, usage)*
1363 usage can be one of the following:
1365 · anyExtendedKeyUsage
1367 · serverAuth
1369 · clientAuth
1371 · codeSigning
1373 · emailProtection
1375 · timeStamping
1377 · OCSPSigning
1379 · Any OID string
1381 Provided there is no ambiguity, the usage argument can be abbre‐
1383 viated with the first few letters or in camel-case style. The
1384 usage values are case-sensitive.
1385 SAN or SubjectAlternativeName
1387 Values:
1388 type:value(, type:value)*
1390 type can be one of the following:
1392 · EMAIL
1394 · URI
1396 · DNS
1398 · IP
1400 · OID
1402 The value argument is the string format value for the type.
1404 IAN or IssuerAlternativeName
1406 Values:
1407 Same as SAN or SubjectAlternativeName.
1409 SIA or SubjectInfoAccess
1411 Values:
1412 method:location-type:location-value(, method:location-type:loca‐
1414 tion-value)*
1415 method can be one of the following:
1417 · timeStamping
1419 · caRepository
1421 · Any OID
1423 The location-type and location-value arguments can be any
1425 type:value supported by the SubjectAlternativeName extension.
1426 AIA or AuthorityInfoAccess
1428 Values:
1429 Same as SIA or SubjectInfoAccess.
1431 The method argument can be one of the following:
1433 · ocsp
1435 · caIssuers
1437 · Any OID
1439 When name is OID, the value is the hexadecimal dumped Definite Encoding
1441 Rules (DER) encoding of the extnValue for the extension excluding the
1442 OCTET STRING type and length bytes. Other than standard hexadecimal
1443 numbers (0-9, a-f, A-F), any extra characters are ignored in the HEX
1444 string. Therefore, both 01:02:03:04 and 01020304 are accepted as iden‐
1445 tical values. When there is no value, the extension has an empty value
1446 field.
1447 A special name honored, used only in -gencert, denotes how the exten‐
1449 sions included in the certificate request should be honored. The value
1450 for this name is a comma-separated list of all (all requested exten‐
1451 sions are honored), name{:[critical|non-critical]} (the named extension
1452 is honored, but it uses a different isCritical attribute), and -name
1453 (used with all, denotes an exception). Requested extensions aren't
1454 honored by default.
1455 If, besides the-ext honored option, another named or OID -ext option is
1457 provided, this extension is added to those already honored. However,
1458 if this name (or OID) also appears in the honored value, then its value
1459 and criticality override that in the request. If an extension of the
1460 same type is provided multiple times through either a name or an OID,
1461 only the last extension is used.
1462 The subjectKeyIdentifier extension is always created. For
1464 non-self-signed certificates, the authorityKeyIdentifier is created.
1465 CAUTION:
1467 Users should be aware that some combinations of extensions (and other
1469 certificate fields) may not conform to the Internet standard. See Cer‐
1470 tificate Conformance Warning.
1471
1473 The following examples describe the sequence actions in creating a key‐
1474 store for managing public/private key pairs and certificates from
1475 trusted entities.
1476 · Generating the Key Pair
1478 · Requesting a Signed Certificate from a CA
1480 · Importing a Certificate for the CA
1482 · Importing the Certificate Reply from the CA
1484 · Exporting a Certificate That Authenticates the Public Key
1486 · Importing the Keystore
1488 · Generating Certificates for an SSL Server
1490
1492 Create a keystore and then generate the key pair.
1493 You can enter the command as a single line such as the following:
1495 keytool -genkeypair -dname "cn=myname, ou=mygroup, o=mycompa‐
1497 ny, c=mycountry" -alias business -keypass password -key‐
1498 store /working/mykeystore -storepass password -validity 180
1499 The command creates the keystore named mykeystore in the working direc‐
1501 tory (provided it doesn't already exist), and assigns it the password
1502 specified by -keypass. It generates a public/private key pair for the
1503 entity whose distinguished name is myname, mygroup, mycompany, and a
1504 two-letter country code of mycountry. It uses the default DSA key gen‐
1505 eration algorithm to create the keys; both are 2048 bits
1506 The command uses the default SHA256withDSA signature algorithm to cre‐
1508 ate a self-signed certificate that includes the public key and the dis‐
1509 tinguished name information. The certificate is valid for 180 days,
1510 and is associated with the private key in a keystore entry referred to
1511 by -alias business. The private key is assigned the password specified
1512 by -keypass.
1513 The command is significantly shorter when the option defaults are ac‐
1515 cepted. In this case, no options are required, and the defaults are
1516 used for unspecified options that have default values. You are prompt‐
1517 ed for any required values. You could have the following:
1518 keytool -genkeypair
1520 In this case, a keystore entry with the alias mykey is created, with a
1522 newly generated key pair and a certificate that is valid for 90 days.
1523 This entry is placed in your home directory in a keystore named .key‐
1524 store . .keystore is created if it doesn't already exist. You are
1525 prompted for the distinguished name information, the keystore password,
1526 and the private key password.
1527 Note:
1529 The rest of the examples assume that you executed the -genkeypair com‐
1531 mand without specifying options, and that you responded to the prompts
1532 with values equal to those specified in the first -genkeypair command.
1533 For example, a distinguished name of cn=myname, ou=mygroup, o=mycompa‐
1534 ny, c=mycountry).
1535
1537 Note:
1538 Generating the key pair created a self-signed certificate; however, a
1540 certificate is more likely to be trusted by others when it is signed by
1541 a CA.
1542 To get a CA signature, complete the following process:
1544 1. Generate a CSR:
1546 keytool -certreq -file myname.csr
1548 This creates a CSR for the entity identified by the default alias
1550 mykey and puts the request in the file named myname.csr.
1551 2. Submit myname.csr to a CA, such as DigiCert.
1553 The CA authenticates you, the requestor (usually offline), and returns
1555 a certificate, signed by them, authenticating your public key. In some
1556 cases, the CA returns a chain of certificates, each one authenticating
1557 the public key of the signer of the previous certificate in the chain.
1558
1560 To import a certificate for the CA, complete the following process:
1561 1. Before you import the certificate reply from a CA, you need one or
1563 more trusted certificates either in your keystore or in the cacerts
1564 keystore file. See -importcert in Commands.
1565 · If the certificate reply is a certificate chain, then you need
1567 the top certificate of the chain. The root CA certificate that
1568 authenticates the public key of the CA.
1569 · If the certificate reply is a single certificate, then you need a
1571 certificate for the issuing CA (the one that signed it). If that
1572 certificate isn't self-signed, then you need a certificate for
1573 its signer, and so on, up to a self-signed root CA certificate.
1574 The cacerts keystore ships with a set of root certificates issued
1576 by the CAs of the Oracle Java Root Certificate program
1577 [http://www.oracle.com/technetwork/java/javase/javasecarootcert‐
1578 sprogram-1876540.html]. If you request a signed certificate from a
1579 CA, and a certificate authenticating that CA's public key hasn't
1580 been added to cacerts, then you must import a certificate from that
1581 CA as a trusted certificate.
1582 A certificate from a CA is usually self-signed or signed by another
1584 CA. If it is signed by another CA, you need a certificate that au‐
1585 thenticates that CA's public key.
1586 For example, you have obtained a X.cer file from a company that is
1588 a CA and the file is supposed to be a self-signed certificate that
1589 authenticates that CA's public key. Before you import it as a
1590 trusted certificate, you should ensure that the certificate is
1591 valid by:
1592 1. Viewing it with the keytool -printcert command or the key‐
1594 tool -importcert command without using the -noprompt option.
1595 Make sure that the displayed certificate fingerprints match the
1596 expected fingerprints.
1597 2. Calling the person who sent the certificate, and comparing the
1599 fingerprints that you see with the ones that they show or that a
1600 secure public key repository shows.
1601 Only when the fingerprints are equal is it assured that the cer‐
1603 tificate wasn't replaced in transit with somebody else's certifi‐
1604 cate (such as an attacker's certificate). If such an attack takes
1605 place, and you didn't check the certificate before you imported it,
1606 then you would be trusting anything that the attacker signed.
1607 2. Replace the self-signed certificate with a certificate chain, where
1609 each certificate in the chain authenticates the public key of the
1610 signer of the previous certificate in the chain, up to a root CA.
1611 If you trust that the certificate is valid, then you can add it to
1613 your keystore by entering the following command:
1614 keytool -importcert -alias alias -file *X*.cer`
1616 This command creates a trusted certificate entry in the keystore
1618 from the data in the CA certificate file and assigns the values of
1619 the alias to the entry.
1620
1622 After you import a certificate that authenticates the public key of the
1623 CA that you submitted your certificate signing request to (or there is
1624 already such a certificate in the cacerts file), you can import the
1625 certificate reply and replace your self-signed certificate with a cer‐
1626 tificate chain.
1627 The certificate chain is one of the following:
1629 · Returned by the CA when the CA reply is a chain.
1631 · Constructed when the CA reply is a single certificate. This certifi‐
1633 cate chain is constructed by using the certificate reply and trusted
1634 certificates available either in the keystore where you import the
1635 reply or in the cacerts keystore file.
1636 For example, if you sent your certificate signing request to DigiCert,
1638 then you can import their reply by entering the following command:
1639 Note:
1641 In this example, the returned certificate is named DCmyname.cer.
1643 keytool -importcert -trustcacerts -file DCmyname.cer
1645
1647 Note:
1648 If you used the jarsigner command to sign a Java Archive (JAR) file,
1650 then clients that use the file will want to authenticate your signa‐
1651 ture.
1652 One way that clients can authenticate you is by importing your public
1654 key certificate into their keystore as a trusted entry. You can then
1655 export the certificate and supply it to your clients.
1656 For example:
1658 1. Copy your certificate to a file named myname.cer by entering the
1660 following command:
1661 Note:
1663 In this example, the entry has an alias of mykey.
1665 keytool -exportcert -alias mykey -file myname.cer
1667 2. With the certificate and the signed JAR file, a client can use the
1669 jarsigner command to authenticate your signature.
1670
1672 Use the importkeystore command to import an entire keystore into anoth‐
1673 er keystore. This imports all entries from the source keystore, in‐
1674 cluding keys and certificates, to the destination keystore with a sin‐
1675 gle command. You can use this command to import entries from a differ‐
1676 ent type of keystore. During the import, all new entries in the desti‐
1677 nation keystore will have the same alias names and protection passwords
1678 (for secret keys and private keys). If the keytool command can't re‐
1679 cover the private keys or secret keys from the source keystore, then it
1680 prompts you for a password. If it detects alias duplication, then it
1681 asks you for a new alias, and you can specify a new alias or simply al‐
1682 low the keytool command to overwrite the existing one.
1683 For example, import entries from a typical JKS type keystore key.jks
1685 into a PKCS #11 type hardware-based keystore, by entering the following
1686 command:
1687 keytool -importkeystore -srckeystore key.jks -destkey‐
1689 store NONE -srcstoretype JKS -deststoretype PKCS11 -srcstorepass
1690 password -deststorepass password
1691 The importkeystore command can also be used to import a single entry
1693 from a source keystore to a destination keystore. In this case, be‐
1694 sides the options you used in the previous example, you need to specify
1695 the alias you want to import. With the -srcalias option specified, you
1696 can also specify the destination alias name, protection password for a
1697 secret or private key, and the destination protection password you want
1698 as follows:
1699 keytool -importkeystore -srckeystore key.jks -destkey‐
1701 store NONE -srcstoretype JKS -deststoretype PKCS11 -srcstorepass
1702 password -deststorepass password -srcalias myprivatekey -destal‐
1703 ias myoldprivatekey -srckeypass password -destkeypass password
1704 -noprompt
1705
1707 The following are keytool commands used to generate key pairs and cer‐
1708 tificates for three entities:
1709 · Root CA (root)
1711 · Intermediate CA (ca)
1713 · SSL server (server)
1715 Ensure that you store all the certificates in the same keystore. In
1717 the following examples, RSA is the recommended the key algorithm.
1718 keytool -genkeypair -keystore root.jks -alias root -ext bc:c
1720 keytool -genkeypair -keystore ca.jks -alias ca -ext bc:c
1721 keytool -genkeypair -keystore server.jks -alias server
1722 keytool -keystore root.jks -alias root -exportcert -rfc > root.pem
1724 keytool -storepass password -keystore ca.jks -certreq -alias ca |
1726 keytool -storepass password -keystore root.jks
1727 -gencert -alias root -ext BC=0 -rfc > ca.pem
1728 keytool -keystore ca.jks -importcert -alias ca -file ca.pem
1729 keytool -storepass password -keystore server.jks -certreq -alias server |
1731 keytool -storepass password -keystore ca.jks -gencert -alias ca
1732 -ext ku:c=dig,kE -rfc > server.pem
1733 cat root.pem ca.pem server.pem |
1734 keytool -keystore server.jks -importcert -alias server
1735
1737 Keystore
1738 A keystore is a storage facility for cryptographic keys and cer‐
1739 tificates.
1740 Keystore entries
1742 Keystores can have different types of entries. The two most ap‐
1743 plicable entry types for the keytool command include the follow‐
1744 ing:
1745 Key entries: Each entry holds very sensitive cryptographic key
1747 information, which is stored in a protected format to prevent
1748 unauthorized access. Typically, a key stored in this type of
1749 entry is a secret key, or a private key accompanied by the cer‐
1750 tificate chain for the corresponding public key. See Certifi‐
1751 cate Chains. The keytool command can handle both types of en‐
1752 tries, while the jarsigner tool only handles the latter type of
1753 entry, that is private keys and their associated certificate
1754 chains.
1755 Trusted certificate entries: Each entry contains a single public
1757 key certificate that belongs to another party. The entry is
1758 called a trusted certificate because the keystore owner trusts
1759 that the public key in the certificate belongs to the identity
1760 identified by the subject (owner) of the certificate. The is‐
1761 suer of the certificate vouches for this, by signing the cer‐
1762 tificate.
1763 Keystore aliases
1765 All keystore entries (key and trusted certificate entries) are
1766 accessed by way of unique aliases.
1767 An alias is specified when you add an entity to the keystore
1769 with the -genseckey command to generate a secret key, the
1770 -genkeypair command to generate a key pair (public and private
1771 key), or the -importcert command to add a certificate or cer‐
1772 tificate chain to the list of trusted certificates. Subsequent
1773 keytool commands must use this same alias to refer to the enti‐
1774 ty.
1775 For example, you can use the alias duke to generate a new pub‐
1777 lic/private key pair and wrap the public key into a self-signed
1778 certificate with the following command. See Certificate Chains.
1779 keytool -genkeypair -alias duke -keypass passwd
1781 This example specifies an initial passwd required by subsequent
1783 commands to access the private key associated with the alias
1784 duke. If you later want to change Duke's private key password,
1785 use a command such as the following:
1786 keytool -keypasswd -alias duke -keypass passwd -new new‐
1788 passwd
1789 This changes the initial passwd to newpasswd. A password
1791 shouldn't be specified on a command line or in a script unless
1792 it is for testing purposes, or you are on a secure system. If
1793 you don't specify a required password option on a command line,
1794 then you are prompted for it.
1795 Keystore implementation
1797 The KeyStore class provided in the java.security package sup‐
1798 plies well-defined interfaces to access and modify the informa‐
1799 tion in a keystore. It is possible for there to be multiple
1800 different concrete implementations, where each implementation is
1801 that for a particular type of keystore.
1802 Currently, two command-line tools (keytool and jarsigner) make
1804 use of keystore implementations. Because the KeyStore class is
1805 public, users can write additional security applications that
1806 use it.
1807 In JDK 9 and later, the default keystore implementation is
1809 PKCS12. This is a cross platform keystore based on the RSA
1810 PKCS12 Personal Information Exchange Syntax Standard. This
1811 standard is primarily meant for storing or transporting a user's
1812 private keys, certificates, and miscellaneous secrets. There is
1813 another built-in implementation, provided by Oracle. It imple‐
1814 ments the keystore as a file with a proprietary keystore type
1815 (format) named JKS. It protects each private key with its indi‐
1816 vidual password, and also protects the integrity of the entire
1817 keystore with a (possibly different) password.
1818 Keystore implementations are provider-based. More specifically,
1820 the application interfaces supplied by KeyStore are implemented
1821 in terms of a Service Provider Interface (SPI). That is, there
1822 is a corresponding abstract KeystoreSpi class, also in the ja‐
1823 va.security package, which defines the Service Provider Inter‐
1824 face methods that providers must implement. The term provider
1825 refers to a package or a set of packages that supply a concrete
1826 implementation of a subset of services that can be accessed by
1827 the Java Security API. To provide a keystore implementation,
1828 clients must implement a provider and supply a KeystoreSpi sub‐
1829 class implementation, as described in Steps to Implement and In‐
1830 tegrate a Provider.
1831 Applications can choose different types of keystore implementa‐
1833 tions from different providers, using the getInstance factory
1834 method supplied in the KeyStore class. A keystore type defines
1835 the storage and data format of the keystore information, and the
1836 algorithms used to protect private/secret keys in the keystore
1837 and the integrity of the keystore. Keystore implementations of
1838 different types aren't compatible.
1839 The keytool command works on any file-based keystore implementa‐
1841 tion. It treats the keystore location that is passed to it at
1842 the command line as a file name and converts it to a FileInput‐
1843 Stream, from which it loads the keystore information.)The jar‐
1844 signer commands can read a keystore from any location that can
1845 be specified with a URL.
1846 For keytool and jarsigner, you can specify a keystore type at
1848 the command line, with the -storetype option.
1849 If you don't explicitly specify a keystore type, then the tools
1851 choose a keystore implementation based on the value of the key‐
1852 store.type property specified in the security properties file.
1853 The security properties file is called java.security, and re‐
1854 sides in the security properties directory:
1855 · Oracle Solaris, Linux, and OS X: java.home/lib/security
1857 · Windows: java.home\lib\security
1859 Each tool gets the keystore.type value and then examines all the
1861 currently installed providers until it finds one that implements
1862 a keystores of that type. It then uses the keystore implementa‐
1863 tion from that provider.The KeyStore class defines a static
1864 method named getDefaultType that lets applications retrieve the
1865 value of the keystore.type property. The following line of code
1866 creates an instance of the default keystore type as specified in
1867 the keystore.type property:
1868 KeyStore keyStore = KeyStore.getInstance(KeyStore.getDe‐
1870 faultType());
1871 The default keystore type is pkcs12, which is a cross-platform
1873 keystore based on the RSA PKCS12 Personal Information Exchange
1874 Syntax Standard. This is specified by the following line in the
1875 security properties file:
1876 keystore.type=pkcs12
1878 To have the tools utilize a keystore implementation other than
1880 the default, you can change that line to specify a different
1881 keystore type. For example, if you want to use the Oracle's jks
1882 keystore implementation, then change the line to the following:
1883 keystore.type=jks
1885 Note:
1887 Case doesn't matter in keystore type designations. For example,
1889 JKS would be considered the same as jks.
1890 Certificate
1892 A certificate (or public-key certificate) is a digitally signed
1893 statement from one entity (the issuer), saying that the public
1894 key and some other information of another entity (the subject)
1895 has some specific value. The following terms are related to
1896 certificates:
1897 · Public Keys: These are numbers associated with a particular
1899 entity, and are intended to be known to everyone who needs to
1900 have trusted interactions with that entity. Public keys are
1901 used to verify signatures.
1902 · Digitally Signed: If some data is digitally signed, then it is
1904 stored with the identity of an entity and a signature that
1905 proves that entity knows about the data. The data is rendered
1906 unforgeable by signing with the entity's private key.
1907 · Identity: A known way of addressing an entity. In some sys‐
1909 tems, the identity is the public key, and in others it can be
1910 anything from an Oracle Solaris UID to an email address to an
1911 X.509 distinguished name.
1912 · Signature: A signature is computed over some data using the
1914 private key of an entity. The signer, which in the case of a
1915 certificate is also known as the issuer.
1916 · Private Keys: These are numbers, each of which is supposed to
1918 be known only to the particular entity whose private key it is
1919 (that is, it is supposed to be kept secret). Private and pub‐
1920 lic keys exist in pairs in all public key cryptography systems
1921 (also referred to as public key crypto systems). In a typical
1922 public key crypto system, such as DSA, a private key corre‐
1923 sponds to exactly one public key. Private keys are used to
1924 compute signatures.
1925 · Entity: An entity is a person, organization, program, comput‐
1927 er, business, bank, or something else you are trusting to some
1928 degree.
1929 Public key cryptography requires access to users' public keys.
1931 In a large-scale networked environment, it is impossible to
1932 guarantee that prior relationships between communicating enti‐
1933 ties were established or that a trusted repository exists with
1934 all used public keys. Certificates were invented as a solution
1935 to this public key distribution problem. Now a Certification
1936 Authority (CA) can act as a trusted third party. CAs are enti‐
1937 ties such as businesses that are trusted to sign (issue) cer‐
1938 tificates for other entities. It is assumed that CAs only cre‐
1939 ate valid and reliable certificates because they are bound by
1940 legal agreements. There are many public Certification Authori‐
1941 ties, such as DigiCert, Comodo, Entrust, and so on.
1942 You can also run your own Certification Authority using products
1944 such as Microsoft Certificate Server or the Entrust CA product
1945 for your organization. With the keytool command, it is possible
1946 to display, import, and export certificates. It is also possi‐
1947 ble to generate self-signed certificates.
1948 The keytool command currently handles X.509 certificates.
1950 X.509 Certificates
1952 The X.509 standard defines what information can go into a cer‐
1953 tificate and describes how to write it down (the data format).
1954 All the data in a certificate is encoded with two related stan‐
1955 dards called ASN.1/DER. Abstract Syntax Notation 1 describes
1956 data. The Definite Encoding Rules describe a single way to
1957 store and transfer that data.
1958 All X.509 certificates have the following data, in addition to
1960 the signature:
1961 · Version: This identifies which version of the X.509 standard
1963 applies to this certificate, which affects what information
1964 can be specified in it. Thus far, three versions are defined.
1965 The keytool command can import and export v1, v2, and v3 cer‐
1966 tificates. It generates v3 certificates.
1967 · X.509 Version 1 has been available since 1988, is widely de‐
1969 ployed, and is the most generic.
1970 · X.509 Version 2 introduced the concept of subject and issuer
1972 unique identifiers to handle the possibility of reuse of
1973 subject or issuer names over time. Most certificate profile
1974 documents strongly recommend that names not be reused and
1975 that certificates shouldn't make use of unique identifiers.
1976 Version 2 certificates aren't widely used.
1977 · X.509 Version 3 is the most recent (1996) and supports the
1979 notion of extensions where anyone can define an extension
1980 and include it in the certificate. Some common extensions
1981 are: KeyUsage (limits the use of the keys to particular pur‐
1982 poses such as signing-only) and AlternativeNames (allows
1983 other identities to also be associated with this public key,
1984 for example. DNS names, email addresses, IP addresses).
1985 Extensions can be marked critical to indicate that the ex‐
1986 tension should be checked and enforced or used. For exam‐
1987 ple, if a certificate has the KeyUsage extension marked
1988 critical and set to keyCertSign, then when this certificate
1989 is presented during SSL communication, it should be rejected
1990 because the certificate extension indicates that the associ‐
1991 ated private key should only be used for signing certifi‐
1992 cates and not for SSL use.
1993 · Serial number: The entity that created the certificate is re‐
1995 sponsible for assigning it a serial number to distinguish it
1996 from other certificates it issues. This information is used
1997 in numerous ways. For example, when a certificate is revoked
1998 its serial number is placed in a Certificate Revocation List
1999 (CRL).
2000 · Signature algorithm identifier: This identifies the algorithm
2002 used by the CA to sign the certificate.
2003 · Issuer name: The X.500 Distinguished Name of the entity that
2005 signed the certificate. This is typically a CA. Using this
2006 certificate implies trusting the entity that signed this cer‐
2007 tificate. In some cases, such as root or top-level CA cer‐
2008 tificates, the issuer signs its own certificate.
2009 · Validity period: Each certificate is valid only for a limited
2011 amount of time. This period is described by a start date and
2012 time and an end date and time, and can be as short as a few
2013 seconds or almost as long as a century. The validity period
2014 chosen depends on a number of factors, such as the strength of
2015 the private key used to sign the certificate, or the amount
2016 one is willing to pay for a certificate. This is the expected
2017 period that entities can rely on the public value, when the
2018 associated private key has not been compromised.
2019 · Subject name: The name of the entity whose public key the cer‐
2021 tificate identifies. This name uses the X.500 standard, so it
2022 is intended to be unique across the Internet. This is the
2023 X.500 Distinguished Name (DN) of the entity. For example,
2024 CN=Java Duke, OU=Java Software Division, O=Oracle Cor‐
2026 poration, C=US
2027 These refer to the subject's common name (CN), organizational
2029 unit (OU), organization (O), and country (C).
2030 · Subject public key information: This is the public key of the
2032 entity being named with an algorithm identifier that specifies
2033 which public key crypto system this key belongs to and any as‐
2034 sociated key parameters.
2035 Certificate Chains
2037 The keytool command can create and manage keystore key entries
2038 that each contain a private key and an associated certificate
2039 chain. The first certificate in the chain contains the public
2040 key that corresponds to the private key.
2041 When keys are first generated, the chain starts off containing a
2043 single element, a self-signed certificate. See -genkeypair in
2044 Commands. A self-signed certificate is one for which the issuer
2045 (signer) is the same as the subject. The subject is the entity
2046 whose public key is being authenticated by the certificate.
2047 Whenever the -genkeypair command is called to generate a new
2048 public/private key pair, it also wraps the public key into a
2049 self-signed certificate.
2050 Later, after a Certificate Signing Request (CSR) was generated
2052 with the -certreq command and sent to a Certification Authority
2053 (CA), the response from the CA is imported with -importcert, and
2054 the self-signed certificate is replaced by a chain of certifi‐
2055 cates. At the bottom of the chain is the certificate (reply)
2056 issued by the CA authenticating the subject's public key. The
2057 next certificate in the chain is one that authenticates the CA's
2058 public key.
2059 In many cases, this is a self-signed certificate, which is a
2061 certificate from the CA authenticating its own public key, and
2062 the last certificate in the chain. In other cases, the CA might
2063 return a chain of certificates. In this case, the bottom cer‐
2064 tificate in the chain is the same (a certificate signed by the
2065 CA, authenticating the public key of the key entry), but the
2066 second certificate in the chain is a certificate signed by a
2067 different CA that authenticates the public key of the CA you
2068 sent the CSR to. The next certificate in the chain is a cer‐
2069 tificate that authenticates the second CA's key, and so on, un‐
2070 til a self-signed root certificate is reached. Each certificate
2071 in the chain (after the first) authenticates the public key of
2072 the signer of the previous certificate in the chain.
2073 Many CAs only return the issued certificate, with no supporting
2075 chain, especially when there is a flat hierarchy (no intermedi‐
2076 ates CAs). In this case, the certificate chain must be estab‐
2077 lished from trusted certificate information already stored in
2078 the keystore.
2079 A different reply format (defined by the PKCS #7 standard) in‐
2081 cludes the supporting certificate chain in addition to the is‐
2082 sued certificate. Both reply formats can be handled by the key‐
2083 tool command.
2084 The top-level (root) CA certificate is self-signed. However,
2086 the trust into the root's public key doesn't come from the root
2087 certificate itself, but from other sources such as a newspaper.
2088 This is because anybody could generate a self-signed certificate
2089 with the distinguished name of, for example, the DigiCert root
2090 CA. The root CA public key is widely known. The only reason it
2091 is stored in a certificate is because this is the format under‐
2092 stood by most tools, so the certificate in this case is only
2093 used as a vehicle to transport the root CA's public key. Before
2094 you add the root CA certificate to your keystore, you should
2095 view it with the -printcert option and compare the displayed
2096 fingerprint with the well-known fingerprint obtained from a
2097 newspaper, the root CA's Web page, and so on.
2098 cacerts Certificates File
2100 A certificates file named cacerts resides in the security prop‐
2101 erties directory:
2102 · Oracle Solaris, Linux, and OS X: JAVA_HOME/lib/security
2104 · Windows: JAVA_HOME\lib\security
2106 JAVA_HOME is the runtime environment directory, which is the jre
2108 directory in the JDK or the top-level directory of the Java Run‐
2109 time Environment (JRE).
2110 The cacerts file represents a system-wide keystore with CA cer‐
2112 tificates. System administrators can configure and manage that
2113 file with the keytool command by specifying jks as the keystore
2114 type. The cacerts keystore file ships with a default set of
2115 root CA certificates. For Oracle Solaris, Linux, OS X, and Win‐
2116 dows, you can list the default certificates with the following
2117 command:
2118 keytool -list -cacerts
2120 The initial password of the cacerts keystore file is changeit.
2122 System administrators should change that password and the de‐
2123 fault access permission of that file upon installing the SDK.
2124 Note:
2126 It is important to verify your cacerts file. Because you trust
2128 the CAs in the cacerts file as entities for signing and issuing
2129 certificates to other entities, you must manage the cacerts file
2130 carefully. The cacerts file should contain only certificates of
2131 the CAs you trust. It is your responsibility to verify the
2132 trusted root CA certificates bundled in the cacerts file and
2133 make your own trust decisions.
2134 To remove an untrusted CA certificate from the cacerts file, use
2136 the -delete option of the keytool command. You can find the
2137 cacerts file in the JRE installation directory. Contact your
2138 system administrator if you don't have permission to edit this
2139 file
2140 Internet RFC 1421 Certificate Encoding Standard
2142 Certificates are often stored using the printable encoding for‐
2143 mat defined by the Internet RFC 1421 standard, instead of their
2144 binary encoding. This certificate format, also known as Base64
2145 encoding, makes it easy to export certificates to other applica‐
2146 tions by email or through some other mechanism.
2147 Certificates read by the -importcert and -printcert commands can
2149 be in either this format or binary encoded. The -exportcert
2150 command by default outputs a certificate in binary encoding, but
2151 will instead output a certificate in the printable encoding for‐
2152 mat, when the -rfc option is specified.
2153 The -list command by default prints the SHA-256 fingerprint of a
2155 certificate. If the -v option is specified, then the certifi‐
2156 cate is printed in human-readable format. If the -rfc option is
2157 specified, then the certificate is output in the printable en‐
2158 coding format.
2159 In its printable encoding format, the encoded certificate is
2161 bounded at the beginning and end by the following text:
2162 -----BEGIN CERTIFICATE-----
2164 encoded certificate goes here.
2166 -----END CERTIFICATE-----
2168 X.500 Distinguished Names
2170 X.500 Distinguished Names are used to identify entities, such as
2171 those that are named by the subject and issuer (signer) fields
2172 of X.509 certificates. The keytool command supports the follow‐
2173 ing subparts:
2174 · commonName: The common name of a person such as Susan Jones.
2176 · organizationUnit: The small organization (such as department
2178 or division) name. For example, Purchasing.
2179 · localityName: The locality (city) name, for example, Palo Al‐
2181 to.
2182 · stateName: State or province name, for example, California.
2184 · country: Two-letter country code, for example, CH.
2186 When you supply a distinguished name string as the value of a
2188 -dname option, such as for the -genkeypair command, the string
2189 must be in the following format:
2190 CN=cName, OU=orgUnit, O=org, L=city, S=state, C=coun‐
2192 tryCode
2193 All the following items represent actual values and the previous
2195 keywords are abbreviations for the following:
2196 CN=commonName
2198 OU=organizationUnit
2199 O=organizationName
2200 L=localityName
2201 S=stateName
2202 C=country
2203 A sample distinguished name string is:
2205 CN=Mark Smith, OU=Java, O=Oracle, L=Cupertino, S=Califor‐
2207 nia, C=US
2208 A sample command using such a string is:
2210 keytool -genkeypair -dname "CN=Mark Smith, OU=Java, O=Or‐
2212 acle, L=Cupertino, S=California, C=US" -alias mark
2213 Case doesn't matter for the keyword abbreviations. For example,
2215 CN, cn, and Cn are all treated the same.
2216 Order matters; each subcomponent must appear in the designated
2218 order. However, it isn't necessary to have all the subcompo‐
2219 nents. You can use a subset, for example:
2220 CN=Smith, OU=Java, O=Oracle, C=US
2222 If a distinguished name string value contains a comma, then the
2224 comma must be escaped by a backslash (\) character when you
2225 specify the string on a command line, as in:
2226 cn=Jack, ou=Java\, Product Development, o=Oracle, c=US
2228 It is never necessary to specify a distinguished name string on
2230 a command line. When the distinguished name is needed for a
2231 command, but not supplied on the command line, the user is
2232 prompted for each of the subcomponents. In this case, a comma
2233 doesn't need to be escaped by a backslash (\).
2234
2237 Important: Be sure to check a certificate very carefully before import‐
2238 ing it as a trusted certificate.
2239 Windows Example:
2241 View the certificate first with the -printcert command or the -im‐
2243 portcert command without the -noprompt option. Ensure that the dis‐
2244 played certificate fingerprints match the expected ones. For example,
2245 suppose someone sends or emails you a certificate that you put it in a
2246 file named \tmp\cert. Before you consider adding the certificate to
2247 your list of trusted certificates, you can execute a -printcert command
2248 to view its fingerprints, as follows:
2249 keytool -printcert -file \tmp\cert
2251 Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
2252 Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
2253 Serial Number: 59092b34
2254 Valid from: Thu Jun 24 18:01:13 PDT 2016 until: Wed Jun 23 17:01:13 PST 2016
2255 Certificate Fingerprints:
2256 SHA-1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE
2258 SHA-256: 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90:
2259 17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4
2260 Oracle Solaris Example:
2262 View the certificate first with the -printcert command or the -im‐
2264 portcert command without the -noprompt option. Ensure that the dis‐
2265 played certificate fingerprints match the expected ones. For example,
2266 suppose someone sends or emails you a certificate that you put it in a
2267 file named /tmp/cert. Before you consider adding the certificate to
2268 your list of trusted certificates, you can execute a -printcert command
2269 to view its fingerprints, as follows:
2270 keytool -printcert -file /tmp/cert
2272 Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
2273 Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
2274 Serial Number: 59092b34
2275 Valid from: Thu Jun 24 18:01:13 PDT 2016 until: Wed Jun 23 17:01:13 PST 2016
2276 Certificate Fingerprints:
2277 SHA-1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE
2279 SHA-256: 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90:
2280 17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4
2281 Then call or otherwise contact the person who sent the certificate and
2283 compare the fingerprints that you see with the ones that they show.
2284 Only when the fingerprints are equal is it guaranteed that the certifi‐
2285 cate wasn't replaced in transit with somebody else's certificate such
2286 as an attacker's certificate. If such an attack took place, and you
2287 didn't check the certificate before you imported it, then you would be
2288 trusting anything the attacker signed, for example, a JAR file with ma‐
2289 licious class files inside.
2290 Note:
2292 It isn't required that you execute a -printcert command before import‐
2294 ing a certificate. This is because before you add a certificate to the
2295 list of trusted certificates in the keystore, the -importcert command
2296 prints out the certificate information and prompts you to verify it.
2297 You can then stop the import operation. However, you can do this only
2298 when you call the -importcert command without the -noprompt option. If
2299 the -noprompt option is specified, then there is no interaction with
2300 the user.
2301
2303 Most commands that operate on a keystore require the store password.
2304 Some commands require a private/secret key password. Passwords can be
2305 specified on the command line in the -storepass and -keypass options.
2306 However, a password shouldn't be specified on a command line or in a
2307 script unless it is for testing, or you are on a secure system. When
2308 you don't specify a required password option on a command line, you are
2309 prompted for it.
2310
2312 Internet X.509 Public Key Infrastructure Certificate and Certificate
2313 Revocation List (CRL) Profile [https://tools.ietf.org/rfc/rfc5280.txt]
2314 defined a profile on conforming X.509 certificates, which includes what
2315 values and value combinations are valid for certificate fields and ex‐
2316 tensions.
2317 The keytool command doesn't enforce all of these rules so it can gener‐
2319 ate certificates that don't conform to the standard, such as
2320 self-signed certificates that would be used for internal testing pur‐
2321 poses. Certificates that don't conform to the standard might be re‐
2322 jected by JRE or other applications. Users should ensure that they
2323 provide the correct options for -dname, -ext, and so on.
2324
2326 Before you add the certificate to the keystore, the keytool command
2327 verifies it by attempting to construct a chain of trust from that cer‐
2328 tificate to a self-signed certificate (belonging to a root CA), using
2329 trusted certificates that are already available in the keystore.
2330 If the -trustcacerts option was specified, then additional certificates
2332 are considered for the chain of trust, namely the certificates in a
2333 file named cacerts.
2334 If the keytool command fails to establish a trust path from the cer‐
2336 tificate to be imported up to a self-signed certificate (either from
2337 the keystore or the cacerts file), then the certificate information is
2338 printed, and the user is prompted to verify it by comparing the dis‐
2339 played certificate fingerprints with the fingerprints obtained from
2340 some other (trusted) source of information, which might be the certifi‐
2341 cate owner. Be very careful to ensure the certificate is valid before
2342 importing it as a trusted certificate. The user then has the option of
2343 stopping the import operation. If the -noprompt option is specified,
2344 then there is no interaction with the user.
2345
2347 When you import a certificate reply, the certificate reply is validated
2348 with trusted certificates from the keystore, and optionally, the cer‐
2349 tificates configured in the cacerts keystore file when the -trustcac‐
2350 erts option is specified.
2351 The methods of determining whether the certificate reply is trusted are
2353 as follows:
2354 · If the reply is a single X.509 certificate, then the keytool command
2356 attempts to establish a trust chain, starting at the certificate re‐
2357 ply and ending at a self-signed certificate (belonging to a root CA).
2358 The certificate reply and the hierarchy of certificates is used to
2359 authenticate the certificate reply from the new certificate chain of
2360 aliases. If a trust chain can't be established, then the certificate
2361 reply isn't imported. In this case, the keytool command doesn't
2362 print the certificate and prompt the user to verify it, because it is
2363 very difficult for a user to determine the authenticity of the cer‐
2364 tificate reply.
2365 · If the reply is a PKCS #7 formatted certificate chain or a sequence
2367 of X.509 certificates, then the chain is ordered with the user cer‐
2368 tificate first followed by zero or more CA certificates. If the
2369 chain ends with a self-signed root CA certificate and the-trustcac‐
2370 erts option was specified, the keytool command attempts to match it
2371 with any of the trusted certificates in the keystore or the cacerts
2372 keystore file. If the chain doesn't end with a self-signed root CA
2373 certificate and the -trustcacerts option was specified, the keytool
2374 command tries to find one from the trusted certificates in the key‐
2375 store or the cacerts keystore file and add it to the end of the
2376 chain. If the certificate isn't found and the -noprompt option isn't
2377 specified, the information of the last certificate in the chain is
2378 printed, and the user is prompted to verify it.
2379 If the public key in the certificate reply matches the user's public
2381 key already stored with alias, then the old certificate chain is re‐
2382 placed with the new certificate chain in the reply. The old chain can
2383 only be replaced with a valid keypass, and so the password used to pro‐
2384 tect the private key of the entry is supplied. If no password is pro‐
2385 vided, and the private key password is different from the keystore
2386 password, the user is prompted for it.
2387 This command was named -import in earlier releases. This old name is
2389 still supported in this release. The new name, -importcert, is pre‐
2390 ferred.
2391JDK 13 2019 KEYTOOL(1)