1KEYTOOL(1)                       JDK Commands                       KEYTOOL(1)
2
3
4

NAME

6       keytool - a key and certificate management utility
7

SYNOPSIS

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

DESCRIPTION

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

COMMAND AND OPTION NOTES

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

COMMANDS AND OPTIONS

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

COMMANDS FOR CREATING OR ADDING DATA TO THE KEYSTORE

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

COMMANDS FOR IMPORTING CONTENTS FROM ANOTHER KEYSTORE

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

COMMANDS FOR GENERATING A CERTIFICATE REQUEST

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

COMMANDS FOR EXPORTING DATA

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

COMMANDS FOR DISPLAYING DATA

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

COMMANDS FOR MANAGING THE KEYSTORE

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

COMMANDS FOR DISPLAYING HELP INFORMATION

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

COMMON COMMAND OPTIONS

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

PRE-CONFIGURED OPTIONS FILE

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

EXAMPLES OF OPTION VALUES

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

SUPPORTED NAMED EXTENSIONS

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

EXAMPLES OF TASKS IN CREATING A KEYSTORE

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

GENERATING THE KEY PAIR

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

REQUESTING A SIGNED CERTIFICATE FROM A CA

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

IMPORTING A CERTIFICATE FOR THE CA

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

IMPORTING THE CERTIFICATE REPLY FROM THE CA

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

EXPORTING A CERTIFICATE THAT AUTHENTICATES THE PUBLIC KEY

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

IMPORTING THE KEYSTORE

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

GENERATING CERTIFICATES FOR AN SSL SERVER

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

TERMS

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

WARNINGS

IMPORTING TRUSTED CERTIFICATES WARNING

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

PASSWORDS WARNING

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

CERTIFICATE CONFORMANCE WARNING

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

IMPORT A NEW TRUSTED CERTIFICATE

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

IMPORT A CERTIFICATE REPLY

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)
Impressum