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