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 The keytool command uses the jdk.certpath.disabledAlgorithms and
78 jdk.security.legacyAlgorithms security properties to determine which
79 algorithms are considered a security risk. It emits warnings when dis‐
80 abled or legacy algorithms are being used. The jdk.certpath.dis‐
81 abledAlgorithms and jdk.security.legacyAlgorithms security properties
82 are defined in the java.security file (located in the JDK's $JA‐
83 VA_HOME/conf/security directory).
84
86 The following notes apply to the descriptions in Commands and Options:
87 • All command and option names are preceded by a hyphen sign (-).
89 • Only one command can be provided.
91 • Options for each command can be provided in any order.
93 • There are two kinds of options, one is single-valued which should be
95 only provided once. If a single-valued option is provided multiple
96 times, the value of the last one is used. The other type is mul‐
97 ti-valued, which can be provided multiple times and all values are
98 used. The only multi-valued option currently supported is the -ext
99 option used to generate X.509v3 certificate extensions.
100 • All items not italicized or in braces ({ }) or brackets ([ ]) are re‐
102 quired to appear as is.
103 • Braces surrounding an option signify that a default value is used
105 when the option isn't specified on the command line. Braces are also
106 used around the -v, -rfc, and -J options, which have meaning only
107 when they appear on the command line. They don't have any default
108 values.
109 • Brackets surrounding an option signify that the user is prompted for
111 the values when the option isn't specified on the command line. For
112 the -keypass option, if you don't specify the option on the command
113 line, then the keytool command first attempts to use the keystore
114 password to recover the private/secret key. If this attempt fails,
115 then the keytool command prompts you for the private/secret key pass‐
116 word.
117 • Items in italics (option values) represent the actual values that
119 must be supplied. For example, here is the format of the -printcert
120 command:
121 keytool -printcert {-file cert_file} {-v}
123 When you specify a -printcert command, replace cert_file with the ac‐
125 tual file name, as follows: keytool -printcert -file VScert.cer
126 • Option values must be enclosed in quotation marks when they contain a
128 blank (space).
129
131 The keytool commands and their options can be grouped by the tasks that
132 they perform.
133 Commands for Creating or Adding Data to the Keystore:
135 • -gencert
137 • -genkeypair
139 • -genseckey
141 • -importcert
143 • -importpass
145 Commands for Importing Contents from Another Keystore:
147 • -importkeystore
149 Commands for Generating a Certificate Request:
151 • -certreq
153 Commands for Exporting Data:
155 • -exportcert
157 Commands for Displaying Data:
159 • -list
161 • -printcert
163 • -printcertreq
165 • -printcrl
167 Commands for Managing the Keystore:
169 • -storepasswd
171 • -keypasswd
173 • -delete
175 • -changealias
177 Commands for Displaying Security-related Information:
179 • -showinfo
181
183 -gencert
184 The following are the available options for the -gencert com‐
185 mand:
186 • {-rfc}: Output in RFC (Request For Comment) style
188 • {-infile infile}: Input file name
190 • {-outfile outfile}: Output file name
192 • {-alias alias}: Alias name of the entry to process
194 • {-sigalg sigalg}: Signature algorithm name
196 • {-dname dname}: Distinguished name
198 • {-startdate startdate}: Certificate validity start date and
200 time
201 • {-ext ext}*: X.509 extension
203 • {-validity days}: Validity number of days
205 • [-keypass arg]: Key password
207 • {-keystore keystore}: Keystore name
209 • [-storepass arg]: Keystore password
211 • {-storetype type}: Keystore type
213 • {-providername name}: Provider name
215 • {-addprovider name [-providerarg arg]}: Adds a security
217 provider by name (such as SunPKCS11) with an optional config‐
218 ure argument. The value of the security provider is the name
219 of a security provider that is defined in a module.
220 For example,
222 keytool -addprovider SunPKCS11 -provider‐
224 arg some.cfg ...
225 Note:
227 For compatibility reasons, the SunPKCS11 provider can still be
229 loaded with -providerclass sun.security.pkcs11.SunPKCS11 even
230 if it is now defined in a module. This is the only module in‐
231 cluded in the JDK that needs a configuration, and therefore
232 the most widely used with the -providerclass option. For
233 legacy security providers located on classpath and loaded by
234 reflection, -providerclass should still be used.
235 • {-providerclass class [-providerarg arg]}: Add security
237 provider by fully qualified class name with an optional con‐
238 figure argument.
239 For example, if MyProvider is a legacy provider loaded via re‐
241 flection,
242 keytool -providerclass com.example.MyProvider ...
244 • {-providerpath list}: Provider classpath
246 • {-v}: Verbose output
248 • {-protected}: Password provided through a protected mechanism
250 Use the -gencert command to generate a certificate as a response
252 to a certificate request file (which can be created by the key‐
253 tool -certreq command). The command reads the request either
254 from infile or, if omitted, from the standard input, signs it by
255 using the alias's private key, and outputs the X.509 certificate
256 into either outfile or, if omitted, to the standard output.
257 When -rfc is specified, the output format is Base64-encoded PEM;
258 otherwise, a binary DER is created.
259 The -sigalg value specifies the algorithm that should be used to
261 sign the certificate. The startdate argument is the start time
262 and date that the certificate is valid. The days argument tells
263 the number of days for which the certificate should be consid‐
264 ered valid.
265 When dname is provided, it is used as the subject of the gener‐
267 ated certificate. Otherwise, the one from the certificate re‐
268 quest is used.
269 The -ext value shows what X.509 extensions will be embedded in
271 the certificate. Read Common Command Options for the grammar of
272 -ext.
273 The -gencert option enables you to create certificate chains.
275 The following example creates a certificate, e1, that contains
276 three certificates in its certificate chain.
277 The following commands creates four key pairs named ca, ca1,
279 ca2, and e1:
280 keytool -alias ca -dname CN=CA -genkeypair -keyalg rsa
282 keytool -alias ca1 -dname CN=CA -genkeypair -keyalg rsa
283 keytool -alias ca2 -dname CN=CA -genkeypair -keyalg rsa
284 keytool -alias e1 -dname CN=E1 -genkeypair -keyalg rsa
285 The following two commands create a chain of signed certifi‐
287 cates; ca signs ca1 and ca1 signs ca2, all of which are self-is‐
288 sued:
289 keytool -alias ca1 -certreq |
291 keytool -alias ca -gencert -ext san=dns:ca1 |
292 keytool -alias ca1 -importcert
293 keytool -alias ca2 -certreq |
295 keytool -alias ca1 -gencert -ext san=dns:ca2 |
296 keytool -alias ca2 -importcert
297 The following command creates the certificate e1 and stores it
299 in the e1.cert file, which is signed by ca2. As a result, e1
300 should contain ca, ca1, and ca2 in its certificate chain:
301 keytool -alias e1 -certreq | key‐
303 tool -alias ca2 -gencert > e1.cert
304 -genkeypair
306 The following are the available options for the -genkeypair com‐
307 mand:
308 • {-alias alias}: Alias name of the entry to process
310 • -keyalg alg: Key algorithm name
312 • {-keysize size}: Key bit size
314 • {-groupname name}: Group name. For example, an Elliptic Curve
316 name.
317 • {-sigalg alg}: Signature algorithm name
319 • {-signer alias}: Signer alias
321 • [-signerkeypass arg]: Signer key password
323 • [-dname name]: Distinguished name
325 • {-startdate date}: Certificate validity start date and time
327 • {-ext value}*: X.509 extension
329 • {-validity days}: Validity number of days
331 • [-keypass arg]: Key password
333 • {-keystore keystore}: Keystore name
335 • [-storepass arg]: Keystore password
337 • {-storetype type}: Keystore type
339 • {-providername name}: Provider name
341 • {-addprovider name [-providerarg arg]}: Add security provider
343 by name (such as SunPKCS11) with an optional configure argu‐
344 ment.
345 • {-providerclass class [-providerarg arg] }: Add security
347 provider by fully qualified class name with an optional con‐
348 figure argument.
349 • {-providerpath list}: Provider classpath
351 • {-v}: Verbose output
353 • {-protected}: Password provided through a protected mechanism
355 Use the -genkeypair command to generate a key pair (a public key
357 and associated private key). When the -signer option is not
358 specified, the public key is wrapped in an X.509 v3 self-signed
359 certificate and stored as a single-element certificate chain.
360 When the -signer option is specified, a new certificate is gen‐
361 erated and signed by the designated signer and stored as a mul‐
362 tiple-element certificate chain (containing the generated cer‐
363 tificate itself, and the signer???s certificate chain). The
364 certificate chain and private key are stored in a new keystore
365 entry that is identified by its alias.
366 The -keyalg value specifies the algorithm to be used to generate
368 the key pair, and the -keysize value specifies the size of each
369 key to be generated. The -sigalg value specifies the algorithm
370 that should be used to sign the certificate. This algorithm
371 must be compatible with the -keyalg value.
372 The -groupname value specifies the named group (for example, the
374 standard or predefined name of an Elliptic Curve) of the key to
375 be generated. Only one of -groupname and -keysize can be speci‐
376 fied.
377 The -signer value specifies the alias of a PrivateKeyEntry for
379 the signer that already exists in the keystore. This option is
380 used to sign the certificate with the signer???s private key.
381 This is especially useful for key agreement algorithms (i.e.
382 the -keyalg value is XDH, X25519, X448, or DH) as these keys
383 cannot be used for digital signatures, and therefore a
384 self-signed certificate cannot be created.
385 The -signerkeypass value specifies the password of the sign‐
387 er???s private key. It can be specified if the private key of
388 the signer entry is protected by a password different from the
389 store password.
390 The -dname value specifies the X.500 Distinguished Name to be
392 associated with the value of -alias. If the -signer option is
393 not specified, the issuer and subject fields of the self-signed
394 certificate are populated with the specified distinguished name.
395 If the -signer option is specified, the subject field of the
396 certificate is populated with the specified distinguished name
397 and the issuer field is populated with the subject field of the
398 signer's certificate. If a distinguished name is not provided
399 at the command line, then the user is prompted for one.
400 The value of -keypass is a password used to protect the private
402 key of the generated key pair. If a password is not provided,
403 then the user is prompted for it. If you press the Return key
404 at the prompt, then the key password is set to the same password
405 as the keystore password. The -keypass value must have at least
406 six characters.
407 The value of -startdate specifies the issue time of the certifi‐
409 cate, also known as the "Not Before" value of the X.509 certifi‐
410 cate's Validity field.
411 The option value can be set in one of these two forms:
413 ([+-]nnn[ymdHMS])+
415 [yyyy/mm/dd] [HH:MM:SS]
417 With the first form, the issue time is shifted by the specified
419 value from the current time. The value is a concatenation of a
420 sequence of subvalues. Inside each subvalue, the plus sign (+)
421 means shift forward, and the minus sign (-) means shift back‐
422 ward. The time to be shifted is nnn units of years, months,
423 days, hours, minutes, or seconds (denoted by a single character
424 of y, m, d, H, M, or S respectively). The exact value of the
425 issue time is calculated by using the java.util.GregorianCalen‐
426 dar.add(int field, int amount) method on each subvalue, from
427 left to right. For example, the issue time can be specified by:
428 Calendar c = new GregorianCalendar();
430 c.add(Calendar.YEAR, -1);
431 c.add(Calendar.MONTH, 1);
432 c.add(Calendar.DATE, -1);
433 return c.getTime()
434 With the second form, the user sets the exact issue time in two
436 parts, year/month/day and hour:minute:second (using the local
437 time zone). The user can provide only one part, which means the
438 other part is the same as the current date (or time). The user
439 must provide the exact number of digits shown in the format def‐
440 inition (padding with 0 when shorter). When both date and time
441 are provided, there is one (and only one) space character be‐
442 tween the two parts. The hour should always be provided in
443 24-hour format.
444 When the option isn't provided, the start date is the current
446 time. The option can only be provided one time.
447 The value of date specifies the number of days (starting at the
449 date specified by -startdate, or the current date when -start‐
450 date isn't specified) for which the certificate should be con‐
451 sidered valid.
452 -genseckey
454 The following are the available options for the -genseckey com‐
455 mand:
456 • {-alias alias}: Alias name of the entry to process
458 • [-keypass arg]: Key password
460 • -keyalg alg: Key algorithm name
462 • {-keysize size}: Key bit size
464 • {-keystore keystore}: Keystore name
466 • [-storepass arg]: Keystore password
468 • {-storetype type}: Keystore type
470 • {-providername name}: Provider name
472 • {-addprovider name [-providerarg arg]}: Add security provider
474 by name (such as SunPKCS11) with an optional configure argu‐
475 ment.
476 • {-providerclass class [-providerarg arg]}: Add security
478 provider by fully qualified class name with an optional con‐
479 figure argument.
480 • {-providerpath list}: Provider classpath
482 • {-v}: Verbose output
484 • {-protected}: Password provided through a protected mechanism
486 Use the -genseckey command to generate a secret key and store it
488 in a new KeyStore.SecretKeyEntry identified by alias.
489 The value of -keyalg specifies the algorithm to be used to gen‐
491 erate the secret key, and the value of -keysize specifies the
492 size of the key that is generated. The -keypass value is a
493 password that protects the secret key. If a password is not
494 provided, then the user is prompted for it. If you press the
495 Return key at the prompt, then the key password is set to the
496 same password that is used for the -keystore. The -keypass val‐
497 ue must contain at least six characters.
498 -importcert
500 The following are the available options for the -importcert com‐
501 mand:
502 • {-noprompt}: Do not prompt
504 • {-trustcacerts}: Trust certificates from cacerts
506 • {-protected}: Password is provided through protected mechanism
508 • {-alias alias}: Alias name of the entry to process
510 • {-file file}: Input file name
512 • [-keypass arg]: Key password
514 • {-keystore keystore}: Keystore name
516 • {-cacerts}: Access the cacerts keystore
518 • [-storepass arg]: Keystore password
520 • {-storetype type}: Keystore type
522 • {-providername name}: Provider name
524 • {-addprovider name [-providerarg arg]}: Add security provider
526 by name (such as SunPKCS11) with an optional configure argu‐
527 ment.
528 • {-providerclass class [-providerarg arg]}: Add security
530 provider by fully qualified class name with an optional con‐
531 figure argument.
532 • {-providerpath list}: Provider classpath
534 • {-v}: Verbose output
536 Use the -importcert command to read the certificate or certifi‐
538 cate chain (where the latter is supplied in a PKCS#7 formatted
539 reply or in a sequence of X.509 certificates) from -file file,
540 and store it in the keystore entry identified by -alias. If
541 -file file is not specified, then the certificate or certificate
542 chain is read from stdin.
543 The keytool command can import X.509 v1, v2, and v3 certifi‐
545 cates, and PKCS#7 formatted certificate chains consisting of
546 certificates of that type. The data to be imported must be pro‐
547 vided either in binary encoding format or in printable encoding
548 format (also known as Base64 encoding) as defined by the Inter‐
549 net RFC 1421 standard. In the latter case, the encoding must be
550 bounded at the beginning by a string that starts with -----BE‐
551 GIN, and bounded at the end by a string that starts with
552 -----END.
553 You import a certificate for two reasons: To add it to the list
555 of trusted certificates, and to import a certificate reply re‐
556 ceived from a certificate authority (CA) as the result of sub‐
557 mitting a Certificate Signing Request (CSR) to that CA. See the
558 -certreq command in Commands for Generating a Certificate Re‐
559 quest.
560 The type of import is indicated by the value of the -alias op‐
562 tion. If the alias doesn't point to a key entry, then the key‐
563 tool command assumes you are adding a trusted certificate entry.
564 In this case, the alias shouldn't already exist in the keystore.
565 If the alias does exist, then the keytool command outputs an er‐
566 ror because a trusted certificate already exists for that alias,
567 and doesn't import the certificate. If -alias points to a key
568 entry, then the keytool command assumes that you're importing a
569 certificate reply.
570 -importpass
572 The following are the available options for the -importpass com‐
573 mand:
574 • {-alias alias}: Alias name of the entry to process
576 • [-keypass arg]: Key password
578 • {-keyalg alg}: Key algorithm name
580 • {-keysize size}: Key bit size
582 • {-keystore keystore}: Keystore name
584 • [-storepass arg]: Keystore password
586 • {-storetype type}: Keystore type
588 • {-providername name}: Provider name
590 • {-addprovider name [-providerarg arg]}: Add security provider
592 by name (such as SunPKCS11) with an optional configure argu‐
593 ment.
594 • {-providerclass class [-providerarg arg]}: Add security
596 provider by fully qualified class name with an optional con‐
597 figure argument.
598 • {-providerpath list}: Provider classpath
600 • {-v}: Verbose output
602 • {-protected}: Password provided through a protected mechanism
604 Use the -importpass command to imports a passphrase and store it
606 in a new KeyStore.SecretKeyEntry identified by -alias. The
607 passphrase may be supplied via the standard input stream; other‐
608 wise the user is prompted for it. The -keypass option provides
609 a password to protect the imported passphrase. If a password is
610 not provided, then the user is prompted for it. If you press
611 the Return key at the prompt, then the key password is set to
612 the same password as that used for the keystore. The -keypass
613 value must contain at least six characters.
614
616 -importkeystore
617 The following are the available options for the -importkeystore
618 command:
619 • -srckeystore keystore: Source keystore name
621 • {-destkeystore keystore}: Destination keystore name
623 • {-srcstoretype type}: Source keystore type
625 • {-deststoretype type}: Destination keystore type
627 • [-srcstorepass arg]: Source keystore password
629 • [-deststorepass arg]: Destination keystore password
631 • {-srcprotected}: Source keystore password protected
633 • {-destprotected}: Destination keystore password protected
635 • {-srcprovidername name}: Source keystore provider name
637 • {-destprovidername name}: Destination keystore provider name
639 • {-srcalias alias}: Source alias
641 • {-destalias alias}: Destination alias
643 • [-srckeypass arg]: Source key password
645 • [-destkeypass arg]: Destination key password
647 • {-noprompt}: Do not prompt
649 • {-addprovider name [-providerarg arg]: Add security provider
651 by name (such as SunPKCS11) with an optional configure argu‐
652 ment.
653 • {-providerclass class [-providerarg arg]}: Add security
655 provider by fully qualified class name with an optional con‐
656 figure argument
657 • {-providerpath list}: Provider classpath
659 • {-v}: Verbose output
661 Note:
663 This is the first line of all options:
665 -srckeystore keystore -destkeystore keystore
667 Use the -importkeystore command to import a single entry or all
669 entries from a source keystore to a destination keystore.
670 Note:
672 If you do not specify -destkeystore when using the keytool -im‐
674 portkeystore command, then the default keystore used is
675 $HOME/.keystore.
676 When the -srcalias option is provided, the command imports the
678 single entry identified by the alias to the destination key‐
679 store. If a destination alias isn't provided with -destalias,
680 then -srcalias is used as the destination alias. If the source
681 entry is protected by a password, then -srckeypass is used to
682 recover the entry. If -srckeypass isn't provided, then the key‐
683 tool command attempts to use -srcstorepass to recover the entry.
684 If -srcstorepass is not provided or is incorrect, then the user
685 is prompted for a password. The destination entry is protected
686 with -destkeypass. If -destkeypass isn't provided, then the
687 destination entry is protected with the source entry password.
688 For example, most third-party tools require storepass and key‐
689 pass in a PKCS #12 keystore to be the same. To create a PKCS#12
690 keystore for these tools, always specify a -destkeypass that is
691 the same as -deststorepass.
692 If the -srcalias option isn't provided, then all entries in the
694 source keystore are imported into the destination keystore.
695 Each destination entry is stored under the alias from the source
696 entry. If the source entry is protected by a password, then
697 -srcstorepass is used to recover the entry. If -srcstorepass is
698 not provided or is incorrect, then the user is prompted for a
699 password. If a source keystore entry type isn't supported in
700 the destination keystore, or if an error occurs while storing an
701 entry into the destination keystore, then the user is prompted
702 either to skip the entry and continue or to quit. The destina‐
703 tion entry is protected with the source entry password.
704 If the destination alias already exists in the destination key‐
706 store, then the user is prompted either to overwrite the entry
707 or to create a new entry under a different alias name.
708 If the -noprompt option is provided, then the user isn't prompt‐
710 ed for a new destination alias. Existing entries are overwrit‐
711 ten with the destination alias name. Entries that can't be im‐
712 ported are skipped and a warning is displayed.
713
715 -certreq
716 The following are the available options for the -certreq com‐
717 mand:
718 • {-alias alias}: Alias name of the entry to process
720 • {-sigalg alg}: Signature algorithm name
722 • {-file file}: Output file name
724 • [ -keypass arg]: Key password
726 • {-keystore keystore}: Keystore name
728 • {-dname name}: Distinguished name
730 • {-ext value}: X.509 extension
732 • [-storepass arg]: Keystore password
734 • {-storetype type}: Keystore type
736 • {-providername name}: Provider name
738 • {-addprovider name [-providerarg arg]}: Add security provider
740 by name (such as SunPKCS11) with an optional configure argu‐
741 ment.
742 • {-providerclass class [-providerarg arg]}: Add security
744 provider by fully qualified class name with an optional con‐
745 figure argument.
746 • {-providerpath list}: Provider classpath
748 • {-v}: Verbose output
750 • {-protected}: Password provided through a protected mechanism
752 Use the -certreq command to generate a Certificate Signing Re‐
754 quest (CSR) using the PKCS #10 format.
755 A CSR is intended to be sent to a CA. The CA authenticates the
757 certificate requestor (usually offline) and returns a certifi‐
758 cate or certificate chain to replace the existing certificate
759 chain (initially a self-signed certificate) in the keystore.
760 The private key associated with alias is used to create the PKCS
762 #10 certificate request. To access the private key, the correct
763 password must be provided. If -keypass isn't provided at the
764 command line and is different from the password used to protect
765 the integrity of the keystore, then the user is prompted for it.
766 If -dname is provided, then it is used as the subject in the
767 CSR. Otherwise, the X.500 Distinguished Name associated with
768 alias is used.
769 The -sigalg value specifies the algorithm that should be used to
771 sign the CSR.
772 The CSR is stored in the -file file. If a file is not speci‐
774 fied, then the CSR is output to -stdout.
775 Use the -importcert command to import the response from the CA.
777
779 -exportcert
780 The following are the available options for the -exportcert com‐
781 mand:
782 • {-rfc}: Output in RFC style
784 • {-alias alias}: Alias name of the entry to process
786 • {-file file}: Output file name
788 • {-keystore keystore}: Keystore name
790 • {-cacerts}: Access the cacerts keystore
792 • [-storepass arg]: Keystore password
794 • {-storetype type}: Keystore type
796 • {-providername name}: Provider name
798 • {-addprovider name [-providerarg arg]}: Add security provider
800 by name (such as SunPKCS11) with an optional configure argu‐
801 ment.
802 • {-providerclass class [-providerarg arg] }: Add security
804 provider by fully qualified class name with an optional con‐
805 figure argument.
806 • {-providerpath list}: Provider classpath
808 • {-v}: Verbose output
810 • {-protected}: Password provided through a protected mechanism
812 Use the -exportcert command to read a certificate from the key‐
814 store that is associated with -alias alias and store it in the
815 -file file. When a file is not specified, the certificate is
816 output to stdout.
817 By default, the certificate is output in binary encoding. If
819 the -rfc option is specified, then the output in the printable
820 encoding format defined by the Internet RFC 1421 Certificate En‐
821 coding Standard.
822 If -alias refers to a trusted certificate, then that certificate
824 is output. Otherwise, -alias refers to a key entry with an as‐
825 sociated certificate chain. In that case, the first certificate
826 in the chain is returned. This certificate authenticates the
827 public key of the entity addressed by -alias.
828
830 -list The following are the available options for the -list command:
831 • {-rfc}: Output in RFC style
833 • {-alias alias}: Alias name of the entry to process
835 • {-keystore keystore}: Keystore name
837 • {-cacerts}: Access the cacerts keystore
839 • [-storepass arg]: Keystore password
841 • {-storetype type}: Keystore type
843 • {-providername name}: Provider name
845 • {-addprovider name [-providerarg arg]}: Add security provider
847 by name (such as SunPKCS11) with an optional configure argu‐
848 ment.
849 • {-providerclass class [-providerarg arg] }: Add security
851 provider by fully qualified class name with an optional con‐
852 figure argument.
853 • {-providerpath list}: Provider classpath
855 • {-v}: Verbose output
857 • {-protected}: Password provided through a protected mechanism
859 Use the -list command to print the contents of the keystore en‐
861 try identified by -alias to stdout. If -alias alias is not
862 specified, then the contents of the entire keystore are printed.
863 By default, this command prints the SHA-256 fingerprint of a
865 certificate. If the -v option is specified, then the certifi‐
866 cate is printed in human-readable format, with additional infor‐
867 mation such as the owner, issuer, serial number, and any exten‐
868 sions. If the -rfc option is specified, then the certificate
869 contents are printed by using the printable encoding format, as
870 defined by the Internet RFC 1421 Certificate Encoding Standard.
871 Note:
873 You can't specify both -v and -rfc in the same command. Other‐
875 wise, an error is reported.
876 -printcert
878 The following are the available options for the -printcert com‐
879 mand:
880 • {-rfc}: Output in RFC style
882 • {-file cert_file}: Input file name
884 • {-sslserver server[:port]}:: Secure Sockets Layer (SSL) server
886 host and port
887 • {-jarfile JAR_file}: Signed .jar file
889 • {-keystore keystore}: Keystore name
891 • {-trustcacerts}: Trust certificates from cacerts
893 • [-storepass arg]: Keystore password
895 • {-storetype type}: Keystore type
897 • {-providername name}: Provider name
899 • {-addprovider name [-providerarg arg]}: Add security provider
901 by name (such as SunPKCS11) with an optional configure argu‐
902 ment.
903 • {-providerclass class [-providerarg arg]}: Add security
905 provider by fully qualified class name with an optional con‐
906 figure argument.
907 • {-providerpath list}: Provider classpath
909 • {-protected}: Password is provided through protected mechanism
911 • {-v}: Verbose output
913 Use the -printcert command to read and print the certificate
915 from -file cert_file, the SSL server located at -sslserver serv‐
916 er[:port], or the signed JAR file specified by -jarfile
917 JAR_file. It prints its contents in a human-readable format.
918 When a port is not specified, the standard HTTPS port 443 is as‐
919 sumed.
920 Note:
922 The -sslserver and -file options can't be provided in the same
924 command. Otherwise, an error is reported. If you don't specify
925 either option, then the certificate is read from stdin.
926 When-rfc is specified, the keytool command prints the certifi‐
928 cate in PEM mode as defined by the Internet RFC 1421 Certificate
929 Encoding standard.
930 If the certificate is read from a file or stdin, then it might
932 be either binary encoded or in printable encoding format, as de‐
933 fined by the RFC 1421 Certificate Encoding standard.
934 If the SSL server is behind a firewall, then the -J-Dhttps.prox‐
936 yHost=proxyhost and -J-Dhttps.proxyPort=proxyport options can be
937 specified on the command line for proxy tunneling.
938 Note:
940 This command can be used independently of a keystore. This com‐
942 mand does not check for the weakness of a certificate's signa‐
943 ture algorithm if it is a trusted certificate in the user key‐
944 store (specified by -keystore) or in the cacerts keystore (if
945 -trustcacerts is specified).
946 -printcertreq
948 The following are the available options for the -printcertreq
949 command:
950 • {-file file}: Input file name
952 • {-v}: Verbose output
954 Use the -printcertreq command to print the contents of a PKCS
956 #10 format certificate request, which can be generated by the
957 keytool -certreq command. The command reads the request from
958 file. If there is no file, then the request is read from the
959 standard input.
960 -printcrl
962 The following are the available options for the -printcrl com‐
963 mand:
964 • {-file crl}: Input file name
966 • {-keystore keystore}: Keystore name
968 • {-trustcacerts}: Trust certificates from cacerts
970 • [-storepass arg]: Keystore password
972 • {-storetype type}: Keystore type
974 • {-providername name}: Provider name
976 • {-addprovider name [-providerarg arg]}: Add security provider
978 by name (such as SunPKCS11) with an optional configure argu‐
979 ment.
980 • {-providerclass class [-providerarg arg]}: Add security
982 provider by fully qualified class name with an optional con‐
983 figure argument.
984 • {-providerpath list}: Provider classpath
986 • {-protected}: Password is provided through protected mechanism
988 • {-v}: Verbose output
990 Use the -printcrl command to read the Certificate Revocation
992 List (CRL) from -file crl . A CRL is a list of the digital cer‐
993 tificates that were revoked by the CA that issued them. The CA
994 generates the crl file.
995 Note:
997 This command can be used independently of a keystore. This com‐
999 mand attempts to verify the CRL using a certificate from the us‐
1000 er keystore (specified by -keystore) or the cacerts keystore (if
1001 -trustcacerts is specified), and will print out a warning if it
1002 cannot be verified.
1003
1005 -storepasswd
1006 The following are the available options for the -storepasswd
1007 command:
1008 • [-new arg]: New password
1010 • {-keystore keystore}: Keystore name
1012 • {-cacerts}: Access the cacerts keystore
1014 • [-storepass arg]: Keystore password
1016 • {-storetype type}: Keystore type
1018 • {-providername name}: Provider name
1020 • {-addprovider name [-providerarg arg]}: Add security provider
1022 by name (such as SunPKCS11) with an optional configure argu‐
1023 ment.
1024 • {-providerclass class [-providerarg arg]}: Add security
1026 provider by fully qualified class name with an optional con‐
1027 figure argument.
1028 • {-providerpath list}: Provider classpath
1030 • {-v}: Verbose output
1032 Use the -storepasswd command to change the password used to pro‐
1034 tect the integrity of the keystore contents. The new password
1035 is set by -new arg and must contain at least six characters.
1036 -keypasswd
1038 The following are the available options for the -keypasswd com‐
1039 mand:
1040 • {-alias alias}: Alias name of the entry to process
1042 • [-keypass old_keypass]: Key password
1044 • [-new new_keypass]: New password
1046 • {-keystore keystore}: Keystore name
1048 • {-storepass arg}: Keystore password
1050 • {-storetype type}: Keystore type
1052 • {-providername name}: Provider name
1054 • {-addprovider name [-providerarg arg]}: Add security provider
1056 by name (such as SunPKCS11) with an optional configure argu‐
1057 ment.
1058 • {-providerclass class [-providerarg arg]}: Add security
1060 provider by fully qualified class name with an optional con‐
1061 figure argument.
1062 • {-providerpath list}: Provider classpath
1064 • {-v}: Verbose output
1066 Use the -keypasswd command to change the password (under which
1068 private/secret keys identified by -alias are protected) from
1069 -keypass old_keypass to -new new_keypass. The password value
1070 must contain at least six characters.
1071 If the -keypass option isn't provided at the command line and
1073 the -keypass password is different from the keystore password
1074 (-storepass arg), then the user is prompted for it.
1075 If the -new option isn't provided at the command line, then the
1077 user is prompted for it.
1078 -delete
1080 The following are the available options for the -delete command:
1081 • [-alias alias]: Alias name of the entry to process
1083 • {-keystore keystore}: Keystore name
1085 • {-cacerts}: Access the cacerts keystore
1087 • [-storepass arg]: Keystore password
1089 • {-storetype type}: Keystore type
1091 • {-providername name}: Provider name
1093 • {-addprovider name [-providerarg arg]}: Add security provider
1095 by name (such as SunPKCS11) with an optional configure argu‐
1096 ment.
1097 • {-providerclass class [-providerarg arg]}: Add security
1099 provider by fully qualified class name with an optional con‐
1100 figure argument.
1101 • {-providerpath list}: Provider classpath
1103 • {-v}: Verbose output
1105 • {-protected}: Password provided through a protected mechanism
1107 Use the -delete command to delete the -alias alias entry from
1109 the keystore. When not provided at the command line, the user
1110 is prompted for the alias.
1111 -changealias
1113 The following are the available options for the -changealias
1114 command:
1115 • {-alias alias}: Alias name of the entry to process
1117 • [-destalias alias]: Destination alias
1119 • [-keypass arg]: Key password
1121 • {-keystore keystore}: Keystore name
1123 • {-cacerts}: Access the cacerts keystore
1125 • [-storepass arg]: Keystore password
1127 • {-storetype type}: Keystore type
1129 • {-providername name}: Provider name
1131 • {-addprovider name [-providerarg arg]}: Add security provider
1133 by name (such as SunPKCS11) with an optional configure argu‐
1134 ment.
1135 • {-providerclass class [-providerarg arg]}: Add security
1137 provider by fully qualified class name with an optional con‐
1138 figure argument.
1139 • {-providerpath list}: Provider classpath
1141 • {-v}: Verbose output
1143 • {-protected}: Password provided through a protected mechanism
1145 Use the -changealias command to move an existing keystore entry
1147 from -alias alias to a new -destalias alias. If a destination
1148 alias is not provided, then the command prompts you for one. If
1149 the original entry is protected with an entry password, then the
1150 password can be supplied with the -keypass option. If a key
1151 password is not provided, then the -storepass (if provided) is
1152 attempted first. If the attempt fails, then the user is prompt‐
1153 ed for a password.
1154
1156 -showinfo
1157 The following are the available options for the -showinfo com‐
1158 mand:
1159 • {-tls}: Displays TLS configuration information
1161 • {-v}: Verbose output
1163 Use the -showinfo command to display various security-related
1165 information. The -tls option displays TLS configurations, such
1166 as the list of enabled protocols and cipher suites.
1167
1169 You can use --help to display a list of keytool commands or to display
1170 help information about a specific keytool command.
1171 • To display a list of keytool commands, enter:
1173 keytool --help
1175 • To display help information about a specific keytool command, enter:
1177 keytool -<command> --help
1179
1181 The -v option can appear for all commands except --help. When the -v
1182 option appears, it signifies verbose mode, which means that more infor‐
1183 mation is provided in the output.
1184 The -Joption argument can appear for any command. When the -Joption is
1186 used, the specified option string is passed directly to the Java inter‐
1187 preter. This option doesn't contain any spaces. It's useful for ad‐
1188 justing the execution environment or memory usage. For a list of pos‐
1189 sible interpreter options, enter java -h or java -X at the command
1190 line.
1191 These options can appear for all commands operating on a keystore:
1193 -storetype storetype
1195 This qualifier specifies the type of keystore to be instantiat‐
1196 ed.
1197 -keystore keystore
1199 The keystore location.
1200 If the JKS storetype is used and a keystore file doesn't yet ex‐
1202 ist, then certain keytool commands can result in a new keystore
1203 file being created. For example, if keytool -genkeypair is
1204 called and the -keystore option isn't specified, the default
1205 keystore file named .keystore is created in the user's home di‐
1206 rectory if it doesn't already exist. Similarly, if the -key‐
1207 store ks_file option is specified but ks_file doesn't exist,
1208 then it is created. For more information on the JKS storetype,
1209 see the KeyStore Implementation section in KeyStore aliases.
1210 Note that the input stream from the -keystore option is passed
1212 to the KeyStore.load method. If NONE is specified as the URL,
1213 then a null stream is passed to the KeyStore.load method. NONE
1214 should be specified if the keystore isn't file-based. For exam‐
1215 ple, when the keystore resides on a hardware token device.
1216 -cacerts cacerts
1218 Operates on the cacerts keystore . This option is equivalent to
1219 -keystore path_to_cacerts -storetype type_of_cacerts. An error
1220 is reported if the -keystore or -storetype option is used with
1221 the -cacerts option.
1222 -storepass [:env | :file ] argument
1224 The password that is used to protect the integrity of the key‐
1225 store.
1226 If the modifier env or file isn't specified, then the password
1228 has the value argument, which must contain at least six charac‐
1229 ters. Otherwise, the password is retrieved as follows:
1230 • env: Retrieve the password from the environment variable named
1232 argument.
1233 • file: Retrieve the password from the file named argument.
1235 Note: All other options that require passwords, such as -key‐
1237 pass, -srckeypass, -destkeypass, -srcstorepass, and -dest‐
1238 storepass, accept the env and file modifiers. Remember to sepa‐
1239 rate the password option and the modifier with a colon (:).
1240 The password must be provided to all commands that access the
1242 keystore contents. For such commands, when the -storepass op‐
1243 tion isn't provided at the command line, the user is prompted
1244 for it.
1245 When retrieving information from the keystore, the password is
1247 optional. If a password is not specified, then the integrity of
1248 the retrieved information can't be verified and a warning is
1249 displayed.
1250 -providername name
1252 Used to identify a cryptographic service provider's name when
1253 listed in the security properties file.
1254 -addprovider name
1256 Used to add a security provider by name (such as SunPKCS11) .
1257 -providerclass class
1259 Used to specify the name of a cryptographic service provider's
1260 master class file when the service provider isn't listed in the
1261 security properties file.
1262 -providerpath list
1264 Used to specify the provider classpath.
1265 -providerarg arg
1267 Used with the -addprovider or -providerclass option to represent
1268 an optional string input argument for the constructor of class
1269 name.
1270 -protected=true|false
1272 Specify this value as true when a password must be specified by
1273 way of a protected authentication path, such as a dedicated PIN
1274 reader. Because there are two keystores involved in the -im‐
1275 portkeystore command, the following two options, -srcprotected
1276 and -destprotected, are provided for the source keystore and the
1277 destination keystore respectively.
1278 -ext {name{:critical} {=value}}
1280 Denotes an X.509 certificate extension. The option can be used
1281 in -genkeypair and -gencert to embed extensions into the gener‐
1282 ated certificate, or in -certreq to show what extensions are re‐
1283 quested in the certificate request. The option can appear mul‐
1284 tiple times. The name argument can be a supported extension
1285 name (see Supported Named Extensions) or an arbitrary OID num‐
1286 ber. The value argument, when provided, denotes the argument
1287 for the extension. When value is omitted, the default value of
1288 the extension or the extension itself requires no argument. The
1289 :critical modifier, when provided, means the extension's isCrit‐
1290 ical attribute is true; otherwise, it is false. You can use :c
1291 in place of :critical.
1292 -conf file
1294 Specifies a pre-configured options file.
1295
1297 A pre-configured options file is a Java properties file that can be
1298 specified with the -conf option. Each property represents the default
1299 option(s) for a keytool command using "keytool.command_name" as the
1300 property name. A special property named "keytool.all" represents the
1301 default option(s) applied to all commands. A property value can in‐
1302 clude ${prop} which will be expanded to the system property associated
1303 with it. If an option value includes white spaces inside, it should be
1304 surrounded by quotation marks (" or '). All property names must be in
1305 lower case.
1306 When keytool is launched with a pre-configured options file, the value
1308 for "keytool.all" (if it exists) is prepended to the keytool command
1309 line first, with the value for the command name (if it exists) comes
1310 next, and the existing options on the command line at last. For a sin‐
1311 gle-valued option, this allows the property for a specific command to
1312 override the "keytool.all" value, and the value specified on the com‐
1313 mand line to override both. For multiple-valued options, all of them
1314 will be used by keytool.
1315 For example, given the following file named preconfig:
1317 # A tiny pre-configured options file
1319 keytool.all = -keystore ${user.home}/ks
1320 keytool.list = -v
1321 keytool.genkeypair = -keyalg rsa
1322 keytool -conf preconfig -list is identical to
1324 keytool -keystore ~/ks -v -list
1326 keytool -conf preconfig -genkeypair -alias me is identical to
1328 keytool -keystore ~/ks -keyalg rsa -genkeypair -alias me
1330 keytool -conf preconfig -genkeypair -alias you -keyalg ec is identical
1332 to
1333 keytool -keystore ~/ks -keyalg rsa -genkey‐
1335 pair -alias you -keyalg ec
1336 which is equivalent to
1338 keytool -keystore ~/ks -genkeypair -alias you -keyalg ec
1340 because -keyalg is a single-valued option and the ec value specified on
1342 the command line overrides the preconfigured options file.
1343
1345 The following examples show the defaults for various option values:
1346 -alias "mykey"
1348 -keysize
1350 2048 (when using -genkeypair and -keyalg is "RSA", "DSA", "RSASSA-PSS", or "DH")
1351 256 (when using -genkeypair and -keyalg is "EC")
1352 255 (when using -genkeypair and -keyalg is "EdDSA", or "XDH)
1353 56 (when using -genseckey and -keyalg is "DES")
1354 168 (when using -genseckey and -keyalg is "DESede")
1355 -validity 90
1357 -keystore <the file named .keystore in the user's home directory>
1359 -destkeystore <the file named .keystore in the user's home directory>
1361 -storetype <the value of the "keystore.type" property in the
1363 security properties file, which is returned by the static
1364 getDefaultType method in java.security.KeyStore>
1365 -file
1367 stdin (if reading)
1368 stdout (if writing)
1369 -protected false
1371 When generating a certificate or a certificate request, the default
1373 signature algorithm (-sigalg option) is derived from the algorithm of
1374 the underlying private key to provide an appropriate level of security
1375 strength as follows:
1376 keyalg keysize default sigalg
1378 ────────────────────────────────────────────
1379 DSA any size SHA256withDSA
1380 RSA <= 3072 SHA256withRSA
1381 <= 7680 SHA384withRSA
1382 > 7680 SHA512withRSA
1383 EC < 384 SHA256withECDSA
1384 < 512 SHA384withECDSA
1385 = 512 SHA512withECDSA
1386 RSASSA-PSS <= 3072 RSASSA-PSS (with
1387 SHA-256)
1388 <= 7680 RSASSA-PSS (with
1389 SHA-384)
1390 > 7680 RSASSA-PSS (with
1391 SHA-512)
1392 EdDSA 255 Ed25519
1393 448 Ed448
1394 Ed25519 255 Ed25519
1395 Ed448 448 Ed448
1396 • An RSASSA-PSS signature algorithm uses a MessageDigest algorithm as
1398 its hash and MGF1 algorithms.
1399 • EdDSA supports 2 key sizes: Ed25519 and Ed448. When generating an
1401 EdDSA key pair using -keyalg EdDSA, a user can specify -keysize 255
1402 or -keysize 448 to generate Ed25519 or Ed448 key pairs. When no
1403 -keysize is specified, an Ed25519 key pair is generated. A user can
1404 also directly specify -keyalg Ed25519 or -keyalg Ed448 to generate a
1405 key pair with the expected key size.
1406 Note:
1408 To improve out of the box security, default key size and signature al‐
1410 gorithm names are periodically updated to stronger values with each re‐
1411 lease of the JDK. If interoperability with older releases of the JDK
1412 is important, make sure that the defaults are supported by those re‐
1413 leases. Alternatively, you can use the -keysize or -sigalg options to
1414 override the default values at your own risk.
1415
1417 The keytool command supports these named extensions. The names aren't
1418 case-sensitive.
1419 BC or BasicContraints
1421 Values:
1422 The full form is ca:{true|false}[,pathlen:len] or len, which is
1424 short for ca:true,pathlen:len.
1425 When len is omitted, the resulting value is ca:true.
1427 KU or KeyUsage
1429 Values:
1430 usage(, usage)*
1432 usage can be one of the following:
1434 • digitalSignature
1436 • nonRepudiation (contentCommitment)
1438 • keyEncipherment
1440 • dataEncipherment
1442 • keyAgreement
1444 • keyCertSign
1446 • cRLSign
1448 • encipherOnly
1450 • decipherOnly
1452 Provided there is no ambiguity, the usage argument can be abbre‐
1454 viated with the first few letters (such as dig for digitalSigna‐
1455 ture) or in camel-case style (such as dS for digitalSignature or
1456 cRLS for cRLSign). The usage values are case-sensitive.
1457 EKU or ExtendedKeyUsage
1459 Values:
1460 usage(, usage)*
1462 usage can be one of the following:
1464 • anyExtendedKeyUsage
1466 • serverAuth
1468 • clientAuth
1470 • codeSigning
1472 • emailProtection
1474 • timeStamping
1476 • OCSPSigning
1478 • Any OID string
1480 Provided there is no ambiguity, the usage argument can be abbre‐
1482 viated with the first few letters or in camel-case style. The
1483 usage values are case-sensitive.
1484 SAN or SubjectAlternativeName
1486 Values:
1487 type:value(, type:value)*
1489 type can be one of the following:
1491 • EMAIL
1493 • URI
1495 • DNS
1497 • IP
1499 • OID
1501 The value argument is the string format value for the type.
1503 IAN or IssuerAlternativeName
1505 Values:
1506 Same as SAN or SubjectAlternativeName.
1508 SIA or SubjectInfoAccess
1510 Values:
1511 method:location-type:location-value(, method:location-type:loca‐
1513 tion-value)*
1514 method can be one of the following:
1516 • timeStamping
1518 • caRepository
1520 • Any OID
1522 The location-type and location-value arguments can be any
1524 type:value supported by the SubjectAlternativeName extension.
1525 AIA or AuthorityInfoAccess
1527 Values:
1528 Same as SIA or SubjectInfoAccess.
1530 The method argument can be one of the following:
1532 • ocsp
1534 • caIssuers
1536 • Any OID
1538 When name is OID, the value is the hexadecimal dumped Definite Encoding
1540 Rules (DER) encoding of the extnValue for the extension excluding the
1541 OCTET STRING type and length bytes. Other than standard hexadecimal
1542 numbers (0-9, a-f, A-F), any extra characters are ignored in the HEX
1543 string. Therefore, both 01:02:03:04 and 01020304 are accepted as iden‐
1544 tical values. When there is no value, the extension has an empty value
1545 field.
1546 A special name honored, used only in -gencert, denotes how the exten‐
1548 sions included in the certificate request should be honored. The value
1549 for this name is a comma-separated list of all (all requested exten‐
1550 sions are honored), name{:[critical|non-critical]} (the named extension
1551 is honored, but it uses a different isCritical attribute), and -name
1552 (used with all, denotes an exception). Requested extensions aren't
1553 honored by default.
1554 If, besides the-ext honored option, another named or OID -ext option is
1556 provided, this extension is added to those already honored. However,
1557 if this name (or OID) also appears in the honored value, then its value
1558 and criticality override that in the request. If an extension of the
1559 same type is provided multiple times through either a name or an OID,
1560 only the last extension is used.
1561 The subjectKeyIdentifier extension is always created. For
1563 non-self-signed certificates, the authorityKeyIdentifier is created.
1564 CAUTION:
1566 Users should be aware that some combinations of extensions (and other
1568 certificate fields) may not conform to the Internet standard. See Cer‐
1569 tificate Conformance Warning.
1570
1572 The following examples describe the sequence actions in creating a key‐
1573 store for managing public/private key pairs and certificates from
1574 trusted entities.
1575 • Generating the Key Pair
1577 • Requesting a Signed Certificate from a CA
1579 • Importing a Certificate for the CA
1581 • Importing the Certificate Reply from the CA
1583 • Exporting a Certificate That Authenticates the Public Key
1585 • Importing the Keystore
1587 • Generating Certificates for an SSL Server
1589
1591 Create a keystore and then generate the key pair.
1592 You can enter the command as a single line such as the following:
1594 keytool -genkeypair -dname "cn=myname, ou=mygroup, o=mycompa‐
1596 ny, c=mycountry" -alias business -keyalg rsa -keypass password
1597 -keystore /working/mykeystore -storepass password -validity 180
1598 The command creates the keystore named mykeystore in the working direc‐
1600 tory (provided it doesn't already exist), and assigns it the password
1601 specified by -keypass. It generates a public/private key pair for the
1602 entity whose distinguished name is myname, mygroup, mycompany, and a
1603 two-letter country code of mycountry. It uses the RSA key generation
1604 algorithm to create the keys; both are 2048 bits
1605 The command uses the default SHA256withRSA signature algorithm to cre‐
1607 ate a self-signed certificate that includes the public key and the dis‐
1608 tinguished name information. The certificate is valid for 180 days,
1609 and is associated with the private key in a keystore entry referred to
1610 by -alias business. The private key is assigned the password specified
1611 by -keypass.
1612 The command is significantly shorter when the option defaults are ac‐
1614 cepted. In this case, only -keyalg is required, and the defaults are
1615 used for unspecified options that have default values. You are prompt‐
1616 ed for any required values. You could have the following:
1617 keytool -genkeypair -keyalg rsa
1619 In this case, a keystore entry with the alias mykey is created, with a
1621 newly generated key pair and a certificate that is valid for 90 days.
1622 This entry is placed in your home directory in a keystore named .key‐
1623 store . .keystore is created if it doesn't already exist. You are
1624 prompted for the distinguished name information, the keystore password,
1625 and the private key password.
1626 Note:
1628 The rest of the examples assume that you responded to the prompts with
1630 values equal to those specified in the first -genkeypair command. For
1631 example, a distinguished name of cn=myname, ou=mygroup, o=mycompa‐
1632 ny, c=mycountry).
1633
1635 Note:
1636 Generating the key pair created a self-signed certificate; however, a
1638 certificate is more likely to be trusted by others when it is signed by
1639 a CA.
1640 To get a CA signature, complete the following process:
1642 1. Generate a CSR:
1644 keytool -certreq -file myname.csr
1646 This creates a CSR for the entity identified by the default alias
1648 mykey and puts the request in the file named myname.csr.
1649 2. Submit myname.csr to a CA, such as DigiCert.
1651 The CA authenticates you, the requestor (usually offline), and returns
1653 a certificate, signed by them, authenticating your public key. In some
1654 cases, the CA returns a chain of certificates, each one authenticating
1655 the public key of the signer of the previous certificate in the chain.
1656
1658 To import a certificate for the CA, complete the following process:
1659 1. Before you import the certificate reply from a CA, you need one or
1661 more trusted certificates either in your keystore or in the cacerts
1662 keystore file. See -importcert in Commands.
1663 • If the certificate reply is a certificate chain, then you need
1665 the top certificate of the chain. The root CA certificate that
1666 authenticates the public key of the CA.
1667 • If the certificate reply is a single certificate, then you need a
1669 certificate for the issuing CA (the one that signed it). If that
1670 certificate isn't self-signed, then you need a certificate for
1671 its signer, and so on, up to a self-signed root CA certificate.
1672 The cacerts keystore ships with a set of root certificates issued
1674 by the CAs of the Oracle Java Root Certificate program
1675 [http://www.oracle.com/technetwork/java/javase/javasecarootcert‐
1676 sprogram-1876540.html]. If you request a signed certificate from a
1677 CA, and a certificate authenticating that CA's public key hasn't
1678 been added to cacerts, then you must import a certificate from that
1679 CA as a trusted certificate.
1680 A certificate from a CA is usually self-signed or signed by another
1682 CA. If it is signed by another CA, you need a certificate that au‐
1683 thenticates that CA's public key.
1684 For example, you have obtained a X.cer file from a company that is
1686 a CA and the file is supposed to be a self-signed certificate that
1687 authenticates that CA's public key. Before you import it as a
1688 trusted certificate, you should ensure that the certificate is
1689 valid by:
1690 1. Viewing it with the keytool -printcert command or the key‐
1692 tool -importcert command without using the -noprompt option.
1693 Make sure that the displayed certificate fingerprints match the
1694 expected fingerprints.
1695 2. Calling the person who sent the certificate, and comparing the
1697 fingerprints that you see with the ones that they show or that a
1698 secure public key repository shows.
1699 Only when the fingerprints are equal is it assured that the cer‐
1701 tificate wasn't replaced in transit with somebody else's certifi‐
1702 cate (such as an attacker's certificate). If such an attack takes
1703 place, and you didn't check the certificate before you imported it,
1704 then you would be trusting anything that the attacker signed.
1705 2. Replace the self-signed certificate with a certificate chain, where
1707 each certificate in the chain authenticates the public key of the
1708 signer of the previous certificate in the chain, up to a root CA.
1709 If you trust that the certificate is valid, then you can add it to
1711 your keystore by entering the following command:
1712 keytool -importcert -alias alias -file *X*.cer`
1714 This command creates a trusted certificate entry in the keystore
1716 from the data in the CA certificate file and assigns the values of
1717 the alias to the entry.
1718
1720 After you import a certificate that authenticates the public key of the
1721 CA that you submitted your certificate signing request to (or there is
1722 already such a certificate in the cacerts file), you can import the
1723 certificate reply and replace your self-signed certificate with a cer‐
1724 tificate chain.
1725 The certificate chain is one of the following:
1727 • Returned by the CA when the CA reply is a chain.
1729 • Constructed when the CA reply is a single certificate. This certifi‐
1731 cate chain is constructed by using the certificate reply and trusted
1732 certificates available either in the keystore where you import the
1733 reply or in the cacerts keystore file.
1734 For example, if you sent your certificate signing request to DigiCert,
1736 then you can import their reply by entering the following command:
1737 Note:
1739 In this example, the returned certificate is named DCmyname.cer.
1741 keytool -importcert -trustcacerts -file DCmyname.cer
1743
1745 Note:
1746 If you used the jarsigner command to sign a Java Archive (JAR) file,
1748 then clients that use the file will want to authenticate your signa‐
1749 ture.
1750 One way that clients can authenticate you is by importing your public
1752 key certificate into their keystore as a trusted entry. You can then
1753 export the certificate and supply it to your clients.
1754 For example:
1756 1. Copy your certificate to a file named myname.cer by entering the
1758 following command:
1759 Note:
1761 In this example, the entry has an alias of mykey.
1763 keytool -exportcert -alias mykey -file myname.cer
1765 2. With the certificate and the signed JAR file, a client can use the
1767 jarsigner command to authenticate your signature.
1768
1770 Use the importkeystore command to import an entire keystore into anoth‐
1771 er keystore. This imports all entries from the source keystore, in‐
1772 cluding keys and certificates, to the destination keystore with a sin‐
1773 gle command. You can use this command to import entries from a differ‐
1774 ent type of keystore. During the import, all new entries in the desti‐
1775 nation keystore will have the same alias names and protection passwords
1776 (for secret keys and private keys). If the keytool command can't re‐
1777 cover the private keys or secret keys from the source keystore, then it
1778 prompts you for a password. If it detects alias duplication, then it
1779 asks you for a new alias, and you can specify a new alias or simply al‐
1780 low the keytool command to overwrite the existing one.
1781 For example, import entries from a typical JKS type keystore key.jks
1783 into a PKCS #11 type hardware-based keystore, by entering the following
1784 command:
1785 keytool -importkeystore -srckeystore key.jks -destkey‐
1787 store NONE -srcstoretype JKS -deststoretype PKCS11 -srcstorepass
1788 password -deststorepass password
1789 The importkeystore command can also be used to import a single entry
1791 from a source keystore to a destination keystore. In this case, be‐
1792 sides the options you used in the previous example, you need to specify
1793 the alias you want to import. With the -srcalias option specified, you
1794 can also specify the destination alias name, protection password for a
1795 secret or private key, and the destination protection password you want
1796 as follows:
1797 keytool -importkeystore -srckeystore key.jks -destkey‐
1799 store NONE -srcstoretype JKS -deststoretype PKCS11 -srcstorepass
1800 password -deststorepass password -srcalias myprivatekey -destal‐
1801 ias myoldprivatekey -srckeypass password -destkeypass password
1802 -noprompt
1803
1805 The following are keytool commands used to generate key pairs and cer‐
1806 tificates for three entities:
1807 • Root CA (root)
1809 • Intermediate CA (ca)
1811 • SSL server (server)
1813 Ensure that you store all the certificates in the same keystore.
1815 keytool -genkeypair -keystore root.jks -alias root -ext bc:c -keyalg rsa
1817 keytool -genkeypair -keystore ca.jks -alias ca -ext bc:c -keyalg rsa
1818 keytool -genkeypair -keystore server.jks -alias server -keyalg rsa
1819 keytool -keystore root.jks -alias root -exportcert -rfc > root.pem
1821 keytool -storepass password -keystore ca.jks -certreq -alias ca |
1823 keytool -storepass password -keystore root.jks
1824 -gencert -alias root -ext BC=0 -rfc > ca.pem
1825 keytool -keystore ca.jks -importcert -alias ca -file ca.pem
1826 keytool -storepass password -keystore server.jks -certreq -alias server |
1828 keytool -storepass password -keystore ca.jks -gencert -alias ca
1829 -ext ku:c=dig,kE -rfc > server.pem
1830 cat root.pem ca.pem server.pem |
1831 keytool -keystore server.jks -importcert -alias server
1832
1834 Keystore
1835 A keystore is a storage facility for cryptographic keys and cer‐
1836 tificates.
1837 Keystore entries
1839 Keystores can have different types of entries. The two most ap‐
1840 plicable entry types for the keytool command include the follow‐
1841 ing:
1842 Key entries: Each entry holds very sensitive cryptographic key
1844 information, which is stored in a protected format to prevent
1845 unauthorized access. Typically, a key stored in this type of
1846 entry is a secret key, or a private key accompanied by the cer‐
1847 tificate chain for the corresponding public key. See Certifi‐
1848 cate Chains. The keytool command can handle both types of en‐
1849 tries, while the jarsigner tool only handles the latter type of
1850 entry, that is private keys and their associated certificate
1851 chains.
1852 Trusted certificate entries: Each entry contains a single public
1854 key certificate that belongs to another party. The entry is
1855 called a trusted certificate because the keystore owner trusts
1856 that the public key in the certificate belongs to the identity
1857 identified by the subject (owner) of the certificate. The is‐
1858 suer of the certificate vouches for this, by signing the cer‐
1859 tificate.
1860 Keystore aliases
1862 All keystore entries (key and trusted certificate entries) are
1863 accessed by way of unique aliases.
1864 An alias is specified when you add an entity to the keystore
1866 with the -genseckey command to generate a secret key, the
1867 -genkeypair command to generate a key pair (public and private
1868 key), or the -importcert command to add a certificate or cer‐
1869 tificate chain to the list of trusted certificates. Subsequent
1870 keytool commands must use this same alias to refer to the enti‐
1871 ty.
1872 For example, you can use the alias duke to generate a new pub‐
1874 lic/private key pair and wrap the public key into a self-signed
1875 certificate with the following command. See Certificate Chains.
1876 keytool -genkeypair -alias duke -keyalg rsa -keypass
1878 passwd
1879 This example specifies an initial passwd required by subsequent
1881 commands to access the private key associated with the alias
1882 duke. If you later want to change Duke's private key password,
1883 use a command such as the following:
1884 keytool -keypasswd -alias duke -keypass passwd -new new‐
1886 passwd
1887 This changes the initial passwd to newpasswd. A password
1889 shouldn't be specified on a command line or in a script unless
1890 it is for testing purposes, or you are on a secure system. If
1891 you don't specify a required password option on a command line,
1892 then you are prompted for it.
1893 Keystore implementation
1895 The KeyStore class provided in the java.security package sup‐
1896 plies well-defined interfaces to access and modify the informa‐
1897 tion in a keystore. It is possible for there to be multiple
1898 different concrete implementations, where each implementation is
1899 that for a particular type of keystore.
1900 Currently, two command-line tools (keytool and jarsigner) make
1902 use of keystore implementations. Because the KeyStore class is
1903 public, users can write additional security applications that
1904 use it.
1905 In JDK 9 and later, the default keystore implementation is
1907 PKCS12. This is a cross platform keystore based on the RSA
1908 PKCS12 Personal Information Exchange Syntax Standard. This
1909 standard is primarily meant for storing or transporting a user's
1910 private keys, certificates, and miscellaneous secrets. There is
1911 another built-in implementation, provided by Oracle. It imple‐
1912 ments the keystore as a file with a proprietary keystore type
1913 (format) named JKS. It protects each private key with its indi‐
1914 vidual password, and also protects the integrity of the entire
1915 keystore with a (possibly different) password.
1916 Keystore implementations are provider-based. More specifically,
1918 the application interfaces supplied by KeyStore are implemented
1919 in terms of a Service Provider Interface (SPI). That is, there
1920 is a corresponding abstract KeystoreSpi class, also in the ja‐
1921 va.security package, which defines the Service Provider Inter‐
1922 face methods that providers must implement. The term provider
1923 refers to a package or a set of packages that supply a concrete
1924 implementation of a subset of services that can be accessed by
1925 the Java Security API. To provide a keystore implementation,
1926 clients must implement a provider and supply a KeystoreSpi sub‐
1927 class implementation, as described in Steps to Implement and In‐
1928 tegrate a Provider.
1929 Applications can choose different types of keystore implementa‐
1931 tions from different providers, using the getInstance factory
1932 method supplied in the KeyStore class. A keystore type defines
1933 the storage and data format of the keystore information, and the
1934 algorithms used to protect private/secret keys in the keystore
1935 and the integrity of the keystore. Keystore implementations of
1936 different types aren't compatible.
1937 The keytool command works on any file-based keystore implementa‐
1939 tion. It treats the keystore location that is passed to it at
1940 the command line as a file name and converts it to a FileInput‐
1941 Stream, from which it loads the keystore information.)The jar‐
1942 signer commands can read a keystore from any location that can
1943 be specified with a URL.
1944 For keytool and jarsigner, you can specify a keystore type at
1946 the command line, with the -storetype option.
1947 If you don't explicitly specify a keystore type, then the tools
1949 choose a keystore implementation based on the value of the key‐
1950 store.type property specified in the security properties file.
1951 The security properties file is called java.security, and re‐
1952 sides in the security properties directory:
1953 • Linux and OS X: java.home/lib/security
1955 • Windows: java.home\lib\security
1957 Each tool gets the keystore.type value and then examines all the
1959 currently installed providers until it finds one that implements
1960 a keystores of that type. It then uses the keystore implementa‐
1961 tion from that provider.The KeyStore class defines a static
1962 method named getDefaultType that lets applications retrieve the
1963 value of the keystore.type property. The following line of code
1964 creates an instance of the default keystore type as specified in
1965 the keystore.type property:
1966 KeyStore keyStore = KeyStore.getInstance(KeyStore.getDe‐
1968 faultType());
1969 The default keystore type is pkcs12, which is a cross-platform
1971 keystore based on the RSA PKCS12 Personal Information Exchange
1972 Syntax Standard. This is specified by the following line in the
1973 security properties file:
1974 keystore.type=pkcs12
1976 To have the tools utilize a keystore implementation other than
1978 the default, you can change that line to specify a different
1979 keystore type. For example, if you want to use the Oracle's jks
1980 keystore implementation, then change the line to the following:
1981 keystore.type=jks
1983 Note:
1985 Case doesn't matter in keystore type designations. For example,
1987 JKS would be considered the same as jks.
1988 Certificate
1990 A certificate (or public-key certificate) is a digitally signed
1991 statement from one entity (the issuer), saying that the public
1992 key and some other information of another entity (the subject)
1993 has some specific value. The following terms are related to
1994 certificates:
1995 • Public Keys: These are numbers associated with a particular
1997 entity, and are intended to be known to everyone who needs to
1998 have trusted interactions with that entity. Public keys are
1999 used to verify signatures.
2000 • Digitally Signed: If some data is digitally signed, then it is
2002 stored with the identity of an entity and a signature that
2003 proves that entity knows about the data. The data is rendered
2004 unforgeable by signing with the entity's private key.
2005 • Identity: A known way of addressing an entity. In some sys‐
2007 tems, the identity is the public key, and in others it can be
2008 anything from an Oracle Solaris UID to an email address to an
2009 X.509 distinguished name.
2010 • Signature: A signature is computed over some data using the
2012 private key of an entity. The signer, which in the case of a
2013 certificate is also known as the issuer.
2014 • Private Keys: These are numbers, each of which is supposed to
2016 be known only to the particular entity whose private key it is
2017 (that is, it is supposed to be kept secret). Private and pub‐
2018 lic keys exist in pairs in all public key cryptography systems
2019 (also referred to as public key crypto systems). In a typical
2020 public key crypto system, such as DSA, a private key corre‐
2021 sponds to exactly one public key. Private keys are used to
2022 compute signatures.
2023 • Entity: An entity is a person, organization, program, comput‐
2025 er, business, bank, or something else you are trusting to some
2026 degree.
2027 Public key cryptography requires access to users' public keys.
2029 In a large-scale networked environment, it is impossible to
2030 guarantee that prior relationships between communicating enti‐
2031 ties were established or that a trusted repository exists with
2032 all used public keys. Certificates were invented as a solution
2033 to this public key distribution problem. Now a Certification
2034 Authority (CA) can act as a trusted third party. CAs are enti‐
2035 ties such as businesses that are trusted to sign (issue) cer‐
2036 tificates for other entities. It is assumed that CAs only cre‐
2037 ate valid and reliable certificates because they are bound by
2038 legal agreements. There are many public Certification Authori‐
2039 ties, such as DigiCert, Comodo, Entrust, and so on.
2040 You can also run your own Certification Authority using products
2042 such as Microsoft Certificate Server or the Entrust CA product
2043 for your organization. With the keytool command, it is possible
2044 to display, import, and export certificates. It is also possi‐
2045 ble to generate self-signed certificates.
2046 The keytool command currently handles X.509 certificates.
2048 X.509 Certificates
2050 The X.509 standard defines what information can go into a cer‐
2051 tificate and describes how to write it down (the data format).
2052 All the data in a certificate is encoded with two related stan‐
2053 dards called ASN.1/DER. Abstract Syntax Notation 1 describes
2054 data. The Definite Encoding Rules describe a single way to
2055 store and transfer that data.
2056 All X.509 certificates have the following data, in addition to
2058 the signature:
2059 • Version: This identifies which version of the X.509 standard
2061 applies to this certificate, which affects what information
2062 can be specified in it. Thus far, three versions are defined.
2063 The keytool command can import and export v1, v2, and v3 cer‐
2064 tificates. It generates v3 certificates.
2065 • X.509 Version 1 has been available since 1988, is widely de‐
2067 ployed, and is the most generic.
2068 • X.509 Version 2 introduced the concept of subject and issuer
2070 unique identifiers to handle the possibility of reuse of
2071 subject or issuer names over time. Most certificate profile
2072 documents strongly recommend that names not be reused and
2073 that certificates shouldn't make use of unique identifiers.
2074 Version 2 certificates aren't widely used.
2075 • X.509 Version 3 is the most recent (1996) and supports the
2077 notion of extensions where anyone can define an extension
2078 and include it in the certificate. Some common extensions
2079 are: KeyUsage (limits the use of the keys to particular pur‐
2080 poses such as signing-only) and AlternativeNames (allows
2081 other identities to also be associated with this public key,
2082 for example. DNS names, email addresses, IP addresses).
2083 Extensions can be marked critical to indicate that the ex‐
2084 tension should be checked and enforced or used. For exam‐
2085 ple, if a certificate has the KeyUsage extension marked
2086 critical and set to keyCertSign, then when this certificate
2087 is presented during SSL communication, it should be rejected
2088 because the certificate extension indicates that the associ‐
2089 ated private key should only be used for signing certifi‐
2090 cates and not for SSL use.
2091 • Serial number: The entity that created the certificate is re‐
2093 sponsible for assigning it a serial number to distinguish it
2094 from other certificates it issues. This information is used
2095 in numerous ways. For example, when a certificate is revoked
2096 its serial number is placed in a Certificate Revocation List
2097 (CRL).
2098 • Signature algorithm identifier: This identifies the algorithm
2100 used by the CA to sign the certificate.
2101 • Issuer name: The X.500 Distinguished Name of the entity that
2103 signed the certificate. This is typically a CA. Using this
2104 certificate implies trusting the entity that signed this cer‐
2105 tificate. In some cases, such as root or top-level CA cer‐
2106 tificates, the issuer signs its own certificate.
2107 • Validity period: Each certificate is valid only for a limited
2109 amount of time. This period is described by a start date and
2110 time and an end date and time, and can be as short as a few
2111 seconds or almost as long as a century. The validity period
2112 chosen depends on a number of factors, such as the strength of
2113 the private key used to sign the certificate, or the amount
2114 one is willing to pay for a certificate. This is the expected
2115 period that entities can rely on the public value, when the
2116 associated private key has not been compromised.
2117 • Subject name: The name of the entity whose public key the cer‐
2119 tificate identifies. This name uses the X.500 standard, so it
2120 is intended to be unique across the Internet. This is the
2121 X.500 Distinguished Name (DN) of the entity. For example,
2122 CN=Java Duke, OU=Java Software Division, O=Oracle Cor‐
2124 poration, C=US
2125 These refer to the subject's common name (CN), organizational
2127 unit (OU), organization (O), and country (C).
2128 • Subject public key information: This is the public key of the
2130 entity being named with an algorithm identifier that specifies
2131 which public key crypto system this key belongs to and any as‐
2132 sociated key parameters.
2133 Certificate Chains
2135 The keytool command can create and manage keystore key entries
2136 that each contain a private key and an associated certificate
2137 chain. The first certificate in the chain contains the public
2138 key that corresponds to the private key.
2139 When keys are first generated, the chain usually starts off con‐
2141 taining a single element, a self-signed certificate. See
2142 -genkeypair in Commands. A self-signed certificate is one for
2143 which the issuer (signer) is the same as the subject. The sub‐
2144 ject is the entity whose public key is being authenticated by
2145 the certificate. When the -genkeypair command is called to gen‐
2146 erate a new public/private key pair, it also wraps the public
2147 key into a self-signed certificate (unless the -signer option is
2148 specified).
2149 Later, after a Certificate Signing Request (CSR) was generated
2151 with the -certreq command and sent to a Certification Authority
2152 (CA), the response from the CA is imported with -importcert, and
2153 the self-signed certificate is replaced by a chain of certifi‐
2154 cates. At the bottom of the chain is the certificate (reply)
2155 issued by the CA authenticating the subject's public key. The
2156 next certificate in the chain is one that authenticates the CA's
2157 public key.
2158 In many cases, this is a self-signed certificate, which is a
2160 certificate from the CA authenticating its own public key, and
2161 the last certificate in the chain. In other cases, the CA might
2162 return a chain of certificates. In this case, the bottom cer‐
2163 tificate in the chain is the same (a certificate signed by the
2164 CA, authenticating the public key of the key entry), but the
2165 second certificate in the chain is a certificate signed by a
2166 different CA that authenticates the public key of the CA you
2167 sent the CSR to. The next certificate in the chain is a cer‐
2168 tificate that authenticates the second CA's key, and so on, un‐
2169 til a self-signed root certificate is reached. Each certificate
2170 in the chain (after the first) authenticates the public key of
2171 the signer of the previous certificate in the chain.
2172 Many CAs only return the issued certificate, with no supporting
2174 chain, especially when there is a flat hierarchy (no intermedi‐
2175 ates CAs). In this case, the certificate chain must be estab‐
2176 lished from trusted certificate information already stored in
2177 the keystore.
2178 A different reply format (defined by the PKCS #7 standard) in‐
2180 cludes the supporting certificate chain in addition to the is‐
2181 sued certificate. Both reply formats can be handled by the key‐
2182 tool command.
2183 The top-level (root) CA certificate is self-signed. However,
2185 the trust into the root's public key doesn't come from the root
2186 certificate itself, but from other sources such as a newspaper.
2187 This is because anybody could generate a self-signed certificate
2188 with the distinguished name of, for example, the DigiCert root
2189 CA. The root CA public key is widely known. The only reason it
2190 is stored in a certificate is because this is the format under‐
2191 stood by most tools, so the certificate in this case is only
2192 used as a vehicle to transport the root CA's public key. Before
2193 you add the root CA certificate to your keystore, you should
2194 view it with the -printcert option and compare the displayed
2195 fingerprint with the well-known fingerprint obtained from a
2196 newspaper, the root CA's Web page, and so on.
2197 cacerts Certificates File
2199 A certificates file named cacerts resides in the security prop‐
2200 erties directory:
2201 • Linux and OS X: JAVA_HOME/lib/security
2203 • Windows: JAVA_HOME\lib\security
2205 The cacerts file represents a system-wide keystore with CA cer‐
2207 tificates. System administrators can configure and manage that
2208 file with the keytool command by specifying jks as the keystore
2209 type. The cacerts keystore file ships with a default set of
2210 root CA certificates. For Linux, OS X, and Windows, you can
2211 list the default certificates with the following command:
2212 keytool -list -cacerts
2214 The initial password of the cacerts keystore file is changeit.
2216 System administrators should change that password and the de‐
2217 fault access permission of that file upon installing the SDK.
2218 Note:
2220 It is important to verify your cacerts file. Because you trust
2222 the CAs in the cacerts file as entities for signing and issuing
2223 certificates to other entities, you must manage the cacerts file
2224 carefully. The cacerts file should contain only certificates of
2225 the CAs you trust. It is your responsibility to verify the
2226 trusted root CA certificates bundled in the cacerts file and
2227 make your own trust decisions.
2228 To remove an untrusted CA certificate from the cacerts file, use
2230 the -delete option of the keytool command. You can find the
2231 cacerts file in the JDK's $JAVA_HOME/lib/security directory.
2232 Contact your system administrator if you don't have permission
2233 to edit this file.
2234 Internet RFC 1421 Certificate Encoding Standard
2236 Certificates are often stored using the printable encoding for‐
2237 mat defined by the Internet RFC 1421 standard, instead of their
2238 binary encoding. This certificate format, also known as Base64
2239 encoding, makes it easy to export certificates to other applica‐
2240 tions by email or through some other mechanism.
2241 Certificates read by the -importcert and -printcert commands can
2243 be in either this format or binary encoded. The -exportcert
2244 command by default outputs a certificate in binary encoding, but
2245 will instead output a certificate in the printable encoding for‐
2246 mat, when the -rfc option is specified.
2247 The -list command by default prints the SHA-256 fingerprint of a
2249 certificate. If the -v option is specified, then the certifi‐
2250 cate is printed in human-readable format. If the -rfc option is
2251 specified, then the certificate is output in the printable en‐
2252 coding format.
2253 In its printable encoding format, the encoded certificate is
2255 bounded at the beginning and end by the following text:
2256 -----BEGIN CERTIFICATE-----
2258 encoded certificate goes here.
2260 -----END CERTIFICATE-----
2262 X.500 Distinguished Names
2264 X.500 Distinguished Names are used to identify entities, such as
2265 those that are named by the subject and issuer (signer) fields
2266 of X.509 certificates. The keytool command supports the follow‐
2267 ing subparts:
2268 • commonName: The common name of a person such as Susan Jones.
2270 • organizationUnit: The small organization (such as department
2272 or division) name. For example, Purchasing.
2273 • localityName: The locality (city) name, for example, Palo Al‐
2275 to.
2276 • stateName: State or province name, for example, California.
2278 • country: Two-letter country code, for example, CH.
2280 When you supply a distinguished name string as the value of a
2282 -dname option, such as for the -genkeypair command, the string
2283 must be in the following format:
2284 CN=cName, OU=orgUnit, O=org, L=city, S=state, C=coun‐
2286 tryCode
2287 All the following items represent actual values and the previous
2289 keywords are abbreviations for the following:
2290 CN=commonName
2292 OU=organizationUnit
2293 O=organizationName
2294 L=localityName
2295 S=stateName
2296 C=country
2297 A sample distinguished name string is:
2299 CN=Mark Smith, OU=Java, O=Oracle, L=Cupertino, S=Califor‐
2301 nia, C=US
2302 A sample command using such a string is:
2304 keytool -genkeypair -dname "CN=Mark Smith, OU=Java, O=Or‐
2306 acle, L=Cupertino, S=Califor‐
2307 nia, C=US" -alias mark -keyalg rsa
2308 Case doesn't matter for the keyword abbreviations. For example,
2310 CN, cn, and Cn are all treated the same.
2311 Order matters; each subcomponent must appear in the designated
2313 order. However, it isn't necessary to have all the subcompo‐
2314 nents. You can use a subset, for example:
2315 CN=Smith, OU=Java, O=Oracle, C=US
2317 If a distinguished name string value contains a comma, then the
2319 comma must be escaped by a backslash (\) character when you
2320 specify the string on a command line, as in:
2321 cn=Jack, ou=Java\, Product Development, o=Oracle, c=US
2323 It is never necessary to specify a distinguished name string on
2325 a command line. When the distinguished name is needed for a
2326 command, but not supplied on the command line, the user is
2327 prompted for each of the subcomponents. In this case, a comma
2328 doesn't need to be escaped by a backslash (\).
2329
2332 Important: Be sure to check a certificate very carefully before import‐
2333 ing it as a trusted certificate.
2334 Windows Example:
2336 View the certificate first with the -printcert command or the -im‐
2338 portcert command without the -noprompt option. Ensure that the dis‐
2339 played certificate fingerprints match the expected ones. For example,
2340 suppose someone sends or emails you a certificate that you put it in a
2341 file named \tmp\cert. Before you consider adding the certificate to
2342 your list of trusted certificates, you can execute a -printcert command
2343 to view its fingerprints, as follows:
2344 keytool -printcert -file \tmp\cert
2346 Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
2347 Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
2348 Serial Number: 59092b34
2349 Valid from: Thu Jun 24 18:01:13 PDT 2016 until: Wed Jun 23 17:01:13 PST 2016
2350 Certificate Fingerprints:
2351 SHA-1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE
2353 SHA-256: 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90:
2354 17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4
2355 Linux Example:
2357 View the certificate first with the -printcert command or the -im‐
2359 portcert command without the -noprompt option. Ensure that the dis‐
2360 played certificate fingerprints match the expected ones. For example,
2361 suppose someone sends or emails you a certificate that you put it in a
2362 file named /tmp/cert. Before you consider adding the certificate to
2363 your list of trusted certificates, you can execute a -printcert command
2364 to view its fingerprints, as follows:
2365 keytool -printcert -file /tmp/cert
2367 Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
2368 Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
2369 Serial Number: 59092b34
2370 Valid from: Thu Jun 24 18:01:13 PDT 2016 until: Wed Jun 23 17:01:13 PST 2016
2371 Certificate Fingerprints:
2372 SHA-1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE
2374 SHA-256: 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90:
2375 17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4
2376 Then call or otherwise contact the person who sent the certificate and
2378 compare the fingerprints that you see with the ones that they show.
2379 Only when the fingerprints are equal is it guaranteed that the certifi‐
2380 cate wasn't replaced in transit with somebody else's certificate such
2381 as an attacker's certificate. If such an attack took place, and you
2382 didn't check the certificate before you imported it, then you would be
2383 trusting anything the attacker signed, for example, a JAR file with ma‐
2384 licious class files inside.
2385 Note:
2387 It isn't required that you execute a -printcert command before import‐
2389 ing a certificate. This is because before you add a certificate to the
2390 list of trusted certificates in the keystore, the -importcert command
2391 prints out the certificate information and prompts you to verify it.
2392 You can then stop the import operation. However, you can do this only
2393 when you call the -importcert command without the -noprompt option. If
2394 the -noprompt option is specified, then there is no interaction with
2395 the user.
2396
2398 Most commands that operate on a keystore require the store password.
2399 Some commands require a private/secret key password. Passwords can be
2400 specified on the command line in the -storepass and -keypass options.
2401 However, a password shouldn't be specified on a command line or in a
2402 script unless it is for testing, or you are on a secure system. When
2403 you don't specify a required password option on a command line, you are
2404 prompted for it.
2405
2407 Internet X.509 Public Key Infrastructure Certificate and Certificate
2408 Revocation List (CRL) Profile [https://tools.ietf.org/rfc/rfc5280.txt]
2409 defined a profile on conforming X.509 certificates, which includes what
2410 values and value combinations are valid for certificate fields and ex‐
2411 tensions.
2412 The keytool command doesn't enforce all of these rules so it can gener‐
2414 ate certificates that don't conform to the standard, such as
2415 self-signed certificates that would be used for internal testing pur‐
2416 poses. Certificates that don't conform to the standard might be re‐
2417 jected by the JDK or other applications. Users should ensure that they
2418 provide the correct options for -dname, -ext, and so on.
2419
2421 Before you add the certificate to the keystore, the keytool command
2422 verifies it by attempting to construct a chain of trust from that cer‐
2423 tificate to a self-signed certificate (belonging to a root CA), using
2424 trusted certificates that are already available in the keystore.
2425 If the -trustcacerts option was specified, then additional certificates
2427 are considered for the chain of trust, namely the certificates in a
2428 file named cacerts.
2429 If the keytool command fails to establish a trust path from the cer‐
2431 tificate to be imported up to a self-signed certificate (either from
2432 the keystore or the cacerts file), then the certificate information is
2433 printed, and the user is prompted to verify it by comparing the dis‐
2434 played certificate fingerprints with the fingerprints obtained from
2435 some other (trusted) source of information, which might be the certifi‐
2436 cate owner. Be very careful to ensure the certificate is valid before
2437 importing it as a trusted certificate. The user then has the option of
2438 stopping the import operation. If the -noprompt option is specified,
2439 then there is no interaction with the user.
2440
2442 When you import a certificate reply, the certificate reply is validated
2443 with trusted certificates from the keystore, and optionally, the cer‐
2444 tificates configured in the cacerts keystore file when the -trustcac‐
2445 erts option is specified.
2446 The methods of determining whether the certificate reply is trusted are
2448 as follows:
2449 • If the reply is a single X.509 certificate, then the keytool command
2451 attempts to establish a trust chain, starting at the certificate re‐
2452 ply and ending at a self-signed certificate (belonging to a root CA).
2453 The certificate reply and the hierarchy of certificates is used to
2454 authenticate the certificate reply from the new certificate chain of
2455 aliases. If a trust chain can't be established, then the certificate
2456 reply isn't imported. In this case, the keytool command doesn't
2457 print the certificate and prompt the user to verify it, because it is
2458 very difficult for a user to determine the authenticity of the cer‐
2459 tificate reply.
2460 • If the reply is a PKCS #7 formatted certificate chain or a sequence
2462 of X.509 certificates, then the chain is ordered with the user cer‐
2463 tificate first followed by zero or more CA certificates. If the
2464 chain ends with a self-signed root CA certificate and the-trustcac‐
2465 erts option was specified, the keytool command attempts to match it
2466 with any of the trusted certificates in the keystore or the cacerts
2467 keystore file. If the chain doesn't end with a self-signed root CA
2468 certificate and the -trustcacerts option was specified, the keytool
2469 command tries to find one from the trusted certificates in the key‐
2470 store or the cacerts keystore file and add it to the end of the
2471 chain. If the certificate isn't found and the -noprompt option isn't
2472 specified, the information of the last certificate in the chain is
2473 printed, and the user is prompted to verify it.
2474 If the public key in the certificate reply matches the user's public
2476 key already stored with alias, then the old certificate chain is re‐
2477 placed with the new certificate chain in the reply. The old chain can
2478 only be replaced with a valid keypass, and so the password used to pro‐
2479 tect the private key of the entry is supplied. If no password is pro‐
2480 vided, and the private key password is different from the keystore
2481 password, the user is prompted for it.
2482 This command was named -import in earlier releases. This old name is
2484 still supported in this release. The new name, -importcert, is pre‐
2485 ferred.
2486JDK 17 2021 KEYTOOL(1)