1keytool(1) General Commands Manual keytool(1)
2
6 keytool - Key and Certificate Management Tool
7 Manages a keystore (database) of cryptographic keys, X.509 certificate
9 chains, and trusted certificates.
10
12 keytool [ commands ]
13 The keytool command interface has changed in Java SE 6. See the Changes
16 Section for a detailed description. Note that previously defined com‐
17 mands are still supported.
18
20 keytool is a key and certificate management utility. It allows users to
21 administer their own public/private key pairs and associated certifi‐
22 cates for use in self-authentication (where the user authenticates him‐
23 self/herself to other users/services) or data integrity and authentica‐
24 tion services, using digital signatures. It also allows users to cache
25 the public keys (in the form of certificates) of their communicating
26 peers.
27 A certificate is a digitally signed statement from one entity (person,
29 company, etc.), saying that the public key (and some other information)
30 of some other entity has a particular value. (See Certificates.) When
31 data is digitally signed, the signature can be verified to check the
32 data integrity and authenticity. Integrity means that the data has not
33 been modified or tampered with, and authenticity means the data indeed
34 comes from whoever claims to have created and signed it.
35 keytool also enables users to administer secret keys used in symmetric
37 encryption/decryption (e.g. DES).
38 keytool stores the keys and certificates in a keystore.
40
42 The various commands and their options are listed and described below.
43 Note:
44 o All command and option names are preceded by a minus sign (-).
46 o The options for each command may be provided in any order.
48 o All items not italicized or in braces or square brackets are
50 required to appear as is.
51 o Braces surrounding an option generally signify that a default
53 value will be used if the option is not specified on the command
54 line. Braces are also used around the -v, -rfc, and -J options,
55 which only have meaning if they appear on the command line (that
56 is, they don't have any "default" values other than not existing).
57 o Brackets surrounding an option signify that the user is prompted
59 for the value(s) if the option is not specified on the command
60 line. (For a -keypass option, if you do not specify the option on
61 the command line, keytool will first attempt to use the keystore
62 password to recover the private/secret key, and if this fails,
63 will then prompt you for the private/secret key password.)
64 o Items in italics (option values) represent the actual values that
66 must be supplied. For example, here is the format of the -print‐
67 cert command:
68 keytool -printcert {-file cert_file} {-v}
69 When specifying a -printcert command, replace cert_file with the
71 actual file name, as in:
72 keytool -printcert -file VScert.cer
73 o Option values must be quoted if they contain a blank (space).
75 o The -help command is the default. Thus, the command line
77 keytool
78 is equivalent to
80 keytool -help
81 Option Defaults
84 Below are the defaults for various option values.
85 -alias "mykey"
87 -keyalg
89 "DSA" (when using -genkeypair)
90 "DES" (when using -genseckey)
91 -keysize
93 2048 (when using -genkeypair and -keyalg is "RSA")
94 1024 (when using -genkeypair and -keyalg is "DSA")
95 256 (when using -genkeypair and -keyalg is "EC")
96 56 (when using -genseckey and -keyalg is "DES")
97 168 (when using -genseckey and -keyalg is "DESede")
98 -validity 90
101 -keystore the file named .keystore in the user's home directory
103 -storetype the value of the "keystore.type" property in the security properties file,
105 which is returned by the static getDefaultType method in
106 java.security.KeyStore
107 -file stdin if reading, stdout if writing
109 -protected false
111 In generating a public/private key pair, the signature algorithm
114 (-sigalg option) is derived from the algorithm of the underlying pri‐
115 vate key:
116 o If the underlying private key is of type "DSA", the -sigalg option
118 defaults to "SHA1withDSA"
119 o If the underlying private key is of type "RSA", the -sigalg option
121 defaults to "SHA256withRSA".
122 o If the underlying private key is of type "EC", the -sigalg option
124 defaults to "SHA256withECDSA".
125 Please consult the Java Cryptography Architecture API Specification &
128 Reference @
129 http://docs.oracle.com/javase/7/docs/technotes/guides/secu‐
130 rity/crypto/CryptoSpec.html#AppA for a full list of -keyalg and -sigalg
131 you can choose from.
132 Common Options
134 The -v option can appear for all commands except -help. If it appears,
135 it signifies "verbose" mode; more information will be provided in the
136 output.
137 There is also a -Jjavaoption option that may appear for any command. If
139 it appears, the specified javaoption string is passed through directly
140 to the Java interpreter. This option should not contain any spaces. It
141 is useful for adjusting the execution environment or memory usage. For
142 a list of possible interpreter options, type java -h or java -X at the
143 command line.
144 These options may appear for all commands operating on a keystore:
146 -storetype storetype
148 This qualifier specifies the type of keystore to be instantiated.
150 -keystore keystore
152 The keystore location.
154 If the JKS storetype is used and a keystore file does not yet exist,
156 then certain keytool commands may result in a new keystore file
157 being created. For example, if keytool -genkeypair is invoked and
158 the -keystore option is not specified, the default keystore file
159 named .keystore in the user's home directory will be created if it
160 does not already exist. Similarly, if the -keystore ks_file option
161 is specified but ks_file does not exist, then it will be created
162 Note that the input stream from the -keystore option is passed to
164 the KeyStore.load method. If NONE is specified as the URL, then a
165 null stream is passed to the KeyStore.load method. NONE should be
166 specified if the KeyStore is not file-based (for example, if it
167 resides on a hardware token device).
168 -storepass[:env|:file] argument
170 The password which is used to protect the integrity of the keystore.
172 If the modifier env or file is not specified, then the password has
174 the value argument, which must be at least 6 characters long. Other‐
175 wise, the password is retrieved as follows:
176 o env: Retrieve the password from the environment variable named
178 argument
179 o file: Retrieve the password from the file named argument
181 Note: All other options that require passwords, such as -keypass,
183 -srckeypass, -destkeypass -srcstorepass, and -deststorepass, accept
184 the env and file modifiers. (Remember to separate the password
185 option and the modifier with a colon, (:).)
186 The password must be provided to all commands that access the key‐
188 store contents. For such commands, if a -storepass option is not
189 provided at the command line, the user is prompted for it.
190 When retrieving information from the keystore, the password is
192 optional; if no password is given, the integrity of the retrieved
193 information cannot be checked and a warning is displayed.
194 -providerName provider_name
196 Used to identify a cryptographic service provider's name when listed
198 in the security properties file.
199 -providerClass provider_class_name
201 Used to specify the name of cryptographic service provider's master
203 class file when the service provider is not listed in the security
204 properties file.
205 -providerArg provider_arg
207 Used in conjunction with -providerClass. Represents an optional
209 string input argument for the constructor of provider_class_name.
210 -protected
212 Either true or false. This value should be specified as true if a
214 password must be given via a protected authentication path such as a
215 dedicated PIN reader.
216 Note: Since there are two keystores involved in -importkeystore com‐
218 mand, two options, namely, -srcprotected and -destprotected are pro‐
219 vided for the source keystore and the destination keystore respec‐
220 tively.
221 -ext {name{:critical}{=value}}
223 Denotes an X.509 certificate extension. The option can be used in
225 -genkeypair and -gencert to embed extensions into the certificate
226 generated, or in -certreq to show what extensions are requested in
227 the certificate request. The option can appear multiple times. name
228 can be a supported extension name (see below) or an arbitrary OID
229 number. value, if provided, denotes the parameter for the extension;
230 if omitted, denotes the default value (if defined) of the extension
231 or the extension requires no parameter. The :critical modifier, if
232 provided, means the extension's isCritical attribute is true; other‐
233 wise, false. You may use :c in place of :critical.
234 Currently keytool supports these named extensions (case-insensitive):
237 For name as OID, value is the HEX dumped DER encoding of the extnValue
239 for the extension excluding the OCTET STRING type and length bytes. Any
240 extra character other than standard HEX numbers (0-9, a-f, A-F) are
241 ignored in the HEX string. Therefore, both "01:02:03:04" and "01020304"
242 are accepted as identical values. If there is no value, the extension
243 has an empty value field then.
244 A special name 'honored', used in -gencert only, denotes how the exten‐
246 sions included in the certificate request should be honored. The value
247 for this name is a comma separated list of "all" (all requested exten‐
248 sions are honored), "name{:[critical|non-critical]}" (the named exten‐
249 sion is honored, but using a different isCritical attribute) and
250 "-name" (used with all, denotes an exception). Requested extensions are
251 not honored by default.
252 If, besides the -ext honored option, another named or OID -ext option
254 is provided, this extension will be added to those already honored.
255 However, if this name (or OID) also appears in the honored value, its
256 value and criticality overrides the one in the request.
257 The subjectKeyIdentifier extension is always created. For non
259 self-signed certificates, the authorityKeyIdentifier is always created.
260 Note: Users should be aware that some combinations of extensions (and
262 other certificate fields) may not conform to the Internet standard. See
263 Warning Regarding Certificate Conformance for details.
264
266 Creating or Adding Data to the Keystore
267 -gencert {-rfc} {-infile infile} {-outfile outfile} {-alias alias}
268 {-sigalg sigalg} {-dname dname} {-startdate startdate {-ext ext}*
269 {-validity valDays} [-keypass keypass] {-keystore keystore}
270 [-storepass storepass] {-storetype storetype} {-providername
271 provider_name} {-providerClass provider_class_name {-providerArg
272 provider_arg}} {-v} {-protected} {-Jjavaoption}
273 Generates a certificate as a response to a certificate request file
275 (which can be created by the keytool -certreq command). The command
276 reads the request from infile (if omitted, from the standard input),
277 signs it using alias's private key, and output the X.509 certificate
278 into outfile (if omitted, to the standard output). If -rfc is speci‐
279 fied, output format is BASE64-encoded PEM; otherwise, a binary DER
280 is created.
281 sigalg specifies the algorithm that should be used to sign the cer‐
283 tificate. startdate is the start time/date that the certificate is
284 valid. valDays tells the number of days for which the certificate
285 should be considered valid.
286 If dname is provided, it's used as the subject of the generated cer‐
288 tificate. Otherwise, the one from the certificate request is used.
289 ext shows what X.509 extensions will be embedded in the certificate.
291 Read Common Options for the grammar of -ext.
292 The -gencert command enables you to create certificate chains. The
294 following example creates a certificate, e1, that contains three
295 certificates in its certificate chain.
296 The following commands creates four key pairs named ca, ca1, ca2,
298 and e1:
299 keytool -alias ca -dname CN=CA -genkeypair
300 keytool -alias ca1 -dname CN=CA -genkeypair
301 keytool -alias ca2 -dname CN=CA -genkeypair
302 keytool -alias e1 -dname CN=E1 -genkeypair
303 The following two commands create a chain of signed certificates; ca
305 signs ca1 and ca1 signs ca2, all of which are self-issued:
306 keytool -alias ca1 -certreq | keytool -alias ca -gencert -ext san=dns:ca1 | keytool -alias ca1 -importcert
307 keytool -alias ca2 -certreq | $KT -alias ca1 -gencert -ext san=dns:ca2 | $KT -alias ca2 -importcert
308 The following command creates the certificate e1 and stores it in
310 the file e1.cert, which is signed by ca2. As a result, e1 should
311 contain ca, ca1, and ca2 in its certificate chain:
312 keytool -alias e1 -certreq | keytool -alias ca2 -gencert > e1.cert
313 -genkeypair {-alias alias} {-keyalg keyalg} {-keysize keysize}
315 {-sigalg sigalg} [-dname dname] [-keypass keypass] {-startdate
316 value} {-ext ext}* {-validity valDays} {-storetype storetype} {-key‐
317 store keystore} [-storepass storepass] {-providerClass
318 provider_class_name {-providerArg provider_arg}} {-v} {-protected}
319 {-Jjavaoption}
320 Generates a key pair (a public key and associated private key).
322 Wraps the public key into an X.509 v3 self-signed certificate, which
323 is stored as a single-element certificate chain. This certificate
324 chain and the private key are stored in a new keystore entry identi‐
325 fied by alias.
326 keyalg specifies the algorithm to be used to generate the key pair,
328 and keysize specifies the size of each key to be generated. sigalg
329 specifies the algorithm that should be used to sign the self-signed
330 certificate; this algorithm must be compatible with keyalg.
331 dname specifies the X.500 Distinguished Name to be associated with
333 alias, and is used as the issuer and subject fields in the
334 self-signed certificate. If no distinguished name is provided at the
335 command line, the user will be prompted for one.
336 keypass is a password used to protect the private key of the gener‐
338 ated key pair. If no password is provided, the user is prompted for
339 it. If you press RETURN at the prompt, the key password is set to
340 the same password as that used for the keystore. keypass must be at
341 least 6 characters long.
342 startdate specifies the issue time of the certificate, also known as
344 the "Not Before" value of the X.509 certificate's Validity field.
345 The option value can be set in one of these two forms:
347 1. ([+-]nnn[ymdHMS])+
349 2. [yyyy/mm/dd] [HH:MM:SS]
351 With the first form, the issue time is shifted by the specified
353 value from the current time. The value is a concatenation of a
354 sequence of sub values. Inside each sub value, the plus sign ("+")
355 means shifting forward, and the minus sign ("-") means shifting
356 backward. The time to be shifted is nnn units of years, months,
357 days, hours, minutes, or seconds (denoted by a single character of
358 "y", "m", "d", "H", "M", or "S" respectively). The exact value of
359 the issue time is calculated using the java.util.GregorianCalen‐
360 dar.add(int field, int amount) method on each sub value, from left
361 to right. For example, by specifying "-startdate -1y+1m-1d", the
362 issue time will be:
363 Calendar c = new GregorianCalendar();
364 c.add(Calendar.YEAR, -1);
365 c.add(Calendar.MONTH, 1);
366 c.add(Calendar.DATE, -1);
367 return c.getTime()
368 With the second form, the user sets the exact issue time in two
370 parts, year/month/day and hour:minute:second (using the local time
371 zone). The user may provide only one part, which means the other
372 part is the same as the current date (or time). User must provide
373 the exact number of digits as shown in the format definition (pad‐
374 ding with 0 if shorter). When both the date and time are provided,
375 there is one (and only one) space character between the two parts.
376 The hour should always be provided in 24 hour format.
377 When the option is not provided, the start date is the current time.
379 The option can be provided at most once.
380 valDays specifies the number of days (starting at the date specified
382 by -startdate, or the current date if -startdate is not specified)
383 for which the certificate should be considered valid.
384 This command was named -genkey in previous releases. This old name
386 is still supported in this release and will be supported in future
387 releases, but for clarity the new name, -genkeypair, is preferred
388 going forward.
389 -genseckey {-alias alias} {-keyalg keyalg} {-keysize keysize} [-key‐
391 pass keypass] {-storetype storetype} {-keystore keystore}
392 [-storepass storepass] {-providerClass provider_class_name
393 {-providerArg provider_arg}} {-v} {-protected} {-Jjavaoption}
394 Generates a secret key and stores it in a new KeyStore.SecretKeyEn‐
396 try identified by alias.
397 keyalg specifies the algorithm to be used to generate the secret
399 key, and keysize specifies the size of the key to be generated. key‐
400 pass is a password used to protect the secret key. If no password is
401 provided, the user is prompted for it. If you press RETURN at the
402 prompt, the key password is set to the same password as that used
403 for the keystore. keypass must be at least 6 characters long.
404 -importcert {-alias alias} {-file cert_file} [-keypass keypass]
406 {-noprompt} {-trustcacerts} {-storetype storetype} {-keystore key‐
407 store} [-storepass storepass] {-providerName provider_name}
408 {-providerClass provider_class_name {-providerArg provider_arg}}
409 {-v} {-protected} {-Jjavaoption}
410 Reads the certificate or certificate chain (where the latter is sup‐
412 plied in a PKCS#7 formatted reply or a sequence of X.509 certifi‐
413 cates) from the file cert_file, and stores it in the keystore entry
414 identified by alias. If no file is given, the certificate or cer‐
415 tificate chain is read from stdin.
416 keytool can import X.509 v1, v2, and v3 certificates, and PKCS#7
418 formatted certificate chains consisting of certificates of that
419 type. The data to be imported must be provided either in binary
420 encoding format, or in printable encoding format (also known as
421 Base64 encoding) as defined by the Internet RFC 1421 standard. In
422 the latter case, the encoding must be bounded at the beginning by a
423 string that starts with "-----BEGIN", and bounded at the end by a
424 string that starts with "-----END".
425 You import a certificate for two reasons:
427 1. to add it to the list of trusted certificates, or
429 2. to import a certificate reply received from a CA as the result
431 of submitting a Certificate Signing Request (see the -certreq
432 command) to that CA.
433 Which type of import is intended is indicated by the value of the
435 -alias option:
436 1. If the alias does not point to a key entry, then keytool
438 assumes you are adding a trusted certificate entry. In this
439 case, the alias should not already exist in the keystore. If
440 the alias does already exist, then keytool outputs an error,
441 since there is already a trusted certificate for that alias,
442 and does not import the certificate.
443 2. If the alias points to a key entry, then keytool assumes you
445 are importing a certificate reply.
446 Importing a New Trusted Certificate
447 Before adding the certificate to the keystore, keytool tries to ver‐
449 ify it by attempting to construct a chain of trust from that cer‐
450 tificate to a self-signed certificate (belonging to a root CA),
451 using trusted certificates that are already available in the key‐
452 store.
453 If the -trustcacerts option has been specified, additional certifi‐
455 cates are considered for the chain of trust, namely the certificates
456 in a file named "cacerts".
457 If keytool fails to establish a trust path from the certificate to
459 be imported up to a self-signed certificate (either from the key‐
460 store or the "cacerts" file), the certificate information is printed
461 out, and the user is prompted to verify it, e.g., by comparing the
462 displayed certificate fingerprints with the fingerprints obtained
463 from some other (trusted) source of information, which might be the
464 certificate owner himself/herself. Be very careful to ensure the
465 certificate is valid prior to importing it as a "trusted" certifi‐
466 cate! -- see WARNING Regarding Importing Trusted Certificates. The
467 user then has the option of aborting the import operation. If the
468 -noprompt option is given, however, there will be no interaction
469 with the user. Importing a Certificate Reply
470 When importing a certificate reply, the certificate reply is vali‐
472 dated using trusted certificates from the keystore, and optionally
473 using the certificates configured in the "cacerts" keystore file (if
474 the -trustcacerts option was specified).
475 The methods of determining whether the certificate reply is trusted
477 are described in the following:
478 o If the reply is a single X.509 certificate, keytool attempts to
480 establish a trust chain, starting at the certificate reply and
481 ending at a self-signed certificate (belonging to a root CA).
482 The certificate reply and the hierarchy of certificates used to
483 authenticate the certificate reply form the new certificate
484 chain of alias. If a trust chain cannot be established, the
485 certificate reply is not imported. In this case, keytool does
486 not print out the certificate and prompt the user to verify it,
487 because it is very hard (if not impossible) for a user to
488 determine the authenticity of the certificate reply.
489 o If the reply is a PKCS#7 formatted certificate chain or a
491 sequence of X.509 certificates, the chain is ordered with the
492 user certificate first followed by zero or more CA certifi‐
493 cates. If the chain ends with a self-signed root CA certificate
494 and -trustcacerts option was specified, keytool will attempt to
495 match it with any of the trusted certificates in the keystore
496 or the "cacerts" keystore file. If the chain does not end with
497 a self-signed root CA certificate and the -trustcacerts option
498 was specified, keytool will try to find one from the trusted
499 certificates in the keystore or the "cacerts" keystore file and
500 add it to the end of the chain. If the certificate is not found
501 and -noprompt option is not specified, the information of the
502 last certificate in the chain is printed out, and the user is
503 prompted to verify it.
504 If the public key in the certificate reply matches the user's public
506 key already stored with under alias, the old certificate chain is
507 replaced with the new certificate chain in the reply. The old chain
508 can only be replaced if a valid keypass, the password used to pro‐
509 tect the private key of the entry, is supplied. If no password is
510 provided, and the private key password is different from the key‐
511 store password, the user is prompted for it.
512 This command was named -import in previous releases. This old name
514 is still supported in this release and will be supported in future
515 releases, but for clarify the new name, -importcert, is preferred
516 going forward.
517 -importkeystore -srckeystore srckeystore -destkeystore destkeystore
519 {-srcstoretype srcstoretype} {-deststoretype deststoretype} [-src‐
520 storepass srcstorepass] [-deststorepass deststorepass] {-srcpro‐
521 tected} {-destprotected} {-srcalias srcalias {-destalias destalias}
522 [-srckeypass srckeypass] [-destkeypass destkeypass] } {-noprompt}
523 {-srcProviderName src_provider_name} {-destProviderName
524 dest_provider_name} {-providerClass provider_class_name {-provider‐
525 Arg provider_arg}} {-v} {-protected} {-Jjavaoption}
526 Imports a single entry or all entries from a source keystore to a
528 destination keystore.
529 When the srcalias option is provided, the command imports the single
531 entry identified by the alias to the destination keystore. If a des‐
532 tination alias is not provided with destalias, then srcalias is used
533 as the destination alias. If the source entry is protected by a
534 password, srckeypass will be used to recover the entry. If srckey‐
535 pass is not provided, then keytool will attempt to use srcstorepass
536 to recover the entry. If srcstorepass is either not provided or is
537 incorrect, the user will be prompted for a password. The destination
538 entry will be protected using destkeypass. If destkeypass is not
539 provided, the destination entry will be protected with the source
540 entry password.
541 If the srcalias option is not provided, then all entries in the
543 source keystore are imported into the destination keystore. Each
544 destination entry will be stored under the alias from the source
545 entry. If the source entry is protected by a password, srcstorepass
546 will be used to recover the entry. If srcstorepass is either not
547 provided or is incorrect, the user will be prompted for a password.
548 If a source keystore entry type is not supported in the destination
549 keystore, or if an error occurs while storing an entry into the des‐
550 tination keystore, the user will be prompted whether to skip the
551 entry and continue, or to quit. The destination entry will be pro‐
552 tected with the source entry password.
553 If the destination alias already exists in the destination keystore,
555 the user is prompted to either overwrite the entry, or to create a
556 new entry under a different alias name.
557 Note that if -noprompt is provided, the user will not be prompted
559 for a new destination alias. Existing entries will automatically be
560 overwritten with the destination alias name. Finally, entries that
561 can not be imported are automatically skipped and a warning is out‐
562 put.
563 -printcertreq {-file file}
565 Prints the content of a PKCS #10 format certificate request, which
567 can be generated by the keytool -certreq command. The command reads
568 the request from file; if omitted, from the standard input.
569 Exporting Data
572 -certreq {-alias alias} {-dname dname} {-sigalg sigalg} {-file
573 certreq_file} [-keypass keypass] {-storetype storetype} {-keystore
574 keystore} [-storepass storepass] {-providerName provider_name}
575 {-providerClass provider_class_name {-providerArg provider_arg}}
576 {-v} {-protected} {-Jjavaoption}
577 Generates a Certificate Signing Request (CSR), using the PKCS#10
579 format.
580 A CSR is intended to be sent to a certificate authority (CA). The CA
582 will authenticate the certificate requestor (usually off-line) and
583 will return a certificate or certificate chain, used to replace the
584 existing certificate chain (which initially consists of a
585 self-signed certificate) in the keystore.
586 The private key associated with alias is used to create the PKCS#10
588 certificate request. In order to access the private key, the appro‐
589 priate password must be provided, since private keys are protected
590 in the keystore with a password. If keypass is not provided at the
591 command line, and is different from the password used to protect the
592 integrity of the keystore, the user is prompted for it. If dname is
593 provided, it's used as the subject in the CSR. Otherwise, the X.500
594 Distinguished Name associated with alias is used.
595 sigalg specifies the algorithm that should be used to sign the CSR.
597 The CSR is stored in the file certreq_file. If no file is given, the
599 CSR is output to stdout.
600 Use the importcert command to import the response from the CA.
602 -exportcert {-alias alias} {-file cert_file} {-storetype storetype}
604 {-keystore keystore} [-storepass storepass] {-providerName
605 provider_name} {-providerClass provider_class_name {-providerArg
606 provider_arg}} {-rfc} {-v} {-protected} {-Jjavaoption}
607 Reads (from the keystore) the certificate associated with alias, and
609 stores it in the file cert_file.
610 If no file is given, the certificate is output to stdout.
612 The certificate is by default output in binary encoding, but will
614 instead be output in the printable encoding format, as defined by
615 the Internet RFC 1421 standard, if the -rfc option is specified.
616 If alias refers to a trusted certificate, that certificate is out‐
618 put. Otherwise, alias refers to a key entry with an associated cer‐
619 tificate chain. In that case, the first certificate in the chain is
620 returned. This certificate authenticates the public key of the
621 entity addressed by alias.
622 This command was named -export in previous releases. This old name
624 is still supported in this release and will be supported in future
625 releases, but for clarify the new name, -exportcert, is preferred
626 going forward.
627 Displaying Data
630 -list {-alias alias} {-storetype storetype} {-keystore keystore}
631 [-storepass storepass] {-providerName provider_name} {-providerClass
632 provider_class_name {-providerArg provider_arg}} {-v | -rfc} {-pro‐
633 tected} {-Jjavaoption}
634 Prints (to stdout) the contents of the keystore entry identified by
636 alias. If no alias is specified, the contents of the entire keystore
637 are printed.
638 This command by default prints the SHA1 fingerprint of a certifi‐
640 cate. If the -v option is specified, the certificate is printed in
641 human-readable format, with additional information such as the
642 owner, issuer, serial number, and any extensions. If the -rfc option
643 is specified, certificate contents are printed using the printable
644 encoding format, as defined by the Internet RFC 1421 standard
645 You cannot specify both -v and -rfc.
647 -printcert {-file cert_file | -sslserver host[:port]} {-jarfile
649 JAR_file {-rfc} {-v} {-Jjavaoption}
650 Reads the certificate from the file cert_file, the SSL server
652 located at host:port, or the signed JAR file JAR_file (with the
653 option -jarfile and prints its contents in a human-readable format.
654 When no port is specified, the standard HTTPS port 443 is assumed.
655 Note that -sslserver and -file options cannot be provided at the
656 same time. Otherwise, an error is reported. If neither option is
657 given, the certificate is read from stdin.
658 If -rfc is specified, keytool prints the certificate in PEM mode as
660 defined by the Internet RFC 1421 standard.
661 If the certificate is read from a file or stdin, it may be either
663 binary encoded or in printable encoding format, as defined by the
664 Internet RFC 1421 standard
665 If the SSL server is behind a firewall, -J-Dhttps.proxyHost=proxy‐
667 host and -J-Dhttps.proxyPort=proxyport can be specified on the com‐
668 mand line for proxy tunneling. See the JSSE Reference Guide @
669 http://docs.oracle.com/javase/7/docs/technotes/guides/secu‐
670 rity/jsse/JSSERefGuide.html for more information.
671 Note: This option can be used independently of a keystore.
673 -printcrl -file crl_ {-v}
675 Reads the certificate revocation list (CRL) from the file crl_file.
677 A Certificate Revocation List (CRL) is a list of digital certifi‐
679 cates which have been revoked by the Certificate Authority (CA) that
680 issued them. The CA generates crl_file.
681 Note: This option can be used independently of a keystore.
683 Managing the Keystore
686 -storepasswd [-new new_storepass] {-storetype storetype} {-keystore
687 keystore} [-storepass storepass] {-providerName provider_name}
688 {-providerClass provider_class_name {-providerArg provider_arg}}
689 {-v} {-Jjavaoption}
690 Changes the password used to protect the integrity of the keystore
692 contents. The new password is new_storepass, which must be at least
693 6 characters long.
694 -keypasswd {-alias alias} [-keypass old_keypass] [-new new_keypass]
696 {-storetype storetype} {-keystore keystore} [-storepass storepass]
697 {-providerName provider_name} {-providerClass provider_class_name
698 {-providerArg provider_arg}} {-v} {-Jjavaoption}
699 Changes the password under which the private/secret key identified
701 by alias is protected, from old_keypass to new_keypass, which must
702 be at least 6 characters long.
703 If the -keypass option is not provided at the command line, and the
705 key password is different from the keystore password, the user is
706 prompted for it.
707 If the -new option is not provided at the command line, the user is
709 prompted for it.
710 -delete [-alias alias] {-storetype storetype} {-keystore keystore}
712 [-storepass storepass] {-providerName provider_name} {-providerClass
713 provider_class_name {-providerArg provider_arg}} {-v} {-protected}
714 {-Jjavaoption}
715 Deletes from the keystore the entry identified by alias. The user is
717 prompted for the alias, if no alias is provided at the command line.
718 -changealias {-alias alias} [-destalias destalias] [-keypass key‐
720 pass] {-storetype storetype} {-keystore keystore} [-storepass
721 storepass] {-providerName provider_name} {-providerClass
722 provider_class_name {-providerArg provider_arg}} {-v} {-protected}
723 {-Jjavaoption}
724 Move an existing keystore entry from the specified alias to a new
726 alias, destalias. If no destination alias is provided, the command
727 will prompt for one. If the original entry is protected with an
728 entry password, the password can be supplied via the "-keypass"
729 option. If no key password is provided, the storepass (if given)
730 will be attempted first. If that attempt fails, the user will be
731 prompted for a password.
732 Getting Help
735 -help
736 Lists the basic commands and their options.
738 For more information about a specific command, enter the following,
740 where command_name is the name of the command:
741 keytool -command_name -help
742
745 Suppose you want to create a keystore for managing your public/private
746 key pair and certificates from entities you trust.
747 Generating Your Key Pair
749 The first thing you need to do is create a keystore and generate the
750 key pair. You could use a command such as the following:
751 keytool -genkeypair -dname "cn=Mark Jones, ou=Java, o=Oracle, c=US"
753 -alias business -keypass <new password for private key> -keystore /working/mykeystore
754 -storepass <new password for keystore> -validity 180
755 (Please note: This must be typed as a single line. Multiple lines are
758 used in the examples just for legibility purposes.)
759 This command creates the keystore named "mykeystore" in the "working"
761 directory (assuming it doesn't already exist), and assigns it the pass‐
762 word specified by <new password for keystore>. It generates a pub‐
763 lic/private key pair for the entity whose "distinguished name" has a
764 common name of "Mark Jones", organizational unit of "Java", organiza‐
765 tion of "Oracle" and two-letter country code of "US". It uses the
766 default "DSA" key generation algorithm to create the keys, both 1024
767 bits long.
768 It creates a self-signed certificate (using the default "SHA1withDSA"
770 signature algorithm) that includes the public key and the distinguished
771 name information. This certificate will be valid for 180 days, and is
772 associated with the private key in a keystore entry referred to by the
773 alias "business". The private key is assigned the password specified by
774 <new password for private key>.
775 The command could be significantly shorter if option defaults were
777 accepted. As a matter of fact, no options are required; defaults are
778 used for unspecified options that have default values, and you are
779 prompted for any required values. Thus, you could simply have the fol‐
780 lowing:
781 keytool -genkeypair
783 In this case, a keystore entry with alias "mykey" is created, with a
786 newly-generated key pair and a certificate that is valid for 90 days.
787 This entry is placed in the keystore named ".keystore" in your home
788 directory. (The keystore is created if it doesn't already exist.) You
789 will be prompted for the distinguished name information, the keystore
790 password, and the private key password.
791 The rest of the examples assume you executed the -genkeypair command
793 without options specified, and that you responded to the prompts with
794 values equal to those given in the first -genkeypair command, above
795 (for example, a distinguished name of "cn=Mark Jones, ou=Java, o=Ora‐
796 cle, c=US").
797 Requesting a Signed Certificate from a Certification Authority
799 So far all we've got is a self-signed certificate. A certificate is
800 more likely to be trusted by others if it is signed by a Certification
801 Authority (CA). To get such a signature, you first generate a Certifi‐
802 cate Signing Request (CSR), via the following:
803 keytool -certreq -file MarkJ.csr
805 This creates a CSR (for the entity identified by the default alias
808 "mykey") and puts the request in the file named "MarkJ.csr". Submit
809 this file to a CA, such as VeriSign, Inc. The CA will authenticate you,
810 the requestor (usually off-line), and then will return a certificate,
811 signed by them, authenticating your public key. (In some cases, they
812 will actually return a chain of certificates, each one authenticating
813 the public key of the signer of the previous certificate in the chain.)
814 Importing a Certificate for the CA
816 You need to replace your self-signed certificate with a certificate
817 chain, where each certificate in the chain authenticates the public key
818 of the signer of the previous certificate in the chain, up to a "root"
819 CA.
820 Before you import the certificate reply from a CA, you need one or more
822 "trusted certificates" in your keystore or in the cacerts keystore file
823 (which is described in importcert command):
824 o If the certificate reply is a certificate chain, you just need the
826 top certificate of the chain (that is, the "root" CA certificate
827 authenticating that CA's public key).
828 o If the certificate reply is a single certificate, you need a cer‐
830 tificate for the issuing CA (the one that signed it), and if that
831 certificate is not self-signed, you need a certificate for its
832 signer, and so on, up to a self-signed "root" CA certificate.
833 The "cacerts" keystore file ships with several VeriSign root CA cer‐
836 tificates, so you probably won't need to import a VeriSign certificate
837 as a trusted certificate in your keystore. But if you request a signed
838 certificate from a different CA, and a certificate authenticating that
839 CA's public key hasn't been added to "cacerts", you will need to import
840 a certificate from the CA as a "trusted certificate".
841 A certificate from a CA is usually either self-signed, or signed by
843 another CA (in which case you also need a certificate authenticating
844 that CA's public key). Suppose company ABC, Inc., is a CA, and you
845 obtain a file named "ABCCA.cer" that is purportedly a self-signed cer‐
846 tificate from ABC, authenticating that CA's public key.
847 Be very careful to ensure the certificate is valid prior to importing
849 it as a "trusted" certificate! View it first (using the keytool -print‐
850 cert command, or the keytool -importcert command without the -noprompt
851 option), and make sure that the displayed certificate fingerprint(s)
852 match the expected ones. You can call the person who sent the certifi‐
853 cate, and compare the fingerprint(s) that you see with the ones that
854 they show (or that a secure public key repository shows). Only if the
855 fingerprints are equal is it guaranteed that the certificate has not
856 been replaced in transit with somebody else's (for example, an
857 attacker's) certificate. If such an attack took place, and you did not
858 check the certificate before you imported it, you would end up trusting
859 anything the attacker has signed.
860 If you trust that the certificate is valid, then you can add it to your
862 keystore via the following:
863 keytool -importcert -alias abc -file ABCCA.cer
865 This creates a "trusted certificate" entry in the keystore, with the
868 data from the file "ABCCA.cer", and assigns the alias "abc" to the
869 entry.
870 Importing the Certificate Reply from the CA
872 Once you've imported a certificate authenticating the public key of the
873 CA you submitted your certificate signing request to (or there is
874 already such a certificate in the "cacerts" file), you can import the
875 certificate reply and thereby replace your self-signed certificate with
876 a certificate chain. This chain is the one returned by the CA in
877 response to your request (if the CA reply is a chain), or one con‐
878 structed (if the CA reply is a single certificate) using the certifi‐
879 cate reply and trusted certificates that are already available in the
880 keystore where you import the reply or in the "cacerts" keystore file.
881 For example, suppose you sent your certificate signing request to
883 VeriSign. You can then import the reply via the following, which
884 assumes the returned certificate is named "VSMarkJ.cer":
885 keytool -importcert -trustcacerts -file VSMarkJ.cer
887 Exporting a Certificate Authenticating Your Public Key
890 Suppose you have used the jarsigner(1) tool to sign a Java ARchive
891 (JAR) file. Clients that want to use the file will want to authenticate
892 your signature.
893 One way they can do this is by first importing your public key certifi‐
895 cate into their keystore as a "trusted" entry. You can export the cer‐
896 tificate and supply it to your clients. As an example, you can copy
897 your certificate to a file named MJ.cer via the following, assuming the
898 entry is aliased by "mykey":
899 keytool -exportcert -alias mykey -file MJ.cer
901 Given that certificate, and the signed JAR file, a client can use the
904 jarsigner tool to authenticate your signature.
905 Importing Keystore
907 The command "importkeystore" is used to import an entire keystore into
908 another keystore, which means all entries from the source keystore,
909 including keys and certificates, are all imported to the destination
910 keystore within a single command. You can use this command to import
911 entries from a different type of keystore. During the import, all new
912 entries in the destination keystore will have the same alias names and
913 protection passwords (for secret keys and private keys). If keytool has
914 difficulties recover the private keys or secret keys from the source
915 keystore, it will prompt you for a password. If it detects alias dupli‐
916 cation, it will ask you for a new one, you can specify a new alias or
917 simply allow keytool to overwrite the existing one.
918 For example, to import entries from a normal JKS type keystore key.jks
920 into a PKCS #11 type hardware based keystore, you can use the command:
921 keytool -importkeystore
923 -srckeystore key.jks -destkeystore NONE
924 -srcstoretype JKS -deststoretype PKCS11
925 -srcstorepass <source keystore password> -deststorepass <destination keystore password>
926 The importkeystore command can also be used to import a single entry
929 from a source keystore to a destination keystore. In this case, besides
930 the options you see in the above example, you need to specify the alias
931 you want to import. With the srcalias option given, you can also spec‐
932 ify the destination alias name in the command line, as well as protec‐
933 tion password for a secret/private key and the destination protection
934 password you want. The following command demonstrates this:
935 keytool -importkeystore
937 -srckeystore key.jks -destkeystore NONE
938 -srcstoretype JKS -deststoretype PKCS11
939 -srcstorepass <source keystore password> -deststorepass <destination keystore password>
940 -srcalias myprivatekey -destalias myoldprivatekey
941 -srckeypass <source entry password> -destkeypass <destination entry password>
942 -noprompt
943 Generating Certificates for a Typical SSL Server
946 The following are keytool commands to generate keypairs and certifi‐
947 cates for three entities, namely, Root CA (root), Intermediate CA (ca),
948 and SSL server (server). Ensure that you store all the certificates in
949 the same keystore. In these examples, it is recommended that you spec‐
950 ify RSA as the key algorithm.
951 keytool -genkeypair -keystore root.jks -alias root -ext bc:c
953 keytool -genkeypair -keystore ca.jks -alias ca -ext bc:c
954 keytool -genkeypair -keystore server.jks -alias server
955 keytool -keystore root.jks -alias root -exportcert -rfc > root.pem
957 keytool -storepass <storepass> -keystore ca.jks -certreq -alias ca | keytool -storepass <storepass> -keystore root.jks -gencert -alias root -ext BC=0 -rfc > ca.pem
959 keytool -keystore ca.jks -importcert -alias ca -file ca.pem
960 keytool -storepass <storepass> -keystore server.jks -certreq -alias server | keytool -storepass <storepass> -keystore ca.jks -gencert -alias ca -ext ku:c=dig,kE -rfc > server.pem
962 cat root.pem ca.pem server.pem | keytool -keystore server.jks -importcert -alias server
963
966 KeyStore
967 A keystore is a storage facility for cryptographic keys and certifi‐
968 cates.
969 o KeyStore Entries
971 Keystores may have different types of entries. The two most applica‐
973 ble entry types for keytool include:
974 1. key entries - each holds very sensitive cryptographic key
976 information, which is stored in a protected format to prevent
977 unauthorized access. Typically, a key stored in this type of
978 entry is a secret key, or a private key accompanied by the
979 certificate "chain" for the corresponding public key. The key‐
980 tool can handle both types of entries, while the jarsigner
981 tool only handle the latter type of entry, that is private
982 keys and their associated certificate chains.
983 2. trusted certificate entries - each contains a single public
985 key certificate belonging to another party. It is called a
986 "trusted certificate" because the keystore owner trusts that
987 the public key in the certificate indeed belongs to the iden‐
988 tity identified by the "subject" (owner) of the certificate.
989 The issuer of the certificate vouches for this, by signing the
990 certificate.
991 o KeyStore Aliases
993 All keystore entries (key and trusted certificate entries) are
995 accessed via unique aliases.
996 An alias is specified when you add an entity to the keystore using
998 the -genseckey command to generate a secret key, -genkeypair command
999 to generate a key pair (public and private key) or the -importcert
1000 command to add a certificate or certificate chain to the list of
1001 trusted certificates. Subsequent keytool commands must use this same
1002 alias to refer to the entity.
1003 For example, suppose you use the alias duke to generate a new pub‐
1005 lic/private key pair and wrap the public key into a self-signed cer‐
1006 tificate (see Certificate Chains) via the following command:
1007 keytool -genkeypair -alias duke -keypass dukekeypasswd
1008 This specifies an initial password of "dukekeypasswd" required by
1010 subsequent commands to access the private key associated with the
1011 alias duke. If you later want to change duke's private key password,
1012 you use a command like the following:
1013 keytool -keypasswd -alias duke -keypass dukekeypasswd -new newpass
1014 This changes the password from "dukekeypasswd" to "newpass".
1016 Please note: A password should not actually be specified on a com‐
1018 mand line or in a script unless it is for testing purposes, or you
1019 are on a secure system. If you don't specify a required password
1020 option on a command line, you will be prompted for it.
1021 o KeyStore Implementation
1023 The KeyStore class provided in the java.security package supplies
1025 well-defined interfaces to access and modify the information in a
1026 keystore. It is possible for there to be multiple different concrete
1027 implementations, where each implementation is that for a particular
1028 type of keystore.
1029 Currently, two command-line tools (keytool and jarsigner) and a
1031 GUI-based tool named Policy Tool make use of keystore implementa‐
1032 tions. Since KeyStore is publicly available, users can write addi‐
1033 tional security applications that use it.
1034 There is a built-in default implementation, provided by Oracle. It
1036 implements the keystore as a file, utilizing a proprietary keystore
1037 type (format) named "JKS". It protects each private key with its
1038 individual password, and also protects the integrity of the entire
1039 keystore with a (possibly different) password.
1040 Keystore implementations are provider-based. More specifically, the
1042 application interfaces supplied by KeyStore are implemented in terms
1043 of a "Service Provider Interface" (SPI). That is, there is a corre‐
1044 sponding abstract KeystoreSpi class, also in the java.security pack‐
1045 age, which defines the Service Provider Interface methods that
1046 "providers" must implement. (The term "provider" refers to a package
1047 or a set of packages that supply a concrete implementation of a sub‐
1048 set of services that can be accessed by the Java Security API.)
1049 Thus, to provide a keystore implementation, clients must implement a
1050 "provider" and supply a KeystoreSpi subclass implementation, as
1051 described in How to Implement a Provider for the Java Cryptography
1052 Architecture @
1053 http://docs.oracle.com/javase/7/docs/technotes/guides/secu‐
1054 rity/crypto/HowToImplAProvider.html.
1055 Applications can choose different types of keystore implementations
1057 from different providers, using the "getInstance" factory method
1058 supplied in the KeyStore class. A keystore type defines the storage
1059 and data format of the keystore information, and the algorithms used
1060 to protect private/secret keys in the keystore and the integrity of
1061 the keystore itself. Keystore implementations of different types are
1062 not compatible.
1063 keytool works on any file-based keystore implementation. (It treats
1065 the keystore location that is passed to it at the command line as a
1066 filename and converts it to a FileInputStream, from which it loads
1067 the keystore information.) The jarsigner and policytool tools, on
1068 the other hand, can read a keystore from any location that can be
1069 specified using a URL.
1070 For keytool and jarsigner, you can specify a keystore type at the
1072 command line, via the -storetype option. For Policy Tool, you can
1073 specify a keystore type via the "Keystore" menu.
1074 If you don't explicitly specify a keystore type, the tools choose a
1076 keystore implementation based simply on the value of the key‐
1077 store.type property specified in the security properties file. The
1078 security properties file is called java.security, and it resides in
1079 the security properties directory, java.home/lib/security, where
1080 java.home is the runtime environment's directory (the jre directory
1081 in the SDK or the top-level directory of the Java 2 Runtime Environ‐
1082 ment).
1083 Each tool gets the keystore.type value and then examines all the
1085 currently-installed providers until it finds one that implements
1086 keystores of that type. It then uses the keystore implementation
1087 from that provider.
1088 The KeyStore class defines a static method named getDefaultType that
1090 lets applications and applets retrieve the value of the key‐
1091 store.type property. The following line of code creates an instance
1092 of the default keystore type (as specified in the keystore.type
1093 property):
1094 KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
1095 The default keystore type is "jks" (the proprietary type of the key‐
1097 store implementation provided by Oracle). This is specified by the
1098 following line in the security properties file:
1099 keystore.type=jks
1100 To have the tools utilize a keystore implementation other than the
1102 default, you can change that line to specify a different keystore
1103 type.
1104 For example, if you have a provider package that supplies a keystore
1106 implementation for a keystore type called "pkcs12", change the line
1107 to
1108 keystore.type=pkcs12
1109 Note: case doesn't matter in keystore type designations. For exam‐
1111 ple, "JKS" would be considered the same as "jks".
1112 Certificate
1115 A certificate (also known as a public-key certificate) is a digitally
1116 signed statement from one entity (the issuer), saying that the public
1117 key (and some other information) of another entity (the subject) has
1118 some specific value.
1119 o Certificate Terms
1121 Public Keys
1123 These are numbers associated with a particular entity, and are
1125 intended to be known to everyone who needs to have trusted inter‐
1126 actions with that entity. Public keys are used to verify signa‐
1127 tures.
1128 Digitally Signed
1130 If some data is digitally signed it has been stored with the
1132 "identity" of an entity, and a signature that proves that entity
1133 knows about the data. The data is rendered unforgeable by signing
1134 with the entity's private key.
1135 Identity
1137 A known way of addressing an entity. In some systems the identity
1139 is the public key, in others it can be anything from a Unix UID
1140 to an Email address to an X.509 Distinguished Name.
1141 Signature
1143 A signature is computed over some data using the private key of
1145 an entity (the signer, which in the case of a certificate is also
1146 known as the issuer).
1147 Private Keys
1149 These are numbers, each of which is supposed to be known only to
1151 the particular entity whose private key it is (that is, it's sup‐
1152 posed to be kept secret). Private and public keys exist in pairs
1153 in all public key cryptography systems (also referred to as "pub‐
1154 lic key crypto systems"). In a typical public key crypto system,
1155 such as DSA, a private key corresponds to exactly one public key.
1156 Private keys are used to compute signatures.
1157 Entity
1159 An entity is a person, organization, program, computer, business,
1161 bank, or something else you are trusting to some degree.
1162 Basically, public key cryptography requires access to users' public
1164 keys. In a large-scale networked environment it is impossible to
1165 guarantee that prior relationships between communicating entities
1166 have been established or that a trusted repository exists with all
1167 used public keys. Certificates were invented as a solution to this
1168 public key distribution problem. Now a Certification Authority (CA)
1169 can act as a trusted third party. CAs are entities (for example,
1170 businesses) that are trusted to sign (issue) certificates for other
1171 entities. It is assumed that CAs will only create valid and reliable
1172 certificates, as they are bound by legal agreements. There are many
1173 public Certification Authorities, such as VeriSign @
1174 http://www.verisign.com/, Thawte @
1175 http://www.thawte.com/, Entrust @
1176 http://www.entrust.com/, and so on. You can also run your own Certi‐
1177 fication Authority using products such as Microsoft Certificate
1178 Server or the Entrust CA product for your organization.
1179 Using keytool, it is possible to display, import, and export cer‐
1181 tificates. It is also possible to generate self-signed certificates.
1182 keytool currently handles X.509 certificates.
1184 o X.509 Certificates
1186 The X.509 standard defines what information can go into a certifi‐
1188 cate, and describes how to write it down (the data format). All the
1189 data in a certificate is encoded using two related standards called
1190 ASN.1/DER. Abstract Syntax Notation 1 describes data. The Definite
1191 Encoding Rules describe a single way to store and transfer that
1192 data.
1193 All X.509 certificates have the following data, in addition to the
1195 signature:
1196 Version
1198 This identifies which version of the X.509 standard applies to
1200 this certificate, which affects what information can be specified
1201 in it. Thus far, three versions are defined. keytool can import
1202 and export v1, v2, and v3 certificates. It generates v3 certifi‐
1203 cates.
1204 X.509 Version 1 has been available since 1988, is widely
1206 deployed, and is the most generic.
1207 X.509 Version 2 introduced the concept of subject and issuer
1209 unique identifiers to handle the possibility of reuse of subject
1210 and/or issuer names over time. Most certificate profile documents
1211 strongly recommend that names not be reused, and that certifi‐
1212 cates should not make use of unique identifiers. Version 2 cer‐
1213 tificates are not widely used.
1214 X.509 Version 3 is the most recent (1996) and supports the notion
1216 of extensions, whereby anyone can define an extension and include
1217 it in the certificate. Some common extensions in use today are:
1218 KeyUsage (limits the use of the keys to particular purposes such
1219 as "signing-only") and AlternativeNames (allows other identities
1220 to also be associated with this public key, e.g. DNS names, Email
1221 addresses, IP addresses). Extensions can be marked critical to
1222 indicate that the extension should be checked and enforced/used.
1223 For example, if a certificate has the KeyUsage extension marked
1224 critical and set to "keyCertSign" then if this certificate is
1225 presented during SSL communication, it should be rejected, as the
1226 certificate extension indicates that the associated private key
1227 should only be used for signing certificates and not for SSL use.
1228 Serial Number
1230 The entity that created the certificate is responsible for
1232 assigning it a serial number to distinguish it from other cer‐
1233 tificates it issues. This information is used in numerous ways,
1234 for example when a certificate is revoked its serial number is
1235 placed in a Certificate Revocation List (CRL).
1236 Signature Algorithm Identifier
1238 This identifies the algorithm used by the CA to sign the certifi‐
1240 cate.
1241 Issuer Name
1243 The X.500 Distinguished Name of the entity that signed the cer‐
1245 tificate. This is normally a CA. Using this certificate implies
1246 trusting the entity that signed this certificate. (Note that in
1247 some cases, such as root or top-level CA certificates, the issuer
1248 signs its own certificate.)
1249 Validity Period
1251 Each certificate is valid only for a limited amount of time. This
1253 period is described by a start date and time and an end date and
1254 time, and can be as short as a few seconds or almost as long as a
1255 century. The validity period chosen depends on a number of fac‐
1256 tors, such as the strength of the private key used to sign the
1257 certificate or the amount one is willing to pay for a certifi‐
1258 cate. This is the expected period that entities can rely on the
1259 public value, if the associated private key has not been compro‐
1260 mised.
1261 Subject Name
1263 The name of the entity whose public key the certificate identi‐
1265 fies. This name uses the X.500 standard, so it is intended to be
1266 unique across the Internet. This is the X.500 Distinguished Name
1267 (DN) of the entity, for example,
1268 CN=Java Duke, OU=Java Software Division, O=Oracle Corporation, C=US
1269 (These refer to the subject's Common Name, Organizational Unit,
1271 Organization, and Country.)
1272 Subject Public Key Information
1274 This is the public key of the entity being named, together with
1276 an algorithm identifier which specifies which public key crypto
1277 system this key belongs to and any associated key parameters.
1278 o Certificate Chains
1280 keytool can create and manage keystore "key" entries that each con‐
1282 tain a private key and an associated certificate "chain". The first
1283 certificate in the chain contains the public key corresponding to
1284 the private key.
1285 When keys are first generated (see the -genkeypair command), the
1287 chain starts off containing a single element, a self-signed certifi‐
1288 cate. A self-signed certificate is one for which the issuer (signer)
1289 is the same as the subject (the entity whose public key is being
1290 authenticated by the certificate). Whenever the -genkeypair command
1291 is called to generate a new public/private key pair, it also wraps
1292 the public key into a self-signed certificate.
1293 Later, after a Certificate Signing Request (CSR) has been generated
1295 (see the -certreq command) and sent to a Certification Authority
1296 (CA), the response from the CA is imported (see -importcert), and
1297 the self-signed certificate is replaced by a chain of certificates.
1298 At the bottom of the chain is the certificate (reply) issued by the
1299 CA authenticating the subject's public key. The next certificate in
1300 the chain is one that authenticates the CA's public key.
1301 In many cases, this is a self-signed certificate (that is, a cer‐
1303 tificate from the CA authenticating its own public key) and the last
1304 certificate in the chain. In other cases, the CA may return a chain
1305 of certificates. In this case, the bottom certificate in the chain
1306 is the same (a certificate signed by the CA, authenticating the pub‐
1307 lic key of the key entry), but the second certificate in the chain
1308 is a certificate signed by a different CA, authenticating the public
1309 key of the CA you sent the CSR to. Then, the next certificate in the
1310 chain will be a certificate authenticating the second CA's key, and
1311 so on, until a self-signed "root" certificate is reached. Each cer‐
1312 tificate in the chain (after the first) thus authenticates the pub‐
1313 lic key of the signer of the previous certificate in the chain.
1314 Many CAs only return the issued certificate, with no supporting
1316 chain, especially when there is a flat hierarchy (no intermediates
1317 CAs). In this case, the certificate chain must be established from
1318 trusted certificate information already stored in the keystore.
1319 A different reply format (defined by the PKCS#7 standard) also
1321 includes the supporting certificate chain, in addition to the issued
1322 certificate. Both reply formats can be handled by keytool.
1323 The top-level (root) CA certificate is self-signed. However, the
1325 trust into the root's public key does not come from the root cer‐
1326 tificate itself (anybody could generate a self-signed certificate
1327 with the distinguished name of say, the VeriSign root CA!), but from
1328 other sources like a newspaper. The root CA public key is widely
1329 known. The only reason it is stored in a certificate is because this
1330 is the format understood by most tools, so the certificate in this
1331 case is only used as a "vehicle" to transport the root CA's public
1332 key. Before you add the root CA certificate to your keystore, you
1333 should view it (using the -printcert option) and compare the dis‐
1334 played fingerprint with the well-known fingerprint (obtained from a
1335 newspaper, the root CA's Web page, etc.).
1336 o The cacerts Certificates File
1338 A certificates file named "cacerts" resides in the security proper‐
1340 ties directory, java.home/lib/security, where java.home is the run‐
1341 time environment's directory (the jre directory in the SDK or the
1342 top-level directory of the Java 2 Runtime Environment).
1343 The "cacerts" file represents a system-wide keystore with CA cer‐
1345 tificates. System administrators can configure and manage that file
1346 using keytool, specifying "jks" as the keystore type. The "cacerts"
1347 keystore file ships with a default set of root CA certificates; list
1348 them with the following command:
1349 keytool -list -keystore java.home/lib/security/cacerts
1350 The initial password of the "cacerts" keystore file is "changeit".
1352 System administrators should change that password and the default
1353 access permission of that file upon installing the SDK.
1354 IMPORTANT: Verify Your cacerts File: Since you trust the CAs in the
1356 cacerts file as entities for signing and issuing certificates to
1357 other entities, you must manage the cacerts file carefully. The cac‐
1358 erts file should contain only certificates of the CAs you trust. It
1359 is your responsibility to verify the trusted root CA certificates
1360 bundled in the cacerts file and make your own trust decisions. To
1361 remove an untrusted CA certificate from the cacerts file, use the
1362 delete option of the keytool command. You can find the cacerts file
1363 in the JRE installation directory. Contact your system administrator
1364 if you do not have permission to edit this file.
1365 o The Internet RFC 1421 Certificate Encoding Standard
1367 Certificates are often stored using the printable encoding format
1369 defined by the Internet RFC 1421 standard, instead of their binary
1370 encoding. This certificate format, also known as "Base 64 encoding",
1371 facilitates exporting certificates to other applications by email or
1372 through some other mechanism.
1373 Certificates read by the -importcert and -printcert commands can be
1375 in either this format or binary encoded.
1376 The -exportcert command by default outputs a certificate in binary
1378 encoding, but will instead output a certificate in the printable
1379 encoding format, if the -rfc option is specified.
1380 The -list command by default prints the SHA1 fingerprint of a cer‐
1382 tificate. If the -v option is specified, the certificate is printed
1383 in human-readable format, while if the -rfc option is specified, the
1384 certificate is output in the printable encoding format.
1385 In its printable encoding format, the encoded certificate is bounded
1387 at the beginning by
1388 -----BEGIN CERTIFICATE-----
1389 and at the end by
1391 -----END CERTIFICATE-----
1392 X.500 Distinguished Names
1395 X.500 Distinguished Names are used to identify entities, such as those
1396 which are named by the subject and issuer (signer) fields of X.509 cer‐
1397 tificates. keytool supports the following subparts:
1398 o commonName - common name of a person, e.g., "Susan Jones"
1400 o organizationUnit - small organization (e.g., department or divi‐
1402 sion) name, e.g., "Purchasing"
1403 o organizationName - large organization name, e.g., "ABCSystems,
1405 Inc."
1406 o localityName - locality (city) name, e.g., "Palo Alto"
1408 o stateName - state or province name, e.g., "California"
1410 o country - two-letter country code, e.g., "CH"
1412 When supplying a distinguished name string as the value of a -dname
1415 option, as for the -genkeypair command, the string must be in the fol‐
1416 lowing format:
1417 CN=cName, OU=orgUnit, O=org, L=city, S=state, C=countryCode
1419 where all the italicized items represent actual values and the above
1422 keywords are abbreviations for the following:
1423 CN=commonName
1425 OU=organizationUnit
1426 O=organizationName
1427 L=localityName
1428 S=stateName
1429 C=country
1430 A sample distinguished name string is
1433 CN=Mark Smith, OU=Java, O=Oracle, L=Cupertino, S=California, C=US
1435 and a sample command using such a string is
1438 keytool -genkeypair -dname "CN=Mark Smith, OU=Java, O=Oracle, L=Cupertino,
1440 S=California, C=US" -alias mark
1441 Case does not matter for the keyword abbreviations. For example, "CN",
1444 "cn", and "Cn" are all treated the same.
1445 Order matters; each subcomponent must appear in the designated order.
1447 However, it is not necessary to have all the subcomponents. You may use
1448 a subset, for example:
1449 CN=Steve Meier, OU=Java, O=Oracle, C=US
1451 If a distinguished name string value contains a comma, the comma must
1454 be escaped by a "\" character when you specify the string on a command
1455 line, as in
1456 cn=Peter Schuster, ou=Java\, Product Development, o=Oracle, c=US
1458 It is never necessary to specify a distinguished name string on a com‐
1461 mand line. If it is needed for a command, but not supplied on the com‐
1462 mand line, the user is prompted for each of the subcomponents. In this
1463 case, a comma does not need to be escaped by a "\".
1464 WARNING Regarding Importing Trusted Certificates
1466 IMPORTANT: Be sure to check a certificate very carefully before import‐
1467 ing it as a trusted certificate!
1468 View it first (using the -printcert command, or the -importcert command
1470 without the -noprompt option), and make sure that the displayed cer‐
1471 tificate fingerprint(s) match the expected ones. For example, suppose
1472 someone sends or emails you a certificate, and you put it in a file
1473 named /tmp/cert. Before you consider adding the certificate to your
1474 list of trusted certificates, you can execute a -printcert command to
1475 view its fingerprints, as in
1476 keytool -printcert -file /tmp/cert
1478 Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
1479 Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
1480 Serial Number: 59092b34
1481 Valid from: Thu Sep 25 18:01:13 PDT 1997 until: Wed Dec 24 17:01:13 PST 1997
1482 Certificate Fingerprints:
1483 MD5: 11:81:AD:92:C8:E5:0E:A2:01:2E:D4:7A:D7:5F:07:6F
1484 SHA1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE
1485 SHA256: 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90:
1486 17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4
1487 Then call or otherwise contact the person who sent the certificate, and
1490 compare the fingerprint(s) that you see with the ones that they show.
1491 Only if the fingerprints are equal is it guaranteed that the certifi‐
1492 cate has not been replaced in transit with somebody else's (for exam‐
1493 ple, an attacker's) certificate. If such an attack took place, and you
1494 did not check the certificate before you imported it, you would end up
1495 trusting anything the attacker has signed (for example, a JAR file with
1496 malicious class files inside).
1497 Note: it is not required that you execute a -printcert command prior to
1499 importing a certificate, since before adding a certificate to the list
1500 of trusted certificates in the keystore, the -importcert command prints
1501 out the certificate information and prompts you to verify it. You then
1502 have the option of aborting the import operation. Note, however, this
1503 is only the case if you invoke the -importcert command without the
1504 -noprompt option. If the -noprompt option is given, there is no inter‐
1505 action with the user.
1506 Warning Regarding Passwords
1508 Most commands operating on a keystore require the store password. Some
1509 commands require a private/secret key password.
1510 Passwords can be specified on the command line (in the -storepass and
1512 -keypass options, respectively). However, a password should not be
1513 specified on a command line or in a script unless it is for testing
1514 purposes, or you are on a secure system.
1515 If you don't specify a required password option on a command line, you
1517 will be prompted for it.
1518 Warning Regarding Certificate Conformance
1520 The Internet standard RFC 5280 @
1521 http://tools.ietf.org/rfc/rfc5280.txt has defined a profile on conform‐
1522 ing X.509 certificates, which includes what values and value combina‐
1523 tions are valid for certificate fields and extensions. keytool has not
1524 enforced all these rules so it can generate certificates which do not
1525 conform to the standard, and these certificates might be rejected by
1526 JRE or other applications. Users should make sure that they provide the
1527 correct options for -dname, -ext, etc.
1528
1530 o jar(1) tool documentation
1531 o jarsigner(1) tool documentation
1533 o the Security @
1535 http://docs.oracle.com/javase/tutorial/security/index.html trail
1536 of the Java Tutorial @
1537 http://docs.oracle.com/javase/tutorial/ for examples of the use of
1538 keytool
1539
1542 The command interface for keytool changed in Java SE 6.
1543 keytool no longer displays password input when entered by users. Since
1545 password input can no longer be viewed when entered, users will be
1546 prompted to re-enter passwords any time a password is being set or
1547 changed (for example, when setting the initial keystore password, or
1548 when changing a key password).
1549 Some commands have simply been renamed, and other commands deemed obso‐
1551 lete are no longer listed in this document. All previous commands (both
1552 renamed and obsolete) are still supported in this release and will con‐
1553 tinue to be supported in future releases. The following summarizes all
1554 of the changes made to the keytool command interface:
1555 Renamed commands:
1557 o -export, renamed to -exportcert
1559 o -genkey, renamed to -genkeypair
1561 o -import, renamed to -importcert
1563 Commands deemed obsolete and no longer documented:
1566 o -keyclone @
1568 http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/key‐
1569 tool.html#keycloneCmd
1570 o -identitydb @
1572 http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/key‐
1573 tool.html#identitydbCmd
1574 o -selfcert @
1576 http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/key‐
1577 tool.html#selfcertCmd
1578 16 Mar 2012 keytool(1)