1keytool(1) Security Tools keytool(1)
2
6 keytool - Manages a keystore (database) of cryptographic keys, X.509
7 certificate chains, and trusted certificates.
8
10 keytool [commands]
11 commands
14 See Commands. These commands are categorized by task as follows:
15 · Create or Add Data to the Keystore
17 · -gencert
19 · -genkeypair
21 · -genseckey
23 · -importcert
25 · -importpassword
27 · Import Contents From Another Keystore
30 · -importkeystore
32 · Generate Certificate Request
35 · -certreq
37 · Export Data
40 · -exportcert
42 · Display Data
45 · -list
47 · -printcert
49 · -printcertreq
51 · -printcrl
53 · Manage the Keystore
56 · -storepasswd
58 · -keypasswd
60 · -delete
62 · -changealias
64 · Get Help
67 · -help
69
73 The keytool command is a key and certificate management utility. It
74 enables users to administer their own public/private key pairs and
75 associated certificates for use in self-authentication (where the user
76 authenticates himself or herself to other users and services) or data
77 integrity and authentication services, using digital signatures. The
78 keytool command also enables users to cache the public keys (in the
79 form of certificates) of their communicating peers.
80 A certificate is a digitally signed statement from one entity (person,
82 company, and so on.), that says that the public key (and some other
83 information) of some other entity has a particular value. (See
84 Certificate.) When data is digitally signed, the signature can be
85 verified to check the data integrity and authenticity. Integrity means
86 that the data has not been modified or tampered with, and authenticity
87 means the data comes from whoever claims to have created and signed it.
88 The keytool command also enables users to administer secret keys and
90 passphrases used in symmetric encryption and decryption (DES).
91 The keytool command stores the keys and certificates in a keystore. See
93 KeyStore aliases.
94
96 See Commands for a listing and description of the various commands.
97 · All command and option names are preceded by a minus sign (-).
99 · The options for each command can be provided in any order.
101 · All items not italicized or in braces or brackets are required to
103 appear as is.
104 · Braces surrounding an option signify that a default value will be
106 used when the option is not specified on the command line. See Option
107 Defaults. Braces are also used around the -v, -rfc, and -J options,
108 which only have meaning when they appear on the command line. They do
109 not have any default values other than not existing.
110 · Brackets surrounding an option signify that the user is prompted for
112 the values when the option is not specified on the command line. For
113 the -keypass option, if you do not specify the option on the command
114 line, then the keytool command first attempts to use the keystore
115 password to recover the private/secret key. If this attempt fails,
116 then the keytool command prompts you for the private/secret key
117 password.
118 · Items in italics (option values) represent the actual values that
120 must be supplied. For example, here is the format of the -printcert
121 command:
122 keytool -printcert {-file cert_file} {-v}
124 When you specify a -printcert command, replace cert_file with the
130 actual file name, as follows: keytool -printcert -file VScert.cer
131 · Option values must be put in quotation marks when they contain a
133 blank (space).
134 · The -help option is the default. The keytool command is the same as
136 keytool -help.
137
139 The following examples show the defaults for various option values.
140 -alias "mykey"
142 -keyalg
143 "DSA" (when using -genkeypair)
144 "DES" (when using -genseckey)
145 -keysize
146 2048 (when using -genkeypair and -keyalg is "RSA")
147 1024 (when using -genkeypair and -keyalg is "DSA")
148 256 (when using -genkeypair and -keyalg is "EC")
149 56 (when using -genseckey and -keyalg is "DES")
150 168 (when using -genseckey and -keyalg is "DESede")
151 -validity 90
152 -keystore <the file named .keystore in the user's home directory>
153 -storetype <the value of the "keystore.type" property in the
154 security properties file, which is returned by the static
155 getDefaultType method in java.security.KeyStore>
156 -file
157 stdin (if reading)
158 stdout (if writing)
159 -protected false
160 In generating a public/private key pair, the signature algorithm
162 (-sigalg option) is derived from the algorithm of the underlying
163 private key:
164 · If the underlying private key is of type DSA, then the -sigalg option
166 defaults to SHA1withDSA.
167 · If the underlying private key is of type RSA, then the -sigalg option
169 defaults to SHA256withRSA.
170 · If the underlying private key is of type EC, then the -sigalg option
172 defaults to SHA256withECDSA.
173 For a full list of -keyalg and -sigalg arguments, see Java Cryptography
175 Architecture (JCA) Reference Guide at
176 http://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/CryptoSpec.html#AppA
177
179 The -v option can appear for all commands except -help. When the -v
180 option appears, it signifies verbose mode, which means that more
181 information is provided in the output.
182 There is also a -Jjavaoption argument that can appear for any command.
184 When the -Jjavaoption appears, the specified javaoption string is
185 passed directly to the Java interpreter. This option does not contain
186 any spaces. It is useful for adjusting the execution environment or
187 memory usage. For a list of possible interpreter options, type java -h
188 or java -X at the command line.
189 These options can appear for all commands operating on a keystore:
191 -storetype storetype
193 This qualifier specifies the type of keystore to be
194 instantiated.
195 -keystore keystore
197 The keystore location.
198 If the JKS storetype is used and a keystore file does not yet
200 exist, then certain keytool commands can result in a new
201 keystore file being created. For example, if keytool -genkeypair
202 is called and the -keystore option is not specified, the default
203 keystore file named .keystore in the user's home directory is
204 created when it does not already exist. Similarly, if the
205 -keystore ks_file option is specified but ks_file does not
206 exist, then it is created. For more information on the JKS
207 storetype, see the KeyStore Implementation section in KeyStore
208 aliases.
209 Note that the input stream from the -keystore option is passed
211 to the KeyStore.load method. If NONE is specified as the URL,
212 then a null stream is passed to the KeyStore.load method. NONE
213 should be specified if the keystore is not file-based. For
214 example, when it resides on a hardware token device.
215 -storepass[:env| :file] argument
217 The password that is used to protect the integrity of the
218 keystore.
219 If the modifier env or file is not specified, then the password
221 has the value argument, which must be at least 6 characters
222 long. Otherwise, the password is retrieved as follows:
223 · env: Retrieve the password from the environment variable named
225 argument.
226 · file: Retrieve the password from the file named argument.
228 Note: All other options that require passwords, such as -keypass,
231 -srckeypass, -destkeypass, -srcstorepass, and -deststorepass, accept
232 the env and file modifiers. Remember to separate the password option
233 and the modifier with a colon (:).
234 The password must be provided to all commands that access the keystore
236 contents. For such commands, when the -storepass option is not provided
237 at the command line, the user is prompted for it.
238 When retrieving information from the keystore, the password is
240 optional. If no password is specified, then the integrity of the
241 retrieved information cannot be verified and a warning is displayed.
242 -providerName provider_name
244 Used to identify a cryptographic service provider's name when
245 listed in the security properties file.
246 -providerClass provider_class_name
248 Used to specify the name of a cryptographic service provider's
249 master class file when the service provider is not listed in the
250 security properties file.
251 -providerArg provider_arg
253 Used with the -providerClass option to represent an optional
254 string input argument for the constructor of
255 provider_class_name.
256 -protected
258 Either true or false. This value should be specified as true
259 when a password must be specified by way of a protected
260 authentication path such as a dedicated PIN reader.Because there
261 are two keystores involved in the -importkeystore command, the
262 following two options -srcprotected and -destprotected are
263 provided for the source keystore and the destination keystore
264 respectively.
265 -ext {name{:critical} {=value}}
267 Denotes an X.509 certificate extension. The option can be used
268 in -genkeypair and -gencert to embed extensions into the
269 certificate generated, or in -certreq to show what extensions
270 are requested in the certificate request. The option can appear
271 multiple times. The name argument can be a supported extension
272 name (see Named Extensions) or an arbitrary OID number. The
273 value argument, when provided, denotes the argument for the
274 extension. When value is omitted, that means that the default
275 value of the extension or the extension requires no argument.
276 The :critical modifier, when provided, means the extension's
277 isCritical attribute is true; otherwise, it is false. You can
278 use :c in place of :critical.
279
281 The keytool command supports these named extensions. The names are not
282 case-sensitive).
283 BC or BasicContraints
285 Values: The full form is: ca:{true|false}[,pathlen:<len>] or
286 <len>, which is short for ca:true,pathlen:<len>. When <len> is
287 omitted, you have ca:true.
288 KU or KeyUsage
290 Values: usage(,usage)*, where usage can be one of
291 digitalSignature, nonRepudiation (contentCommitment),
292 keyEncipherment, dataEncipherment, keyAgreement, keyCertSign,
293 cRLSign, encipherOnly, decipherOnly. The usage argument can be
294 abbreviated with the first few letters (dig for
295 digitalSignature) or in camel-case style (dS for
296 digitalSignature or cRLS for cRLSign), as long as no ambiguity
297 is found. The usage values are case-sensitive.
298 EKU or ExtendedKeyUsage
300 Values: usage(,usage)*, where usage can be one of
301 anyExtendedKeyUsage, serverAuth, clientAuth, codeSigning,
302 emailProtection, timeStamping, OCSPSigning, or any OID string.
303 The usage argument can be abbreviated with the first few letters
304 or in camel-case style, as long as no ambiguity is found. The
305 usage values are case-sensitive.
306 SAN or SubjectAlternativeName
308 Values: type:value(,type:value)*, where type can be EMAIL, URI,
309 DNS, IP, or OID. The value argument is the string format value
310 for the type.
311 IAN or IssuerAlternativeName
313 Values: Same as SubjectAlternativeName.
314 SIA or SubjectInfoAccess
316 Values: method:location-type:location-value (,method:location-
317 type:location-value)*, where method can be timeStamping,
318 caRepository or any OID. The location-type and location-value
319 arguments can be any type:value supported by the
320 SubjectAlternativeName extension.
321 AIA or AuthorityInfoAccess
323 Values: Same as SubjectInfoAccess. The method argument can be
324 ocsp,caIssuers, or any OID.
325 When name is OID, the value is the hexadecimal dumped DER encoding of
327 the extnValue for the extension excluding the OCTET STRING type and
328 length bytes. Any extra character other than standard hexadecimal
329 numbers (0-9, a-f, A-F) are ignored in the HEX string. Therefore, both
330 01:02:03:04 and 01020304 are accepted as identical values. When there
331 is no value, the extension has an empty value field.
332 A special name honored, used in -gencert only, denotes how the
334 extensions included in the certificate request should be honored. The
335 value for this name is a comma separated list of all (all requested
336 extensions are honored), name{:[critical|non-critical]} (the named
337 extension is honored, but using a different isCritical attribute) and
338 -name (used with all, denotes an exception). Requested extensions are
339 not honored by default.
340 If, besides the-ext honored option, another named or OID -ext option is
342 provided, this extension is added to those already honored. However, if
343 this name (or OID) also appears in the honored value, then its value
344 and criticality overrides the one in the request.
345 The subjectKeyIdentifier extension is always created. For non-self-
347 signed certificates, the authorityKeyIdentifier is created.
348 Note: Users should be aware that some combinations of extensions (and
350 other certificate fields) may not conform to the Internet standard. See
351 Certificate Conformance Warning.
352
354 -gencert
355 {-rfc} {-infile infile} {-outfile outfile} {-alias alias} {-sigalg sigalg}
357 {-dname dname} {-startdate startdate {-ext ext}* {-validity valDays}
360 [-keypass keypass] {-keystore keystore} [-storepass storepass]
363 {-storetype storetype} {-providername provider_name}
366 {-providerClass provider_class_name {-providerArg provider_arg}}
369 {-v} {-protected} {-Jjavaoption}
372 Generates a certificate as a response to a certificate request
376 file (which can be created by the keytool-certreq command). The
377 command reads the request from infile (if omitted, from the
378 standard input), signs it using alias's private key, and outputs
379 the X.509 certificate into outfile (if omitted, to the standard
380 output). When-rfc is specified, the output format is
381 Base64-encoded PEM; otherwise, a binary DER is created.
382 The sigalg value specifies the algorithm that should be used to
384 sign the certificate. The startdate argument is the start time
385 and date that the certificate is valid. The valDays argument
386 tells the number of days for which the certificate should be
387 considered valid.
388 When dname is provided, it is used as the subject of the
390 generated certificate. Otherwise, the one from the certificate
391 request is used.
392 The ext value shows what X.509 extensions will be embedded in
394 the certificate. Read Common Options for the grammar of -ext.
395 The -gencert option enables you to create certificate chains.
397 The following example creates a certificate, e1, that contains
398 three certificates in its certificate chain.
399 The following commands creates four key pairs named ca, ca1,
401 ca2, and e1:
402 keytool -alias ca -dname CN=CA -genkeypair
404 keytool -alias ca1 -dname CN=CA -genkeypair
405 keytool -alias ca2 -dname CN=CA -genkeypair
406 keytool -alias e1 -dname CN=E1 -genkeypair
407 The following two commands create a chain of signed
411 certificates; ca signs ca1 and ca1 signs ca2, all of which are
412 self-issued:
413 keytool -alias ca1 -certreq |
415 keytool -alias ca -gencert -ext san=dns:ca1 |
416 keytool -alias ca1 -importcert
417 keytool -alias ca2 -certreq |
418 $KT -alias ca1 -gencert -ext san=dns:ca2 |
419 $KT -alias ca2 -importcert
420 The following command creates the certificate e1 and stores it
424 in the file e1.cert, which is signed by ca2. As a result, e1
425 should contain ca, ca1, and ca2 in its certificate chain:
426 keytool -alias e1 -certreq | keytool -alias ca2 -gencert > e1.cert
428 -genkeypair
432 {-alias alias} {-keyalg keyalg} {-keysize keysize} {-sigalg sigalg}
434 [-dname dname] [-keypass keypass] {-startdate value} {-ext ext}*
437 {-validity valDays} {-storetype storetype} {-keystore keystore}
440 [-storepass storepass]
443 {-providerClass provider_class_name {-providerArg provider_arg}}
446 {-v} {-protected} {-Jjavaoption}
449 Generates a key pair (a public key and associated private key).
453 Wraps the public key into an X.509 v3 self-signed certificate,
454 which is stored as a single-element certificate chain. This
455 certificate chain and the private key are stored in a new
456 keystore entry identified by alias.
457 The keyalg value specifies the algorithm to be used to generate
459 the key pair, and the keysize value specifies the size of each
460 key to be generated. The sigalg value specifies the algorithm
461 that should be used to sign the self-signed certificate. This
462 algorithm must be compatible with the keyalg value.
463 The dname value specifies the X.500 Distinguished Name to be
465 associated with the value of alias, and is used as the issuer
466 and subject fields in the self-signed certificate. If no
467 distinguished name is provided at the command line, then the
468 user is prompted for one.
469 The value of keypass is a password used to protect the private
471 key of the generated key pair. If no password is provided, then
472 the user is prompted for it. If you press the Return key at the
473 prompt, then the key password is set to the same password as the
474 keystore password. The keypass value must be at least 6
475 characters.
476 The value of startdate specifies the issue time of the
478 certificate, also known as the "Not Before" value of the X.509
479 certificate's Validity field.
480 The option value can be set in one of these two forms:
482 ([+-]nnn[ymdHMS])+
484 [yyyy/mm/dd] [HH:MM:SS]
486 With the first form, the issue time is shifted by the specified
488 value from the current time. The value is a concatenation of a
489 sequence of subvalues. Inside each subvalue, the plus sign (+)
490 means shift forward, and the minus sign (-) means shift
491 backward. The time to be shifted is nnn units of years, months,
492 days, hours, minutes, or seconds (denoted by a single character
493 of y, m, d, H, M, or S respectively). The exact value of the
494 issue time is calculated using the
495 java.util.GregorianCalendar.add(int field, int amount) method on
496 each subvalue, from left to right. For example, by specifying,
497 the issue time will be:
498 Calendar c = new GregorianCalendar();
500 c.add(Calendar.YEAR, -1);
501 c.add(Calendar.MONTH, 1);
502 c.add(Calendar.DATE, -1);
503 return c.getTime()
504 With the second form, the user sets the exact issue time in two
508 parts, year/month/day and hour:minute:second (using the local
509 time zone). The user can provide only one part, which means the
510 other part is the same as the current date (or time). The user
511 must provide the exact number of digits as shown in the format
512 definition (padding with 0 when shorter). When both the date and
513 time are provided, there is one (and only one) space character
514 between the two parts. The hour should always be provided in 24
515 hour format.
516 When the option is not provided, the start date is the current
518 time. The option can be provided at most once.
519 The value of valDays specifies the number of days (starting at
521 the date specified by -startdate, or the current date when
522 -startdate is not specified) for which the certificate should be
523 considered valid.
524 This command was named -genkey in earlier releases. The old name
526 is still supported in this release. The new name, -genkeypair,
527 is preferred going forward.
528 -genseckey
530 {-alias alias} {-keyalg keyalg} {-keysize keysize} [-keypass keypass]
532 {-storetype storetype} {-keystore keystore} [-storepass storepass]
535 {-providerClass provider_class_name {-providerArg provider_arg}} {-v}
538 {-protected} {-Jjavaoption}
541 Generates a secret key and stores it in a new
545 KeyStore.SecretKeyEntry identified by alias.
546 The value of keyalg specifies the algorithm to be used to
548 generate the secret key, and the value of keysize specifies the
549 size of the key to be generated. The keypass value is a password
550 that protects the secret key. If no password is provided, then
551 the user is prompted for it. If you press the Return key at the
552 prompt, then the key password is set to the same password that
553 is used for the keystore. The keypass value must be at least 6
554 characters.
555 -importcert
557 {-alias alias} {-file cert_file} [-keypass keypass] {-noprompt} {-trustcacerts}
559 {-storetype storetype} {-keystore keystore} [-storepass storepass]
562 {-providerName provider_name}
565 {-providerClass provider_class_name {-providerArg provider_arg}}
568 {-v} {-protected} {-Jjavaoption}
571 Reads the certificate or certificate chain (where the latter is
575 supplied in a PKCS#7 formatted reply or a sequence of X.509
576 certificates) from the file cert_file, and stores it in the
577 keystore entry identified by alias. If no file is specified,
578 then the certificate or certificate chain is read from stdin.
579 The keytool command can import X.509 v1, v2, and v3
581 certificates, and PKCS#7 formatted certificate chains consisting
582 of certificates of that type. The data to be imported must be
583 provided either in binary encoding format or in printable
584 encoding format (also known as Base64 encoding) as defined by
585 the Internet RFC 1421 standard. In the latter case, the encoding
586 must be bounded at the beginning by a string that starts with
587 -----BEGIN, and bounded at the end by a string that starts with
588 -----END.
589 You import a certificate for two reasons: To add it to the list
591 of trusted certificates, and to import a certificate reply
592 received from a certificate authority (CA) as the result of
593 submitting a Certificate Signing Request to that CA (see the
594 -certreq option in Commands).
595 Which type of import is intended is indicated by the value of
597 the -alias option. If the alias does not point to a key entry,
598 then the keytool command assumes you are adding a trusted
599 certificate entry. In this case, the alias should not already
600 exist in the keystore. If the alias does already exist, then the
601 keytool command outputs an error because there is already a
602 trusted certificate for that alias, and does not import the
603 certificate. If the alias points to a key entry, then the
604 keytool command assumes you are importing a certificate reply.
605 -importpassword
607 {-alias alias} [-keypass keypass] {-storetype storetype} {-keystore keystore}
609 [-storepass storepass]
612 {-providerClass provider_class_name {-providerArg provider_arg}}
615 {-v} {-protected} {-Jjavaoption}
618 Imports a passphrase and stores it in a new
622 KeyStore.SecretKeyEntry identified by alias. The passphrase may
623 be supplied via the standard input stream; otherwise the user is
624 prompted for it. keypass is a password used to protect the
625 imported passphrase. If no password is provided, the user is
626 prompted for it. If you press the Return key at the prompt, the
627 key password is set to the same password as that used for the
628 keystore. keypass must be at least 6 characters long.
629 -importkeystore
631 {-srcstoretype srcstoretype} {-deststoretype deststoretype}
633 [-srcstorepass srcstorepass] [-deststorepass deststorepass] {-srcprotected}
636 {-destprotected}
639 {-srcalias srcalias {-destalias destalias} [-srckeypass srckeypass]}
642 [-destkeypass destkeypass] {-noprompt}
645 {-srcProviderName src_provider_name} {-destProviderName dest_provider_name}
648 {-providerClass provider_class_name {-providerArg provider_arg}} {-v}
651 {-protected} {-Jjavaoption}
654 Imports a single entry or all entries from a source keystore to
658 a destination keystore.
659 When the -srcalias option is provided, the command imports the
661 single entry identified by the alias to the destination
662 keystore. If a destination alias is not provided with destalias,
663 then srcalias is used as the destination alias. If the source
664 entry is protected by a password, then srckeypass is used to
665 recover the entry. If srckeypass is not provided, then the
666 keytool command attempts to use srcstorepass to recover the
667 entry. If srcstorepass is either not provided or is incorrect,
668 then the user is prompted for a password. The destination entry
669 is protected with destkeypass. If destkeypass is not provided,
670 then the destination entry is protected with the source entry
671 password. For example, most third-party tools require storepass
672 and keypass in a PKCS #12 keystore to be the same. In order to
673 create a PKCS #12 keystore for these tools, always specify a
674 -destkeypass to be the same as -deststorepass.
675 If the -srcalias option is not provided, then all entries in the
677 source keystore are imported into the destination keystore. Each
678 destination entry is stored under the alias from the source
679 entry. If the source entry is protected by a password, then
680 srcstorepass is used to recover the entry. If srcstorepass is
681 either not provided or is incorrect, then the user is prompted
682 for a password. If a source keystore entry type is not supported
683 in the destination keystore, or if an error occurs while storing
684 an entry into the destination keystore, then the user is
685 prompted whether to skip the entry and continue or to quit. The
686 destination entry is protected with the source entry password.
687 If the destination alias already exists in the destination
689 keystore, then the user is prompted to either overwrite the
690 entry or to create a new entry under a different alias name.
691 If the -noprompt option is provided, then the user is not
693 prompted for a new destination alias. Existing entries are
694 overwritten with the destination alias name. Entries that cannot
695 be imported are skipped and a warning is displayed.
696 -printcertreq
698 {-file file}
700 Prints the content of a PKCS #10 format certificate request,
704 which can be generated by the keytool-certreq command. The
705 command reads the request from file. If there is no file, then
706 the request is read from the standard input.
707 -certreq
709 {-alias alias} {-dname dname} {-sigalg sigalg} {-file certreq_file}
711 [-keypass keypass] {-storetype storetype} {-keystore keystore}
714 [-storepass storepass] {-providerName provider_name}
717 {-providerClass provider_class_name {-providerArg provider_arg}}
720 {-v} {-protected} {-Jjavaoption}
723 Generates a Certificate Signing Request (CSR) using the PKCS #10
727 format.
728 A CSR is intended to be sent to a certificate authority (CA).
730 The CA authenticates the certificate requestor (usually off-
731 line) and will return a certificate or certificate chain, used
732 to replace the existing certificate chain (which initially
733 consists of a self-signed certificate) in the keystore.
734 The private key associated with alias is used to create the PKCS
736 #10 certificate request. To access the private key, the correct
737 password must be provided. If keypass is not provided at the
738 command line and is different from the password used to protect
739 the integrity of the keystore, then the user is prompted for it.
740 If dname is provided, then it is used as the subject in the CSR.
741 Otherwise, the X.500 Distinguished Name associated with alias is
742 used.
743 The sigalg value specifies the algorithm that should be used to
745 sign the CSR.
746 The CSR is stored in the file certreq_file. If no file is
748 specified, then the CSR is output to stdout.
749 Use the importcert command to import the response from the CA.
751 -exportcert
753 {-alias alias} {-file cert_file} {-storetype storetype} {-keystore keystore}
755 [-storepass storepass] {-providerName provider_name}
758 {-providerClass provider_class_name {-providerArg provider_arg}}
761 {-rfc} {-v} {-protected} {-Jjavaoption}
764 Reads from the keystore the certificate associated with alias
768 and stores it in the cert_file file. When no file is specified,
769 the certificate is output to stdout.
770 The certificate is by default output in binary encoding. If the
772 -rfc option is specified, then the output in the printable
773 encoding format defined by the Internet RFC 1421 Certificate
774 Encoding Standard.
775 If alias refers to a trusted certificate, then that certificate
777 is output. Otherwise, alias refers to a key entry with an
778 associated certificate chain. In that case, the first
779 certificate in the chain is returned. This certificate
780 authenticates the public key of the entity addressed by alias.
781 This command was named -export in earlier releases. The old name
783 is still supported in this release. The new name, -exportcert,
784 is preferred going forward.
785 -list
787 {-alias alias} {-storetype storetype} {-keystore keystore} [-storepass storepass]
789 {-providerName provider_name}
792 {-providerClass provider_class_name {-providerArg provider_arg}}
795 {-v | -rfc} {-protected} {-Jjavaoption}
798 Prints to stdout the contents of the keystore entry identified
802 by alias. If no alias is specified, then the contents of the
803 entire keystore are printed.
804 This command by default prints the SHA1 fingerprint of a
806 certificate. If the -v option is specified, then the certificate
807 is printed in human-readable format, with additional information
808 such as the owner, issuer, serial number, and any extensions. If
809 the -rfc option is specified, then the certificate contents are
810 printed using the printable encoding format, as defined by the
811 Internet RFC 1421 Certificate Encoding Standard.
812 You cannot specify both -v and -rfc.
814 -printcert
816 {-file cert_file | -sslserver host[:port]} {-jarfile JAR_file {-rfc} {-v}
818 {-Jjavaoption}
821 Reads the certificate from the file cert_file, the SSL server
825 located at host:port, or the signed JAR file JAR_file (with the
826 -jarfile option and prints its contents in a human-readable
827 format. When no port is specified, the standard HTTPS port 443
828 is assumed. Note that -sslserver and -file options cannot be
829 provided at the same time. Otherwise, an error is reported. If
830 neither option is specified, then the certificate is read from
831 stdin.
832 When-rfc is specified, the keytool command prints the
834 certificate in PEM mode as defined by the Internet RFC 1421
835 Certificate Encoding standard. See Internet RFC 1421 Certificate
836 Encoding Standard.
837 If the certificate is read from a file or stdin, then it might
839 be either binary encoded or in printable encoding format, as
840 defined by the RFC 1421 Certificate Encoding standard.
841 If the SSL server is behind a firewall, then the -J-
843 Dhttps.proxyHost=proxyhost and -J-Dhttps.proxyPort=proxyport
844 options can be specified on the command line for proxy
845 tunneling. See Java Secure Socket Extension (JSSE) Reference
846 Guide at
847 http://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html
848 Note: This option can be used independently of a keystore.
850 -printcrl
852 -file crl_ {-v}
854 Reads the Certificate Revocation List (CRL) from the file crl_.
858 A CRL is a list of digital certificates that were revoked by the
859 CA that issued them. The CA generates the crl_ file.
860 Note: This option can be used independently of a keystore.
862 -storepasswd
864 [-new new_storepass] {-storetype storetype} {-keystore keystore}
866 [-storepass storepass] {-providerName provider_name}
869 {-providerClass provider_class_name {-providerArg provider_arg}}
872 {-v} {-Jjavaoption}
875 Changes the password used to protect the integrity of the
879 keystore contents. The new password is new_storepass, which must
880 be at least 6 characters.
881 -keypasswd
883 {-alias alias} [-keypass old_keypass] [-new new_keypass] {-storetype storetype}
885 {-keystore keystore} [-storepass storepass] {-providerName provider_name}
888 {-providerClass provider_class_name {-providerArg provider_arg}} {-v}
891 {-Jjavaoption}
894 Changes the password under which the private/secret key
898 identified by alias is protected, from old_keypass to
899 new_keypass, which must be at least 6 characters.
900 If the -keypass option is not provided at the command line, and
902 the key password is different from the keystore password, then
903 the user is prompted for it.
904 If the -new option is not provided at the command line, then the
906 user is prompted for it
907 -delete
909 [-alias alias] {-storetype storetype} {-keystore keystore} [-storepass storepass]
911 {-providerName provider_name}
914 {-providerClass provider_class_name {-providerArg provider_arg}}
917 {-v} {-protected} {-Jjavaoption}
920 Deletes from the keystore the entry identified by alias. The
924 user is prompted for the alias, when no alias is provided at the
925 command line.
926 -changealias
928 {-alias alias} [-destalias destalias] [-keypass keypass] {-storetype storetype}
930 {-keystore keystore} [-storepass storepass] {-providerName provider_name}
933 {-providerClass provider_class_name {-providerArg provider_arg}} {-v}
936 {-protected} {-Jjavaoption}
939 Move an existing keystore entry from the specified alias to a
943 new alias, destalias. If no destination alias is provided, then
944 the command prompts for one. If the original entry is protected
945 with an entry password, then the password can be supplied with
946 the -keypass option. If no key password is provided, then the
947 storepass (if provided) is attempted first. If the attempt
948 fails, then the user is prompted for a password.
949 -help
951 Lists the basic commands and their options.
952 For more information about a specific command, enter the
954 following, where command_name is the name of the command:
955 keytool -command_name -help.
956
958 This example walks through the sequence of steps to create a keystore
959 for managing public/private key pair and certificates from trusted
960 entities.
961 GENERATE THE KEY PAIR
963 First, create a keystore and generate the key pair. You can use a
964 command such as the following typed as a single line:
965 keytool -genkeypair -dname "cn=Mark Jones, ou=Java, o=Oracle, c=US"
967 -alias business -keypass <new password for private key>
968 -keystore /working/mykeystore
969 -storepass <new password for keystore> -validity 180
970 The command creates the keystore named mykeystore in the working
972 directory (assuming it does not already exist), and assigns it the
973 password specified by <new password for keystore>. It generates a
974 public/private key pair for the entity whose distinguished name has a
975 common name of Mark Jones, organizational unit of Java, organization of
976 Oracle and two-letter country code of US. It uses the default DSA key
977 generation algorithm to create the keys; both are 1024 bits.
978 The command uses the default SHA1withDSA signature algorithm to create
980 a self-signed certificate that includes the public key and the
981 distinguished name information. The certificate is valid for 180 days,
982 and is associated with the private key in a keystore entry referred to
983 by the alias business. The private key is assigned the password
984 specified by <new password for private key>.
985 The command is significantly shorter when the option defaults are
987 accepted. In this case, no options are required, and the defaults are
988 used for unspecified options that have default values. You are prompted
989 for any required values. You could have the following:
990 keytool -genkeypair
992 In this case, a keystore entry with the alias mykey is created, with a
994 newly generated key pair and a certificate that is valid for 90 days.
995 This entry is placed in the keystore named .keystore in your home
996 directory. The keystore is created when it does not already exist. You
997 are prompted for the distinguished name information, the keystore
998 password, and the private key password.
999 The rest of the examples assume you executed the -genkeypair command
1001 without options specified, and that you responded to the prompts with
1002 values equal to those specified in the first -genkeypair command. For
1003 example, a distinguished name of cn=Mark Jones, ou=Java, o=Oracle,
1004 c=US).
1005 REQUEST A SIGNED CERTIFICATE FROM A CA
1007 Generating the key pair created a self-signed certificate. A
1008 certificate is more likely to be trusted by others when it is signed by
1009 a Certification Authority (CA). To get a CA signature, first generate a
1010 Certificate Signing Request (CSR), as follows:
1011 keytool -certreq -file MarkJ.csr
1013 This creates a CSR for the entity identified by the default alias mykey
1015 and puts the request in the file named MarkJ.csr. Submit this file to a
1016 CA, such as VeriSign. The CA authenticates you, the requestor (usually
1017 off-line), and returns a certificate, signed by them, authenticating
1018 your public key. In some cases, the CA returns a chain of certificates,
1019 each one authenticating the public key of the signer of the previous
1020 certificate in the chain.
1021 IMPORT A CERTIFICATE FOR THE CA
1023 You now need to replace the self-signed certificate with a certificate
1024 chain, where each certificate in the chain authenticates the public key
1025 of the signer of the previous certificate in the chain, up to a root
1026 CA.
1027 Before you import the certificate reply from a CA, you need one or more
1029 trusted certificates in your keystore or in the cacerts keystore file.
1030 See -importcert in Commands.
1031 · If the certificate reply is a certificate chain, then you need the
1033 top certificate of the chain. The root CA certificate that
1034 authenticates the public key of the CA.
1035 · If the certificate reply is a single certificate, then you need a
1037 certificate for the issuing CA (the one that signed it). If that
1038 certificate is not self-signed, then you need a certificate for its
1039 signer, and so on, up to a self-signed root CA certificate.
1040 The cacerts keystore file ships with several VeriSign root CA
1042 certificates, so you probably will not need to import a VeriSign
1043 certificate as a trusted certificate in your keystore. But if you
1044 request a signed certificate from a different CA, and a certificate
1045 authenticating that CA's public key was not added to cacerts, then you
1046 must import a certificate from the CA as a trusted certificate.
1047 A certificate from a CA is usually either self-signed or signed by
1049 another CA, in which case you need a certificate that authenticates
1050 that CA's public key. Suppose company ABC, Inc., is a CA, and you
1051 obtain a file named ABCCA.cer that is supposed to be a self-signed
1052 certificate from ABC, that authenticates that CA's public key. Be
1053 careful to ensure the certificate is valid before you import it as a
1054 trusted certificate. View it first with the keytool -printcert command
1055 or the keytool -importcert command without the -noprompt option, and
1056 make sure that the displayed certificate fingerprints match the
1057 expected ones. You can call the person who sent the certificate, and
1058 compare the fingerprints that you see with the ones that they show or
1059 that a secure public key repository shows. Only when the fingerprints
1060 are equal is it guaranteed that the certificate was not replaced in
1061 transit with somebody else's (for example, an attacker's) certificate.
1062 If such an attack takes place, and you did not check the certificate
1063 before you imported it, then you would be trusting anything the
1064 attacker has signed.
1065 If you trust that the certificate is valid, then you can add it to your
1067 keystore with the following command:
1068 keytool -importcert -alias abc -file ABCCA.cer
1070 This command creates a trusted certificate entry in the keystore, with
1072 the data from the file ABCCA.cer, and assigns the alias abc to the
1073 entry.
1074 IMPORT THE CERTIFICATE REPLY FROM THE CA
1076 After you import a certificate that authenticates the public key of the
1077 CA you submitted your certificate signing request to (or there is
1078 already such a certificate in the cacerts file), you can import the
1079 certificate reply and replace your self-signed certificate with a
1080 certificate chain. This chain is the one returned by the CA in response
1081 to your request (when the CA reply is a chain), or one constructed
1082 (when the CA reply is a single certificate) using the certificate reply
1083 and trusted certificates that are already available in the keystore
1084 where you import the reply or in the cacerts keystore file.
1085 For example, if you sent your certificate signing request to VeriSign,
1087 then you can import the reply with the following, which assumes the
1088 returned certificate is named VSMarkJ.cer:
1089 keytool -importcert -trustcacerts -file VSMarkJ.cer
1091 EXPORT A CERTIFICATE THAT AUTHENTICATES THE PUBLIC KEY
1094 If you used the jarsigner command to sign a Java Archive (JAR) file,
1095 then clients that want to use the file will want to authenticate your
1096 signature. One way the clients can authenticate you is by first
1097 importing your public key certificate into their keystore as a trusted
1098 entry.
1099 You can export the certificate and supply it to your clients. As an
1101 example, you can copy your certificate to a file named MJ.cer with the
1102 following command that assumes the entry has an alias of mykey:
1103 keytool -exportcert -alias mykey -file MJ.cer
1105 With the certificate and the signed JAR file, a client can use the
1107 jarsigner command to authenticate your signature.
1108 IMPORT KEYSTORE
1110 The command importkeystore is used to import an entire keystore into
1111 another keystore, which means all entries from the source keystore,
1112 including keys and certificates, are all imported to the destination
1113 keystore within a single command. You can use this command to import
1114 entries from a different type of keystore. During the import, all new
1115 entries in the destination keystore will have the same alias names and
1116 protection passwords (for secret keys and private keys). If the keytool
1117 command cannot recover the private keys or secret keys from the source
1118 keystore, then it prompts you for a password. If it detects alias
1119 duplication, then it asks you for a new alias, and you can specify a
1120 new alias or simply allow the keytool command to overwrite the existing
1121 one.
1122 For example, to import entries from a typical JKS type keystore key.jks
1124 into a PKCS #11 type hardware-based keystore, use the command:
1125 keytool -importkeystore
1127 -srckeystore key.jks -destkeystore NONE
1128 -srcstoretype JKS -deststoretype PKCS11
1129 -srcstorepass <src keystore password>
1130 -deststorepass <destination keystore pwd>
1131 The importkeystore command can also be used to import a single entry
1133 from a source keystore to a destination keystore. In this case, besides
1134 the options you see in the previous example, you need to specify the
1135 alias you want to import. With the -srcalias option specified, you can
1136 also specify the destination alias name in the command line, as well as
1137 protection password for a secret/private key and the destination
1138 protection password you want. The following command demonstrates this:
1139 keytool -importkeystore
1141 -srckeystore key.jks -destkeystore NONE
1142 -srcstoretype JKS -deststoretype PKCS11
1143 -srcstorepass <src keystore password>
1144 -deststorepass <destination keystore pwd>
1145 -srcalias myprivatekey -destalias myoldprivatekey
1146 -srckeypass <source entry password>
1147 -destkeypass <destination entry password>
1148 -noprompt
1149 GENERATE CERTIFICATES FOR AN SSL SERVER
1152 The following are keytool commands to generate key pairs and
1153 certificates for three entities: Root CA (root), Intermediate CA (ca),
1154 and SSL server (server). Ensure that you store all the certificates in
1155 the same keystore. In these examples, RSA is the recommended the key
1156 algorithm.
1157 keytool -genkeypair -keystore root.jks -alias root -ext bc:c
1159 keytool -genkeypair -keystore ca.jks -alias ca -ext bc:c
1160 keytool -genkeypair -keystore server.jks -alias server
1161 keytool -keystore root.jks -alias root -exportcert -rfc > root.pem
1162 keytool -storepass <storepass> -keystore ca.jks -certreq -alias ca |
1163 keytool -storepass <storepass> -keystore root.jks
1164 -gencert -alias root -ext BC=0 -rfc > ca.pem
1165 keytool -keystore ca.jks -importcert -alias ca -file ca.pem
1166 keytool -storepass <storepass> -keystore server.jks -certreq -alias server |
1167 keytool -storepass <storepass> -keystore ca.jks -gencert -alias ca
1168 -ext ku:c=dig,kE -rfc > server.pem
1169 cat root.pem ca.pem server.pem |
1170 keytool -keystore server.jks -importcert -alias server
1171
1174 Keystore
1175 A keystore is a storage facility for cryptographic keys and
1176 certificates.
1177 Keystore entries
1179 Keystores can have different types of entries. The two most
1180 applicable entry types for the keytool command include the
1181 following:
1182 Key entries: Each entry holds very sensitive cryptographic key
1184 information, which is stored in a protected format to prevent
1185 unauthorized access. Typically, a key stored in this type of
1186 entry is a secret key, or a private key accompanied by the
1187 certificate chain for the corresponding public key. See
1188 Certificate Chains. The keytool command can handle both types of
1189 entries, while the jarsigner tool only handles the latter type
1190 of entry, that is private keys and their associated certificate
1191 chains.
1192 Trusted certificate entries: Each entry contains a single public
1194 key certificate that belongs to another party. The entry is
1195 called a trusted certificate because the keystore owner trusts
1196 that the public key in the certificate belongs to the identity
1197 identified by the subject (owner) of the certificate. The issuer
1198 of the certificate vouches for this, by signing the certificate.
1199 KeyStore aliases
1201 All keystore entries (key and trusted certificate entries) are
1202 accessed by way of unique aliases.
1203 An alias is specified when you add an entity to the keystore
1205 with the -genseckey command to generate a secret key, the
1206 -genkeypair command to generate a key pair (public and private
1207 key), or the -importcert command to add a certificate or
1208 certificate chain to the list of trusted certificates.
1209 Subsequent keytool commands must use this same alias to refer to
1210 the entity.
1211 For example, you can use the alias duke to generate a new
1213 public/private key pair and wrap the public key into a self-
1214 signed certificate with the following command. See Certificate
1215 Chains.
1216 keytool -genkeypair -alias duke -keypass dukekeypasswd
1218 This example specifies an initial password of dukekeypasswd
1222 required by subsequent commands to access the private key
1223 associated with the alias duke. If you later want to change
1224 Duke's private key password, use a command such as the
1225 following:
1226 keytool -keypasswd -alias duke -keypass dukekeypasswd -new newpass
1228 This changes the password from dukekeypasswd to newpass. A
1232 password should not be specified on a command line or in a
1233 script unless it is for testing purposes, or you are on a secure
1234 system. If you do not specify a required password option on a
1235 command line, then you are prompted for it.
1236 KeyStore implementation
1238 The KeyStore class provided in the java.security package
1239 supplies well-defined interfaces to access and modify the
1240 information in a keystore. It is possible for there to be
1241 multiple different concrete implementations, where each
1242 implementation is that for a particular type of keystore.
1243 Currently, two command-line tools (keytool and jarsigner) and a
1245 GUI-based tool named Policy Tool make use of keystore
1246 implementations. Because the KeyStore class is public, users can
1247 write additional security applications that use it.
1248 There is a built-in default implementation, provided by Oracle.
1250 It implements the keystore as a file with a proprietary keystore
1251 type (format) named JKS. It protects each private key with its
1252 individual password, and also protects the integrity of the
1253 entire keystore with a (possibly different) password.
1254 Keystore implementations are provider-based. More specifically,
1256 the application interfaces supplied by KeyStore are implemented
1257 in terms of a Service Provider Interface (SPI). That is, there
1258 is a corresponding abstract KeystoreSpi class, also in the
1259 java.security package, which defines the Service Provider
1260 Interface methods that providers must implement. The term
1261 provider refers to a package or a set of packages that supply a
1262 concrete implementation of a subset of services that can be
1263 accessed by the Java Security API. To provide a keystore
1264 implementation, clients must implement a provider and supply a
1265 KeystoreSpi subclass implementation, as described in How to
1266 Implement a Provider in the Java Cryptography Architecture at
1267 http://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/HowToImplAProvider.html
1268 Applications can choose different types of keystore
1270 implementations from different providers, using the getInstance
1271 factory method supplied in the KeyStore class. A keystore type
1272 defines the storage and data format of the keystore information,
1273 and the algorithms used to protect private/secret keys in the
1274 keystore and the integrity of the keystore. Keystore
1275 implementations of different types are not compatible.
1276 The keytool command works on any file-based keystore
1278 implementation. It treats the keystore location that is passed
1279 to it at the command line as a file name and converts it to a
1280 FileInputStream, from which it loads the keystore
1281 information.)The jarsigner command can read a keystore from any
1282 location that can be specified with a URL.
1283 For keytool and jarsigner, you can specify a keystore type at
1285 the command line, with the -storetype option. For Policy Tool,
1286 you can specify a keystore type with the Keystore menu.
1287 If you do not explicitly specify a keystore type, then the tools
1289 choose a keystore implementation based on the value of the
1290 keystore.type property specified in the security properties
1291 file. The security properties file is called java.security, and
1292 resides in the security properties directory,
1293 java.home\lib\security on Windows and java.home/lib/security on
1294 Oracle Solaris, where java.home is the runtime environment
1295 directory. The jre directory in the SDK or the top-level
1296 directory of the Java Runtime Environment (JRE).
1297 Each tool gets the keystore.type value and then examines all the
1299 currently installed providers until it finds one that implements
1300 a keystores of that type. It then uses the keystore
1301 implementation from that provider.The KeyStore class defines a
1302 static method named getDefaultType that lets applications and
1303 applets retrieve the value of the keystore.type property. The
1304 following line of code creates an instance of the default
1305 keystore type as specified in the keystore.type property:
1306 KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
1308 The default keystore type is jks, which is the proprietary type
1312 of the keystore implementation provided by Oracle. This is
1313 specified by the following line in the security properties file:
1314 keystore.type=jks
1316 To have the tools utilize a keystore implementation other than
1320 the default, you can change that line to specify a different
1321 keystore type. For example, if you have a provider package that
1322 supplies a keystore implementation for a keystore type called
1323 pkcs12, then change the line to the following:
1324 keystore.type=pkcs12
1326 Note: Case does not matter in keystore type designations. For
1330 example, JKS would be considered the same as jks.
1331 Certificate
1333 A certificate (or public-key certificate) is a digitally signed
1334 statement from one entity (the issuer), saying that the public
1335 key and some other information of another entity (the subject)
1336 has some specific value. The following terms are related to
1337 certificates:
1338 Public Keys: These are numbers associated with a particular
1340 entity, and are intended to be known to everyone who needs to
1341 have trusted interactions with that entity. Public keys are used
1342 to verify signatures.
1343 Digitally Signed: If some data is digitally signed, then it is
1345 stored with the identity of an entity and a signature that
1346 proves that entity knows about the data. The data is rendered
1347 unforgeable by signing with the entity's private key.
1348 Identity: A known way of addressing an entity. In some systems,
1350 the identity is the public key, and in others it can be anything
1351 from an Oracle Solaris UID to an email address to an X.509
1352 distinguished name.
1353 Signature: A signature is computed over some data using the
1355 private key of an entity. The signer, which in the case of a
1356 certificate is also known as the issuer.
1357 Private Keys: These are numbers, each of which is supposed to be
1359 known only to the particular entity whose private key it is
1360 (that is, it is supposed to be kept secret). Private and public
1361 keys exist in pairs in all public key cryptography systems (also
1362 referred to as public key crypto systems). In a typical public
1363 key crypto system, such as DSA, a private key corresponds to
1364 exactly one public key. Private keys are used to compute
1365 signatures.
1366 Entity: An entity is a person, organization, program, computer,
1368 business, bank, or something else you are trusting to some
1369 degree.
1370 Public key cryptography requires access to users' public keys.
1372 In a large-scale networked environment, it is impossible to
1373 guarantee that prior relationships between communicating
1374 entities were established or that a trusted repository exists
1375 with all used public keys. Certificates were invented as a
1376 solution to this public key distribution problem. Now a
1377 Certification Authority (CA) can act as a trusted third party.
1378 CAs are entities such as businesses that are trusted to sign
1379 (issue) certificates for other entities. It is assumed that CAs
1380 only create valid and reliable certificates because they are
1381 bound by legal agreements. There are many public Certification
1382 Authorities, such as VeriSign, Thawte, Entrust, and so on.
1383 You can also run your own Certification Authority using products
1385 such as Microsoft Certificate Server or the Entrust CA product
1386 for your organization. With the keytool command, it is possible
1387 to display, import, and export certificates. It is also possible
1388 to generate self-signed certificates.
1389 The keytool command currently handles X.509 certificates.
1391 X.509 Certificates
1393 The X.509 standard defines what information can go into a
1394 certificate and describes how to write it down (the data
1395 format). All the data in a certificate is encoded with two
1396 related standards called ASN.1/DER. Abstract Syntax Notation 1
1397 describes data. The Definite Encoding Rules describe a single
1398 way to store and transfer that data.
1399 All X.509 certificates have the following data, in addition to
1401 the signature:
1402 Version: This identifies which version of the X.509 standard
1404 applies to this certificate, which affects what information can
1405 be specified in it. Thus far, three versions are defined. The
1406 keytool command can import and export v1, v2, and v3
1407 certificates. It generates v3 certificates.
1408 X.509 Version 1 has been available since 1988, is widely
1410 deployed, and is the most generic.
1411 X.509 Version 2 introduced the concept of subject and issuer
1413 unique identifiers to handle the possibility of reuse of subject
1414 or issuer names over time. Most certificate profile documents
1415 strongly recommend that names not be reused and that
1416 certificates should not make use of unique identifiers. Version
1417 2 certificates are not widely used.
1418 X.509 Version 3 is the most recent (1996) and supports the
1420 notion of extensions where anyone can define an extension and
1421 include it in the certificate. Some common extensions are:
1422 KeyUsage (limits the use of the keys to particular purposes such
1423 as signing-only) and AlternativeNames (allows other identities
1424 to also be associated with this public key, for example. DNS
1425 names, email addresses, IP addresses). Extensions can be marked
1426 critical to indicate that the extension should be checked and
1427 enforced or used. For example, if a certificate has the KeyUsage
1428 extension marked critical and set to keyCertSign, then when this
1429 certificate is presented during SSL communication, it should be
1430 rejected because the certificate extension indicates that the
1431 associated private key should only be used for signing
1432 certificates and not for SSL use.
1433 Serial number: The entity that created the certificate is
1435 responsible for assigning it a serial number to distinguish it
1436 from other certificates it issues. This information is used in
1437 numerous ways. For example, when a certificate is revoked its
1438 serial number is placed in a Certificate Revocation List (CRL).
1439 Signature algorithm identifier: This identifies the algorithm
1441 used by the CA to sign the certificate.
1442 Issuer name: The X.500 Distinguished Name of the entity that
1444 signed the certificate. See X.500 Distinguished Names. This is
1445 typically a CA. Using this certificate implies trusting the
1446 entity that signed this certificate. In some cases, such as root
1447 or top-level CA certificates, the issuer signs its own
1448 certificate.
1449 Validity period: Each certificate is valid only for a limited
1451 amount of time. This period is described by a start date and
1452 time and an end date and time, and can be as short as a few
1453 seconds or almost as long as a century. The validity period
1454 chosen depends on a number of factors, such as the strength of
1455 the private key used to sign the certificate, or the amount one
1456 is willing to pay for a certificate. This is the expected period
1457 that entities can rely on the public value, when the associated
1458 private key has not been compromised.
1459 Subject name: The name of the entity whose public key the
1461 certificate identifies. This name uses the X.500 standard, so it
1462 is intended to be unique across the Internet. This is the X.500
1463 Distinguished Name (DN) of the entity. See X.500 Distinguished
1464 Names. For example,
1465 CN=Java Duke, OU=Java Software Division, O=Oracle Corporation, C=US
1467 These refer to the subject's common name (CN), organizational
1471 unit (OU), organization (O), and country (C).
1472 Subject public key information: This is the public key of the
1474 entity being named with an algorithm identifier that specifies
1475 which public key crypto system this key belongs to and any
1476 associated key parameters.
1477 Certificate Chains
1479 The keytool command can create and manage keystore key entries
1480 that each contain a private key and an associated certificate
1481 chain. The first certificate in the chain contains the public
1482 key that corresponds to the private key.
1483 When keys are first generated, the chain starts off containing a
1485 single element, a self-signed certificate. See -genkeypair in
1486 Commands. A self-signed certificate is one for which the issuer
1487 (signer) is the same as the subject. The subject is the entity
1488 whose public key is being authenticated by the certificate.
1489 Whenever the -genkeypair command is called to generate a new
1490 public/private key pair, it also wraps the public key into a
1491 self-signed certificate.
1492 Later, after a Certificate Signing Request (CSR) was generated
1494 with the -certreq command and sent to a Certification Authority
1495 (CA), the response from the CA is imported with -importcert, and
1496 the self-signed certificate is replaced by a chain of
1497 certificates. See the -certreq and -importcert options in
1498 Commands. At the bottom of the chain is the certificate (reply)
1499 issued by the CA authenticating the subject's public key. The
1500 next certificate in the chain is one that authenticates the CA's
1501 public key.
1502 In many cases, this is a self-signed certificate, which is a
1504 certificate from the CA authenticating its own public key, and
1505 the last certificate in the chain. In other cases, the CA might
1506 return a chain of certificates. In this case, the bottom
1507 certificate in the chain is the same (a certificate signed by
1508 the CA, authenticating the public key of the key entry), but the
1509 second certificate in the chain is a certificate signed by a
1510 different CA that authenticates the public key of the CA you
1511 sent the CSR to. The next certificate in the chain is a
1512 certificate that authenticates the second CA's key, and so on,
1513 until a self-signed root certificate is reached. Each
1514 certificate in the chain (after the first) authenticates the
1515 public key of the signer of the previous certificate in the
1516 chain.
1517 Many CAs only return the issued certificate, with no supporting
1519 chain, especially when there is a flat hierarchy (no
1520 intermediates CAs). In this case, the certificate chain must be
1521 established from trusted certificate information already stored
1522 in the keystore.
1523 A different reply format (defined by the PKCS #7 standard)
1525 includes the supporting certificate chain in addition to the
1526 issued certificate. Both reply formats can be handled by the
1527 keytool command.
1528 The top-level (root) CA certificate is self-signed. However, the
1530 trust into the root's public key does not come from the root
1531 certificate itself, but from other sources such as a newspaper.
1532 This is because anybody could generate a self-signed certificate
1533 with the distinguished name of, for example, the VeriSign root
1534 CA. The root CA public key is widely known. The only reason it
1535 is stored in a certificate is because this is the format
1536 understood by most tools, so the certificate in this case is
1537 only used as a vehicle to transport the root CA's public key.
1538 Before you add the root CA certificate to your keystore, you
1539 should view it with the -printcert option and compare the
1540 displayed fingerprint with the well-known fingerprint obtained
1541 from a newspaper, the root CA's Web page, and so on.
1542 The cacerts Certificates File
1544 A certificates file named cacerts resides in the security
1545 properties directory, java.home\lib\security on Windows and
1546 java.home/lib/security on Oracle Solaris, where java.home is the
1547 runtime environment's directory, which would be the jre
1548 directory in the SDK or the top-level directory of the JRE.
1549 The cacerts file represents a system-wide keystore with CA
1551 certificates. System administrators can configure and manage
1552 that file with the keytool command by specifying jks as the
1553 keystore type. The cacerts keystore file ships with a default
1554 set of root CA certificates. You can list the default
1555 certificates with the following command:
1556 keytool -list -keystore java.home/lib/security/cacerts
1558 The initial password of the cacerts keystore file is changeit.
1562 System administrators should change that password and the
1563 default access permission of that file upon installing the SDK.
1564 Note: It is important to verify your cacerts file. Because you
1566 trust the CAs in the cacerts file as entities for signing and
1567 issuing certificates to other entities, you must manage the
1568 cacerts file carefully. The cacerts file should contain only
1569 certificates of the CAs you trust. It is your responsibility to
1570 verify the trusted root CA certificates bundled in the cacerts
1571 file and make your own trust decisions.
1572 To remove an untrusted CA certificate from the cacerts file, use
1574 the delete option of the keytool command. You can find the
1575 cacerts file in the JRE installation directory. Contact your
1576 system administrator if you do not have permission to edit this
1577 file
1578 Internet RFC 1421 Certificate Encoding Standard
1580 Certificates are often stored using the printable encoding
1581 format defined by the Internet RFC 1421 standard, instead of
1582 their binary encoding. This certificate format, also known as
1583 Base64 encoding, makes it easy to export certificates to other
1584 applications by email or through some other mechanism.
1585 Certificates read by the -importcert and -printcert commands can
1587 be in either this format or binary encoded. The -exportcert
1588 command by default outputs a certificate in binary encoding, but
1589 will instead output a certificate in the printable encoding
1590 format, when the -rfc option is specified.
1591 The -list command by default prints the SHA1 fingerprint of a
1593 certificate. If the -v option is specified, then the certificate
1594 is printed in human-readable format. If the -rfc option is
1595 specified, then the certificate is output in the printable
1596 encoding format.
1597 In its printable encoding format, the encoded certificate is
1599 bounded at the beginning and end by the following text:
1600 -----BEGIN CERTIFICATE-----
1602 encoded certificate goes here.
1603 -----END CERTIFICATE-----
1604 X.500 Distinguished Names
1608 X.500 Distinguished Names are used to identify entities, such as
1609 those that are named by the subject and issuer (signer) fields
1610 of X.509 certificates. The keytool command supports the
1611 following subparts:
1612 commonName: The common name of a person such as Susan Jones.
1614 organizationUnit: The small organization (such as department or
1616 division) name. For example, Purchasing.
1617 localityName: The locality (city) name, for example, Palo Alto.
1619 stateName: State or province name, for example, California.
1621 country: Two-letter country code, for example, CH.
1623 When you supply a distinguished name string as the value of a
1625 -dname option, such as for the -genkeypair command, the string
1626 must be in the following format:
1627 CN=cName, OU=orgUnit, O=org, L=city, S=state, C=countryCode
1629 All the italicized items represent actual values and the
1633 previous keywords are abbreviations for the following:
1634 CN=commonName
1636 OU=organizationUnit
1637 O=organizationName
1638 L=localityName
1639 S=stateName
1640 C=country
1641 A sample distinguished name string is:
1645 CN=Mark Smith, OU=Java, O=Oracle, L=Cupertino, S=California, C=US
1647 A sample command using such a string is:
1651 keytool -genkeypair -dname "CN=Mark Smith, OU=Java, O=Oracle, L=Cupertino,
1653 S=California, C=US" -alias mark
1654 Case does not matter for the keyword abbreviations. For example,
1658 CN, cn, and Cn are all treated the same.
1659 Order matters; each subcomponent must appear in the designated
1661 order. However, it is not necessary to have all the
1662 subcomponents. You can use a subset, for example:
1663 CN=Steve Meier, OU=Java, O=Oracle, C=US
1665 If a distinguished name string value contains a comma, then the
1669 comma must be escaped by a backslash (\) character when you
1670 specify the string on a command line, as in:
1671 cn=Peter Schuster, ou=Java\, Product Development, o=Oracle, c=US
1673 It is never necessary to specify a distinguished name string on
1677 a command line. When the distinguished name is needed for a
1678 command, but not supplied on the command line, the user is
1679 prompted for each of the subcomponents. In this case, a comma
1680 does not need to be escaped by a backslash (\).
1681
1683 IMPORTING TRUSTED CERTIFICATES WARNING
1684 Important: Be sure to check a certificate very carefully before
1685 importing it as a trusted certificate.
1686 Windows Example:
1688 View the certificate first with the -printcert command or the
1690 -importcert command without the -noprompt option. Ensure that the
1691 displayed certificate fingerprints match the expected ones. For
1692 example, suppose sends or emails you a certificate that you put it in a
1693 file named \tmp\cert. Before you consider adding the certificate to
1694 your list of trusted certificates, you can execute a -printcert command
1695 to view its fingerprints, as follows:
1696 keytool -printcert -file \tmp\cert
1698 Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
1699 Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
1700 Serial Number: 59092b34
1701 Valid from: Thu Sep 25 18:01:13 PDT 1997 until: Wed Dec 24 17:01:13 PST 1997
1702 Certificate Fingerprints:
1703 MD5: 11:81:AD:92:C8:E5:0E:A2:01:2E:D4:7A:D7:5F:07:6F
1704 SHA1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE
1705 SHA256: 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90:
1706 17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4
1707 Oracle Solaris Example:
1711 View the certificate first with the -printcert command or the
1713 -importcert command without the -noprompt option. Ensure that the
1714 displayed certificate fingerprints match the expected ones. For
1715 example, suppose someone sends or emails you a certificate that you put
1716 it in a file named /tmp/cert. Before you consider adding the
1717 certificate to your list of trusted certificates, you can execute a
1718 -printcert command to view its fingerprints, as follows:
1719 keytool -printcert -file /tmp/cert
1721 Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
1722 Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
1723 Serial Number: 59092b34
1724 Valid from: Thu Sep 25 18:01:13 PDT 1997 until: Wed Dec 24 17:01:13 PST 1997
1725 Certificate Fingerprints:
1726 MD5: 11:81:AD:92:C8:E5:0E:A2:01:2E:D4:7A:D7:5F:07:6F
1727 SHA1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE
1728 SHA256: 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90:
1729 17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4
1730 Then call or otherwise contact the person who sent the certificate and
1732 compare the fingerprints that you see with the ones that they show.
1733 Only when the fingerprints are equal is it guaranteed that the
1734 certificate was not replaced in transit with somebody else's
1735 certificate such as an attacker's certificate. If such an attack took
1736 place, and you did not check the certificate before you imported it,
1737 then you would be trusting anything the attacker signed, for example, a
1738 JAR file with malicious class files inside.
1739 Note: It is not required that you execute a -printcert command before
1741 importing a certificate. This is because before you add a certificate
1742 to the list of trusted certificates in the keystore, the -importcert
1743 command prints out the certificate information and prompts you to
1744 verify it. You can then stop the import operation. However, you can do
1745 this only when you call the -importcert command without the -noprompt
1746 option. If the -noprompt option is specified, then there is no
1747 interaction with the user.
1748 PASSWORDS WARNING
1750 Most commands that operate on a keystore require the store password.
1751 Some commands require a private/secret key password. Passwords can be
1752 specified on the command line in the -storepass and -keypass options.
1753 However, a password should not be specified on a command line or in a
1754 script unless it is for testing, or you are on a secure system. When
1755 you do not specify a required password option on a command line, you
1756 are prompted for it.
1757 CERTIFICATE CONFORMANCE WARNING
1759 The Internet standard RFC 5280 has defined a profile on conforming
1760 X.509 certificates, which includes what values and value combinations
1761 are valid for certificate fields and extensions. See the standard at
1762 http://tools.ietf.org/rfc/rfc5280.txt
1763 The keytool command does not enforce all of these rules so it can
1765 generate certificates that do not conform to the standard. Certificates
1766 that do not conform to the standard might be rejected by JRE or other
1767 applications. Users should ensure that they provide the correct options
1768 for -dname, -ext, and so on.
1769
1771 IMPORT A NEW TRUSTED CERTIFICATE
1772 Before you add the certificate to the keystore, the keytool command
1773 verifies it by attempting to construct a chain of trust from that
1774 certificate to a self-signed certificate (belonging to a root CA),
1775 using trusted certificates that are already available in the keystore.
1776 If the -trustcacerts option was specified, then additional certificates
1778 are considered for the chain of trust, namely the certificates in a
1779 file named cacerts.
1780 If the keytool command fails to establish a trust path from the
1782 certificate to be imported up to a self-signed certificate (either from
1783 the keystore or the cacerts file), then the certificate information is
1784 printed, and the user is prompted to verify it by comparing the
1785 displayed certificate fingerprints with the fingerprints obtained from
1786 some other (trusted) source of information, which might be the
1787 certificate owner. Be very careful to ensure the certificate is valid
1788 before importing it as a trusted certificate. See Importing Trusted
1789 Certificates Warning. The user then has the option of stopping the
1790 import operation. If the -noprompt option is specified, then there is
1791 no interaction with the user.
1792 IMPORT A CERTIFICATE REPLY
1794 When you import a certificate reply, the certificate reply is validated
1795 with trusted certificates from the keystore, and optionally, the
1796 certificates configured in the cacerts keystore file when the
1797 -trustcacerts option is specified. See The cacerts Certificates File.
1798 The methods of determining whether the certificate reply is trusted are
1800 as follows:
1801 · If the reply is a single X.509 certificate, then the keytool command
1803 attempts to establish a trust chain, starting at the certificate
1804 reply and ending at a self-signed certificate (belonging to a root
1805 CA). The certificate reply and the hierarchy of certificates is used
1806 to authenticate the certificate reply from the new certificate chain
1807 of aliases. If a trust chain cannot be established, then the
1808 certificate reply is not imported. In this case, the keytool command
1809 does not print the certificate and prompt the user to verify it,
1810 because it is very difficult for a user to determine the authenticity
1811 of the certificate reply.
1812 · If the reply is a PKCS #7 formatted certificate chain or a sequence
1814 of X.509 certificates, then the chain is ordered with the user
1815 certificate first followed by zero or more CA certificates. If the
1816 chain ends with a self-signed root CA certificate and the-
1817 trustcacerts option was specified, the keytool command attempts to
1818 match it with any of the trusted certificates in the keystore or the
1819 cacerts keystore file. If the chain does not end with a self-signed
1820 root CA certificate and the -trustcacerts option was specified, the
1821 keytool command tries to find one from the trusted certificates in
1822 the keystore or the cacerts keystore file and add it to the end of
1823 the chain. If the certificate is not found and the -noprompt option
1824 is not specified, the information of the last certificate in the
1825 chain is printed, and the user is prompted to verify it.
1826 If the public key in the certificate reply matches the user's public
1828 key already stored with alias, then the old certificate chain is
1829 replaced with the new certificate chain in the reply. The old chain can
1830 only be replaced with a valid keypass, and so the password used to
1831 protect the private key of the entry is supplied. If no password is
1832 provided, and the private key password is different from the keystore
1833 password, the user is prompted for it.
1834 This command was named -import in earlier releases. This old name is
1836 still supported in this release. The new name, -importcert, is
1837 preferred going forward.
1838
1840 · jar(1)
1841 · jarsigner(1)
1843 · Trail: Security Features in Java SE at
1845 http://docs.oracle.com/javase/tutorial/security/index.html
1846JDK 8 03 March 2015 keytool(1)