1keytool(1)                      Security Tools                      keytool(1)
2
3
4

NAME

6       keytool - Manages a keystore (database) of cryptographic keys, X.509
7       certificate chains, and trusted certificates.
8

SYNOPSIS

10       keytool [commands]
11
12
13       commands
14              See Commands. These commands are categorized by task as follows:
15
16              · Create or Add Data to the Keystore
17
18                · -gencert
19
20                · -genkeypair
21
22                · -genseckey
23
24                · -importcert
25
26                · -importpassword
27
28
29              · Import Contents From Another Keystore
30
31                · -importkeystore
32
33
34              · Generate Certificate Request
35
36                · -certreq
37
38
39              · Export Data
40
41                · -exportcert
42
43
44              · Display Data
45
46                · -list
47
48                · -printcert
49
50                · -printcertreq
51
52                · -printcrl
53
54
55              · Manage the Keystore
56
57                · -storepasswd
58
59                · -keypasswd
60
61                · -delete
62
63                · -changealias
64
65
66              · Get Help
67
68                · -help
69
70
71

DESCRIPTION

73       The keytool command is a key and certificate management utility. It
74       enables users to administer their own public/private key pairs and
75       associated certificates for use in self-authentication (where the user
76       authenticates himself or herself to other users and services) or data
77       integrity and authentication services, using digital signatures. The
78       keytool command also enables users to cache the public keys (in the
79       form of certificates) of their communicating peers.
80
81       A certificate is a digitally signed statement from one entity (person,
82       company, and so on.), that says that the public key (and some other
83       information) of some other entity has a particular value. (See
84       Certificate.) When data is digitally signed, the signature can be
85       verified to check the data integrity and authenticity. Integrity means
86       that the data has not been modified or tampered with, and authenticity
87       means the data comes from whoever claims to have created and signed it.
88
89       The keytool command also enables users to administer secret keys and
90       passphrases used in symmetric encryption and decryption (DES).
91
92       The keytool command stores the keys and certificates in a keystore. See
93       KeyStore aliases.
94

COMMAND AND OPTION NOTES

96       See Commands for a listing and description of the various commands.
97
98       · All command and option names are preceded by a minus sign (-).
99
100       · The options for each command can be provided in any order.
101
102       · All items not italicized or in braces or brackets are required to
103         appear as is.
104
105       · Braces surrounding an option signify that a default value will be
106         used when the option is not specified on the command line. See Option
107         Defaults. Braces are also used around the -v, -rfc, and -J options,
108         which only have meaning when they appear on the command line. They do
109         not have any default values other than not existing.
110
111       · Brackets surrounding an option signify that the user is prompted for
112         the values when the option is not specified on the command line. For
113         the -keypass option, if you do not specify the option on the command
114         line, then the keytool command first attempts to use the keystore
115         password to recover the private/secret key. If this attempt fails,
116         then the keytool command prompts you for the private/secret key
117         password.
118
119       · Items in italics (option values) represent the actual values that
120         must be supplied. For example, here is the format of the -printcert
121         command:
122
123         keytool -printcert {-file cert_file} {-v}
124
125
126
127
128
129         When you specify a -printcert command, replace cert_file with the
130         actual file name, as follows: keytool -printcert -file VScert.cer
131
132       · Option values must be put in quotation marks when they contain a
133         blank (space).
134
135       · The -help option is the default. The keytool command is the same as
136         keytool -help.
137

OPTION DEFAULTS

139       The following examples show the defaults for various option values.
140
141       -alias "mykey"
142       -keyalg
143           "DSA" (when using -genkeypair)
144           "DES" (when using -genseckey)
145       -keysize
146           2048 (when using -genkeypair and -keyalg is "RSA")
147           1024 (when using -genkeypair and -keyalg is "DSA")
148           256 (when using -genkeypair and -keyalg is "EC")
149           56 (when using -genseckey and -keyalg is "DES")
150           168 (when using -genseckey and -keyalg is "DESede")
151       -validity 90
152       -keystore <the file named .keystore in the user's home directory>
153       -storetype <the value of the "keystore.type" property in the
154           security properties file, which is returned by the static
155           getDefaultType method in java.security.KeyStore>
156       -file
157           stdin (if reading)
158           stdout (if writing)
159       -protected false
160
161       In generating a public/private key pair, the signature algorithm
162       (-sigalg option) is derived from the algorithm of the underlying
163       private key:
164
165       · If the underlying private key is of type DSA, then the -sigalg option
166         defaults to SHA1withDSA.
167
168       · If the underlying private key is of type RSA, then the -sigalg option
169         defaults to SHA256withRSA.
170
171       · If the underlying private key is of type EC, then the -sigalg option
172         defaults to SHA256withECDSA.
173
174       For a full list of -keyalg and -sigalg arguments, see Java Cryptography
175       Architecture (JCA) Reference Guide at
176       http://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/CryptoSpec.html#AppA
177

COMMON OPTIONS

179       The -v option can appear for all commands except -help. When the -v
180       option appears, it signifies verbose mode, which means that more
181       information is provided in the output.
182
183       There is also a -Jjavaoption argument that can appear for any command.
184       When the -Jjavaoption appears, the specified javaoption string is
185       passed directly to the Java interpreter. This option does not contain
186       any spaces. It is useful for adjusting the execution environment or
187       memory usage. For a list of possible interpreter options, type java -h
188       or java -X at the command line.
189
190       These options can appear for all commands operating on a keystore:
191
192       -storetype storetype
193              This qualifier specifies the type of keystore to be
194              instantiated.
195
196       -keystore keystore
197              The keystore location.
198
199              If the JKS storetype is used and a keystore file does not yet
200              exist, then certain keytool commands can result in a new
201              keystore file being created. For example, if keytool -genkeypair
202              is called and the -keystore option is not specified, the default
203              keystore file named .keystore in the user's home directory is
204              created when it does not already exist. Similarly, if the
205              -keystore ks_file option is specified but ks_file does not
206              exist, then it is created. For more information on the JKS
207              storetype, see the KeyStore Implementation section in KeyStore
208              aliases.
209
210              Note that the input stream from the -keystore option is passed
211              to the KeyStore.load method. If NONE is specified as the URL,
212              then a null stream is passed to the KeyStore.load method. NONE
213              should be specified if the keystore is not file-based. For
214              example, when it resides on a hardware token device.
215
216       -storepass[:env| :file] argument
217              The password that is used to protect the integrity of the
218              keystore.
219
220              If the modifier env or file is not specified, then the password
221              has the value argument, which must be at least 6 characters
222              long. Otherwise, the password is retrieved as follows:
223
224              · env: Retrieve the password from the environment variable named
225                argument.
226
227              · file: Retrieve the password from the file named argument.
228
229
230       Note: All other options that require passwords, such as -keypass,
231       -srckeypass, -destkeypass, -srcstorepass, and -deststorepass, accept
232       the env and file modifiers. Remember to separate the password option
233       and the modifier with a colon (:).
234
235       The password must be provided to all commands that access the keystore
236       contents. For such commands, when the -storepass option is not provided
237       at the command line, the user is prompted for it.
238
239       When retrieving information from the keystore, the password is
240       optional. If no password is specified, then the integrity of the
241       retrieved information cannot be verified and a warning is displayed.
242
243       -providerName provider_name
244              Used to identify a cryptographic service provider's name when
245              listed in the security properties file.
246
247       -providerClass provider_class_name
248              Used to specify the name of a cryptographic service provider's
249              master class file when the service provider is not listed in the
250              security properties file.
251
252       -providerArg provider_arg
253              Used with the -providerClass option to represent an optional
254              string input argument for the constructor of
255              provider_class_name.
256
257       -protected
258              Either true or false. This value should be specified as true
259              when a password must be specified by way of a protected
260              authentication path such as a dedicated PIN reader.Because there
261              are two keystores involved in the -importkeystore command, the
262              following two options -srcprotected and -destprotected are
263              provided for the source keystore and the destination keystore
264              respectively.
265
266       -ext {name{:critical} {=value}}
267              Denotes an X.509 certificate extension. The option can be used
268              in -genkeypair and -gencert to embed extensions into the
269              certificate generated, or in -certreq to show what extensions
270              are requested in the certificate request. The option can appear
271              multiple times. The name argument can be a supported extension
272              name (see Named Extensions) or an arbitrary OID number. The
273              value argument, when provided, denotes the argument for the
274              extension. When value is omitted, that means that the default
275              value of the extension or the extension requires no argument.
276              The :critical modifier, when provided, means the extension's
277              isCritical attribute is true; otherwise, it is false. You can
278              use :c in place of :critical.
279

NAMED EXTENSIONS

281       The keytool command supports these named extensions. The names are not
282       case-sensitive).
283
284       BC or BasicContraints
285              Values: The full form is: ca:{true|false}[,pathlen:<len>] or
286              <len>, which is short for ca:true,pathlen:<len>. When <len> is
287              omitted, you have ca:true.
288
289       KU or KeyUsage
290              Values: usage(,usage)*, where usage can be one of
291              digitalSignature, nonRepudiation (contentCommitment),
292              keyEncipherment, dataEncipherment, keyAgreement, keyCertSign,
293              cRLSign, encipherOnly, decipherOnly. The usage argument can be
294              abbreviated with the first few letters (dig for
295              digitalSignature) or in camel-case style (dS for
296              digitalSignature or cRLS for cRLSign), as long as no ambiguity
297              is found. The usage values are case-sensitive.
298
299       EKU or ExtendedKeyUsage
300              Values: usage(,usage)*, where usage can be one of
301              anyExtendedKeyUsage, serverAuth, clientAuth, codeSigning,
302              emailProtection, timeStamping, OCSPSigning, or any OID string.
303              The usage argument can be abbreviated with the first few letters
304              or in camel-case style, as long as no ambiguity is found. The
305              usage values are case-sensitive.
306
307       SAN or SubjectAlternativeName
308              Values: type:value(,type:value)*, where type can be EMAIL, URI,
309              DNS, IP, or OID. The value argument is the string format value
310              for the type.
311
312       IAN or IssuerAlternativeName
313              Values: Same as SubjectAlternativeName.
314
315       SIA or SubjectInfoAccess
316              Values: method:location-type:location-value (,method:location-
317              type:location-value)*, where method can be timeStamping,
318              caRepository or any OID. The location-type and location-value
319              arguments can be any type:value supported by the
320              SubjectAlternativeName extension.
321
322       AIA or AuthorityInfoAccess
323              Values: Same as SubjectInfoAccess. The method argument can be
324              ocsp,caIssuers, or any OID.
325
326       When name is OID, the value is the hexadecimal dumped DER encoding of
327       the extnValue for the extension excluding the OCTET STRING type and
328       length bytes. Any extra character other than standard hexadecimal
329       numbers (0-9, a-f, A-F) are ignored in the HEX string. Therefore, both
330       01:02:03:04 and 01020304 are accepted as identical values. When there
331       is no value, the extension has an empty value field.
332
333       A special name honored, used in -gencert only, denotes how the
334       extensions included in the certificate request should be honored. The
335       value for this name is a comma separated list of all (all requested
336       extensions are honored), name{:[critical|non-critical]} (the named
337       extension is honored, but using a different isCritical attribute) and
338       -name (used with all, denotes an exception). Requested extensions are
339       not honored by default.
340
341       If, besides the-ext honored option, another named or OID -ext option is
342       provided, this extension is added to those already honored. However, if
343       this name (or OID) also appears in the honored value, then its value
344       and criticality overrides the one in the request.
345
346       The subjectKeyIdentifier extension is always created. For non-self-
347       signed certificates, the authorityKeyIdentifier is created.
348
349       Note: Users should be aware that some combinations of extensions (and
350       other certificate fields) may not conform to the Internet standard. See
351       Certificate Conformance Warning.
352

COMMANDS

354       -gencert
355
356              {-rfc} {-infile infile} {-outfile outfile} {-alias alias} {-sigalg sigalg}
357
358
359              {-dname dname} {-startdate startdate {-ext ext}* {-validity valDays}
360
361
362              [-keypass keypass] {-keystore keystore} [-storepass storepass]
363
364
365              {-storetype storetype} {-providername provider_name}
366
367
368              {-providerClass provider_class_name {-providerArg provider_arg}}
369
370
371              {-v} {-protected} {-Jjavaoption}
372
373
374
375              Generates a certificate as a response to a certificate request
376              file (which can be created by the keytool-certreq command). The
377              command reads the request from infile (if omitted, from the
378              standard input), signs it using alias's private key, and outputs
379              the X.509 certificate into outfile (if omitted, to the standard
380              output). When-rfc is specified, the output format is
381              Base64-encoded PEM; otherwise, a binary DER is created.
382
383              The sigalg value specifies the algorithm that should be used to
384              sign the certificate. The startdate argument is the start time
385              and date that the certificate is valid. The valDays argument
386              tells the number of days for which the certificate should be
387              considered valid.
388
389              When dname is provided, it is used as the subject of the
390              generated certificate. Otherwise, the one from the certificate
391              request is used.
392
393              The ext value shows what X.509 extensions will be embedded in
394              the certificate. Read Common Options for the grammar of -ext.
395
396              The -gencert option enables you to create certificate chains.
397              The following example creates a certificate, e1, that contains
398              three certificates in its certificate chain.
399
400              The following commands creates four key pairs named ca, ca1,
401              ca2, and e1:
402
403              keytool -alias ca -dname CN=CA -genkeypair
404              keytool -alias ca1 -dname CN=CA -genkeypair
405              keytool -alias ca2 -dname CN=CA -genkeypair
406              keytool -alias e1 -dname CN=E1 -genkeypair
407
408
409
410              The following two commands create a chain of signed
411              certificates; ca signs ca1 and ca1 signs ca2, all of which are
412              self-issued:
413
414              keytool -alias ca1 -certreq |
415                  keytool -alias ca -gencert -ext san=dns:ca1 |
416                  keytool -alias ca1 -importcert
417              keytool -alias ca2 -certreq |
418                  $KT -alias ca1 -gencert -ext san=dns:ca2 |
419                  $KT -alias ca2 -importcert
420
421
422
423              The following command creates the certificate e1 and stores it
424              in the file e1.cert, which is signed by ca2. As a result, e1
425              should contain ca, ca1, and ca2 in its certificate chain:
426
427              keytool -alias e1 -certreq | keytool -alias ca2 -gencert > e1.cert
428
429
430
431       -genkeypair
432
433              {-alias alias} {-keyalg keyalg} {-keysize keysize} {-sigalg sigalg}
434
435
436              [-dname dname] [-keypass keypass] {-startdate value} {-ext ext}*
437
438
439              {-validity valDays} {-storetype storetype} {-keystore keystore}
440
441
442              [-storepass storepass]
443
444
445              {-providerClass provider_class_name {-providerArg provider_arg}}
446
447
448              {-v} {-protected} {-Jjavaoption}
449
450
451
452              Generates a key pair (a public key and associated private key).
453              Wraps the public key into an X.509 v3 self-signed certificate,
454              which is stored as a single-element certificate chain. This
455              certificate chain and the private key are stored in a new
456              keystore entry identified by alias.
457
458              The keyalg value specifies the algorithm to be used to generate
459              the key pair, and the keysize value specifies the size of each
460              key to be generated. The sigalg value specifies the algorithm
461              that should be used to sign the self-signed certificate. This
462              algorithm must be compatible with the keyalg value.
463
464              The dname value specifies the X.500 Distinguished Name to be
465              associated with the value of alias, and is used as the issuer
466              and subject fields in the self-signed certificate. If no
467              distinguished name is provided at the command line, then the
468              user is prompted for one.
469
470              The value of keypass is a password used to protect the private
471              key of the generated key pair. If no password is provided, then
472              the user is prompted for it. If you press the Return key at the
473              prompt, then the key password is set to the same password as the
474              keystore password. The keypass value must be at least 6
475              characters.
476
477              The value of startdate specifies the issue time of the
478              certificate, also known as the "Not Before" value of the X.509
479              certificate's Validity field.
480
481              The option value can be set in one of these two forms:
482
483              ([+-]nnn[ymdHMS])+
484
485              [yyyy/mm/dd] [HH:MM:SS]
486
487              With the first form, the issue time is shifted by the specified
488              value from the current time. The value is a concatenation of a
489              sequence of subvalues. Inside each subvalue, the plus sign (+)
490              means shift forward, and the minus sign (-) means shift
491              backward. The time to be shifted is nnn units of years, months,
492              days, hours, minutes, or seconds (denoted by a single character
493              of y, m, d, H, M, or S respectively). The exact value of the
494              issue time is calculated using the
495              java.util.GregorianCalendar.add(int field, int amount) method on
496              each subvalue, from left to right. For example, by specifying,
497              the issue time will be:
498
499              Calendar c = new GregorianCalendar();
500              c.add(Calendar.YEAR, -1);
501              c.add(Calendar.MONTH, 1);
502              c.add(Calendar.DATE, -1);
503              return c.getTime()
504
505
506
507              With the second form, the user sets the exact issue time in two
508              parts, year/month/day and hour:minute:second (using the local
509              time zone). The user can provide only one part, which means the
510              other part is the same as the current date (or time). The user
511              must provide the exact number of digits as shown in the format
512              definition (padding with 0 when shorter). When both the date and
513              time are provided, there is one (and only one) space character
514              between the two parts. The hour should always be provided in 24
515              hour format.
516
517              When the option is not provided, the start date is the current
518              time. The option can be provided at most once.
519
520              The value of valDays specifies the number of days (starting at
521              the date specified by -startdate, or the current date when
522              -startdate is not specified) for which the certificate should be
523              considered valid.
524
525              This command was named -genkey in earlier releases. The old name
526              is still supported in this release. The new name, -genkeypair,
527              is preferred going forward.
528
529       -genseckey
530
531              {-alias alias} {-keyalg keyalg} {-keysize keysize} [-keypass keypass]
532
533
534              {-storetype storetype} {-keystore keystore} [-storepass storepass]
535
536
537              {-providerClass provider_class_name {-providerArg provider_arg}} {-v}
538
539
540              {-protected} {-Jjavaoption}
541
542
543
544              Generates a secret key and stores it in a new
545              KeyStore.SecretKeyEntry identified by alias.
546
547              The value of keyalg specifies the algorithm to be used to
548              generate the secret key, and the value of keysize specifies the
549              size of the key to be generated. The keypass value is a password
550              that protects the secret key. If no password is provided, then
551              the user is prompted for it. If you press the Return key at the
552              prompt, then the key password is set to the same password that
553              is used for the keystore. The keypass value must be at least 6
554              characters.
555
556       -importcert
557
558              {-alias alias} {-file cert_file} [-keypass keypass] {-noprompt} {-trustcacerts}
559
560
561              {-storetype storetype} {-keystore keystore} [-storepass storepass]
562
563
564              {-providerName provider_name}
565
566
567              {-providerClass provider_class_name {-providerArg provider_arg}}
568
569
570              {-v} {-protected} {-Jjavaoption}
571
572
573
574              Reads the certificate or certificate chain (where the latter is
575              supplied in a PKCS#7 formatted reply or a sequence of X.509
576              certificates) from the file cert_file, and stores it in the
577              keystore entry identified by alias. If no file is specified,
578              then the certificate or certificate chain is read from stdin.
579
580              The keytool command can import X.509 v1, v2, and v3
581              certificates, and PKCS#7 formatted certificate chains consisting
582              of certificates of that type. The data to be imported must be
583              provided either in binary encoding format or in printable
584              encoding format (also known as Base64 encoding) as defined by
585              the Internet RFC 1421 standard. In the latter case, the encoding
586              must be bounded at the beginning by a string that starts with
587              -----BEGIN, and bounded at the end by a string that starts with
588              -----END.
589
590              You import a certificate for two reasons: To add it to the list
591              of trusted certificates, and to import a certificate reply
592              received from a certificate authority (CA) as the result of
593              submitting a Certificate Signing Request to that CA (see the
594              -certreq option in Commands).
595
596              Which type of import is intended is indicated by the value of
597              the -alias option. If the alias does not point to a key entry,
598              then the keytool command assumes you are adding a trusted
599              certificate entry. In this case, the alias should not already
600              exist in the keystore. If the alias does already exist, then the
601              keytool command outputs an error because there is already a
602              trusted certificate for that alias, and does not import the
603              certificate. If the alias points to a key entry, then the
604              keytool command assumes you are importing a certificate reply.
605
606       -importpassword
607
608              {-alias alias} [-keypass keypass] {-storetype storetype} {-keystore keystore}
609
610
611              [-storepass storepass]
612
613
614              {-providerClass provider_class_name {-providerArg provider_arg}}
615
616
617              {-v} {-protected} {-Jjavaoption}
618
619
620
621              Imports a passphrase and stores it in a new
622              KeyStore.SecretKeyEntry identified by alias. The passphrase may
623              be supplied via the standard input stream; otherwise the user is
624              prompted for it. keypass is a password used to protect the
625              imported passphrase. If no password is provided, the user is
626              prompted for it. If you press the Return key at the prompt, the
627              key password is set to the same password as that used for the
628              keystore. keypass must be at least 6 characters long.
629
630       -importkeystore
631
632              {-srcstoretype srcstoretype} {-deststoretype deststoretype}
633
634
635              [-srcstorepass srcstorepass] [-deststorepass deststorepass] {-srcprotected}
636
637
638              {-destprotected}
639
640
641              {-srcalias srcalias {-destalias destalias} [-srckeypass srckeypass]}
642
643
644              [-destkeypass destkeypass] {-noprompt}
645
646
647              {-srcProviderName src_provider_name} {-destProviderName dest_provider_name}
648
649
650              {-providerClass provider_class_name {-providerArg provider_arg}} {-v}
651
652
653              {-protected} {-Jjavaoption}
654
655
656
657              Imports a single entry or all entries from a source keystore to
658              a destination keystore.
659
660              When the -srcalias option is provided, the command imports the
661              single entry identified by the alias to the destination
662              keystore. If a destination alias is not provided with destalias,
663              then srcalias is used as the destination alias. If the source
664              entry is protected by a password, then srckeypass is used to
665              recover the entry. If srckeypass is not provided, then the
666              keytool command attempts to use srcstorepass to recover the
667              entry. If srcstorepass is either not provided or is incorrect,
668              then the user is prompted for a password. The destination entry
669              is protected with destkeypass. If destkeypass is not provided,
670              then the destination entry is protected with the source entry
671              password. For example, most third-party tools require storepass
672              and keypass in a PKCS #12 keystore to be the same. In order to
673              create a PKCS #12 keystore for these tools, always specify a
674              -destkeypass to be the same as -deststorepass.
675
676              If the -srcalias option is not provided, then all entries in the
677              source keystore are imported into the destination keystore. Each
678              destination entry is stored under the alias from the source
679              entry. If the source entry is protected by a password, then
680              srcstorepass is used to recover the entry. If srcstorepass is
681              either not provided or is incorrect, then the user is prompted
682              for a password. If a source keystore entry type is not supported
683              in the destination keystore, or if an error occurs while storing
684              an entry into the destination keystore, then the user is
685              prompted whether to skip the entry and continue or to quit. The
686              destination entry is protected with the source entry password.
687
688              If the destination alias already exists in the destination
689              keystore, then the user is prompted to either overwrite the
690              entry or to create a new entry under a different alias name.
691
692              If the -noprompt option is provided, then the user is not
693              prompted for a new destination alias. Existing entries are
694              overwritten with the destination alias name. Entries that cannot
695              be imported are skipped and a warning is displayed.
696
697       -printcertreq
698
699              {-file file}
700
701
702
703              Prints the content of a PKCS #10 format certificate request,
704              which can be generated by the keytool-certreq command. The
705              command reads the request from file. If there is no file, then
706              the request is read from the standard input.
707
708       -certreq
709
710              {-alias alias} {-dname dname} {-sigalg sigalg} {-file certreq_file}
711
712
713              [-keypass keypass] {-storetype storetype} {-keystore keystore}
714
715
716              [-storepass storepass] {-providerName provider_name}
717
718
719              {-providerClass provider_class_name {-providerArg provider_arg}}
720
721
722              {-v} {-protected} {-Jjavaoption}
723
724
725
726              Generates a Certificate Signing Request (CSR) using the PKCS #10
727              format.
728
729              A CSR is intended to be sent to a certificate authority (CA).
730              The CA authenticates the certificate requestor (usually off-
731              line) and will return a certificate or certificate chain, used
732              to replace the existing certificate chain (which initially
733              consists of a self-signed certificate) in the keystore.
734
735              The private key associated with alias is used to create the PKCS
736              #10 certificate request. To access the private key, the correct
737              password must be provided. If keypass is not provided at the
738              command line and is different from the password used to protect
739              the integrity of the keystore, then the user is prompted for it.
740              If dname is provided, then it is used as the subject in the CSR.
741              Otherwise, the X.500 Distinguished Name associated with alias is
742              used.
743
744              The sigalg value specifies the algorithm that should be used to
745              sign the CSR.
746
747              The CSR is stored in the file certreq_file. If no file is
748              specified, then the CSR is output to stdout.
749
750              Use the importcert command to import the response from the CA.
751
752       -exportcert
753
754              {-alias alias} {-file cert_file} {-storetype storetype} {-keystore keystore}
755
756
757              [-storepass storepass] {-providerName provider_name}
758
759
760              {-providerClass provider_class_name {-providerArg provider_arg}}
761
762
763              {-rfc} {-v} {-protected} {-Jjavaoption}
764
765
766
767              Reads from the keystore the certificate associated with alias
768              and stores it in the cert_file file. When no file is specified,
769              the certificate is output to stdout.
770
771              The certificate is by default output in binary encoding. If the
772              -rfc option is specified, then the output in the printable
773              encoding format defined by the Internet RFC 1421 Certificate
774              Encoding Standard.
775
776              If alias refers to a trusted certificate, then that certificate
777              is output. Otherwise, alias refers to a key entry with an
778              associated certificate chain. In that case, the first
779              certificate in the chain is returned. This certificate
780              authenticates the public key of the entity addressed by alias.
781
782              This command was named -export in earlier releases. The old name
783              is still supported in this release. The new name, -exportcert,
784              is preferred going forward.
785
786       -list
787
788              {-alias alias} {-storetype storetype} {-keystore keystore} [-storepass storepass]
789
790
791              {-providerName provider_name}
792
793
794              {-providerClass provider_class_name {-providerArg provider_arg}}
795
796
797              {-v | -rfc} {-protected} {-Jjavaoption}
798
799
800
801              Prints to stdout the contents of the keystore entry identified
802              by alias. If no alias is specified, then the contents of the
803              entire keystore are printed.
804
805              This command by default prints the SHA1 fingerprint of a
806              certificate. If the -v option is specified, then the certificate
807              is printed in human-readable format, with additional information
808              such as the owner, issuer, serial number, and any extensions. If
809              the -rfc option is specified, then the certificate contents are
810              printed using the printable encoding format, as defined by the
811              Internet RFC 1421 Certificate Encoding Standard.
812
813              You cannot specify both -v and -rfc.
814
815       -printcert
816
817              {-file cert_file | -sslserver host[:port]} {-jarfile JAR_file {-rfc} {-v}
818
819
820              {-Jjavaoption}
821
822
823
824              Reads the certificate from the file cert_file, the SSL server
825              located at host:port, or the signed JAR file JAR_file (with the
826              -jarfile option and prints its contents in a human-readable
827              format. When no port is specified, the standard HTTPS port 443
828              is assumed. Note that -sslserver and -file options cannot be
829              provided at the same time. Otherwise, an error is reported. If
830              neither option is specified, then the certificate is read from
831              stdin.
832
833              When-rfc is specified, the keytool command prints the
834              certificate in PEM mode as defined by the Internet RFC 1421
835              Certificate Encoding standard. See Internet RFC 1421 Certificate
836              Encoding Standard.
837
838              If the certificate is read from a file or stdin, then it might
839              be either binary encoded or in printable encoding format, as
840              defined by the RFC 1421 Certificate Encoding standard.
841
842              If the SSL server is behind a firewall, then the -J-
843              Dhttps.proxyHost=proxyhost and -J-Dhttps.proxyPort=proxyport
844              options can be specified on the command line for proxy
845              tunneling. See Java Secure Socket Extension (JSSE) Reference
846              Guide at
847              http://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html
848
849              Note: This option can be used independently of a keystore.
850
851       -printcrl
852
853              -file crl_ {-v}
854
855
856
857              Reads the Certificate Revocation List (CRL) from the file crl_.
858              A CRL is a list of digital certificates that were revoked by the
859              CA that issued them. The CA generates the crl_ file.
860
861              Note: This option can be used independently of a keystore.
862
863       -storepasswd
864
865              [-new new_storepass] {-storetype storetype} {-keystore keystore}
866
867
868              [-storepass storepass] {-providerName provider_name}
869
870
871              {-providerClass provider_class_name {-providerArg provider_arg}}
872
873
874              {-v} {-Jjavaoption}
875
876
877
878              Changes the password used to protect the integrity of the
879              keystore contents. The new password is new_storepass, which must
880              be at least 6 characters.
881
882       -keypasswd
883
884              {-alias alias} [-keypass old_keypass] [-new new_keypass] {-storetype storetype}
885
886
887              {-keystore keystore} [-storepass storepass] {-providerName provider_name}
888
889
890              {-providerClass provider_class_name {-providerArg provider_arg}} {-v}
891
892
893              {-Jjavaoption}
894
895
896
897              Changes the password under which the private/secret key
898              identified by alias is protected, from old_keypass to
899              new_keypass, which must be at least 6 characters.
900
901              If the -keypass option is not provided at the command line, and
902              the key password is different from the keystore password, then
903              the user is prompted for it.
904
905              If the -new option is not provided at the command line, then the
906              user is prompted for it
907
908       -delete
909
910              [-alias alias] {-storetype storetype} {-keystore keystore} [-storepass storepass]
911
912
913              {-providerName provider_name}
914
915
916              {-providerClass provider_class_name {-providerArg provider_arg}}
917
918
919              {-v} {-protected} {-Jjavaoption}
920
921
922
923              Deletes from the keystore the entry identified by alias. The
924              user is prompted for the alias, when no alias is provided at the
925              command line.
926
927       -changealias
928
929              {-alias alias} [-destalias destalias] [-keypass keypass] {-storetype storetype}
930
931
932              {-keystore keystore} [-storepass storepass] {-providerName provider_name}
933
934
935              {-providerClass provider_class_name {-providerArg provider_arg}} {-v}
936
937
938              {-protected} {-Jjavaoption}
939
940
941
942              Move an existing keystore entry from the specified alias to a
943              new alias, destalias. If no destination alias is provided, then
944              the command prompts for one. If the original entry is protected
945              with an entry password, then the password can be supplied with
946              the -keypass option. If no key password is provided, then the
947              storepass (if provided) is attempted first. If the attempt
948              fails, then the user is prompted for a password.
949
950       -help
951              Lists the basic commands and their options.
952
953              For more information about a specific command, enter the
954              following, where command_name is the name of the command:
955              keytool -command_name -help.
956

EXAMPLES

958       This example walks through the sequence of steps to create a keystore
959       for managing public/private key pair and certificates from trusted
960       entities.
961
962   GENERATE THE KEY PAIR
963       First, create a keystore and generate the key pair. You can use a
964       command such as the following typed as a single line:
965
966       keytool -genkeypair -dname "cn=Mark Jones, ou=Java, o=Oracle, c=US"
967           -alias business -keypass <new password for private key>
968           -keystore /working/mykeystore
969           -storepass <new password for keystore> -validity 180
970
971       The command creates the keystore named mykeystore in the working
972       directory (assuming it does not already exist), and assigns it the
973       password specified by <new password for keystore>. It generates a
974       public/private key pair for the entity whose distinguished name has a
975       common name of Mark Jones, organizational unit of Java, organization of
976       Oracle and two-letter country code of US. It uses the default DSA key
977       generation algorithm to create the keys; both are 1024 bits.
978
979       The command uses the default SHA1withDSA signature algorithm to create
980       a self-signed certificate that includes the public key and the
981       distinguished name information. The certificate is valid for 180 days,
982       and is associated with the private key in a keystore entry referred to
983       by the alias business. The private key is assigned the password
984       specified by <new password for private key>.
985
986       The command is significantly shorter when the option defaults are
987       accepted. In this case, no options are required, and the defaults are
988       used for unspecified options that have default values. You are prompted
989       for any required values. You could have the following:
990
991       keytool -genkeypair
992
993       In this case, a keystore entry with the alias mykey is created, with a
994       newly generated key pair and a certificate that is valid for 90 days.
995       This entry is placed in the keystore named .keystore in your home
996       directory. The keystore is created when it does not already exist. You
997       are prompted for the distinguished name information, the keystore
998       password, and the private key password.
999
1000       The rest of the examples assume you executed the -genkeypair command
1001       without options specified, and that you responded to the prompts with
1002       values equal to those specified in the first -genkeypair command. For
1003       example, a distinguished name of cn=Mark Jones, ou=Java, o=Oracle,
1004       c=US).
1005
1006   REQUEST A SIGNED CERTIFICATE FROM A CA
1007       Generating the key pair created a self-signed certificate. A
1008       certificate is more likely to be trusted by others when it is signed by
1009       a Certification Authority (CA). To get a CA signature, first generate a
1010       Certificate Signing Request (CSR), as follows:
1011
1012       keytool -certreq -file MarkJ.csr
1013
1014       This creates a CSR for the entity identified by the default alias mykey
1015       and puts the request in the file named MarkJ.csr. Submit this file to a
1016       CA, such as VeriSign. The CA authenticates you, the requestor (usually
1017       off-line), and returns a certificate, signed by them, authenticating
1018       your public key. In some cases, the CA returns a chain of certificates,
1019       each one authenticating the public key of the signer of the previous
1020       certificate in the chain.
1021
1022   IMPORT A CERTIFICATE FOR THE CA
1023       You now need to replace the self-signed certificate with a certificate
1024       chain, where each certificate in the chain authenticates the public key
1025       of the signer of the previous certificate in the chain, up to a root
1026       CA.
1027
1028       Before you import the certificate reply from a CA, you need one or more
1029       trusted certificates in your keystore or in the cacerts keystore file.
1030       See -importcert in Commands.
1031
1032       · If the certificate reply is a certificate chain, then you need the
1033         top certificate of the chain. The root CA certificate that
1034         authenticates the public key of the CA.
1035
1036       · If the certificate reply is a single certificate, then you need a
1037         certificate for the issuing CA (the one that signed it). If that
1038         certificate is not self-signed, then you need a certificate for its
1039         signer, and so on, up to a self-signed root CA certificate.
1040
1041       The cacerts keystore file ships with several VeriSign root CA
1042       certificates, so you probably will not need to import a VeriSign
1043       certificate as a trusted certificate in your keystore. But if you
1044       request a signed certificate from a different CA, and a certificate
1045       authenticating that CA's public key was not added to cacerts, then you
1046       must import a certificate from the CA as a trusted certificate.
1047
1048       A certificate from a CA is usually either self-signed or signed by
1049       another CA, in which case you need a certificate that authenticates
1050       that CA's public key. Suppose company ABC, Inc., is a CA, and you
1051       obtain a file named ABCCA.cer that is supposed to be a self-signed
1052       certificate from ABC, that authenticates that CA's public key. Be
1053       careful to ensure the certificate is valid before you import it as a
1054       trusted certificate. View it first with the keytool -printcert command
1055       or the keytool -importcert command without the -noprompt option, and
1056       make sure that the displayed certificate fingerprints match the
1057       expected ones. You can call the person who sent the certificate, and
1058       compare the fingerprints that you see with the ones that they show or
1059       that a secure public key repository shows. Only when the fingerprints
1060       are equal is it guaranteed that the certificate was not replaced in
1061       transit with somebody else's (for example, an attacker's) certificate.
1062       If such an attack takes place, and you did not check the certificate
1063       before you imported it, then you would be trusting anything the
1064       attacker has signed.
1065
1066       If you trust that the certificate is valid, then you can add it to your
1067       keystore with the following command:
1068
1069       keytool -importcert -alias abc -file ABCCA.cer
1070
1071       This command creates a trusted certificate entry in the keystore, with
1072       the data from the file ABCCA.cer, and assigns the alias abc to the
1073       entry.
1074
1075   IMPORT THE CERTIFICATE REPLY FROM THE CA
1076       After you import a certificate that authenticates the public key of the
1077       CA you submitted your certificate signing request to (or there is
1078       already such a certificate in the cacerts file), you can import the
1079       certificate reply and replace your self-signed certificate with a
1080       certificate chain. This chain is the one returned by the CA in response
1081       to your request (when the CA reply is a chain), or one constructed
1082       (when the CA reply is a single certificate) using the certificate reply
1083       and trusted certificates that are already available in the keystore
1084       where you import the reply or in the cacerts keystore file.
1085
1086       For example, if you sent your certificate signing request to VeriSign,
1087       then you can import the reply with the following, which assumes the
1088       returned certificate is named VSMarkJ.cer:
1089
1090       keytool -importcert -trustcacerts -file VSMarkJ.cer
1091
1092
1093   EXPORT A CERTIFICATE THAT AUTHENTICATES THE PUBLIC KEY
1094       If you used the jarsigner command to sign a Java Archive (JAR) file,
1095       then clients that want to use the file will want to authenticate your
1096       signature. One way the clients can authenticate you is by first
1097       importing your public key certificate into their keystore as a trusted
1098       entry.
1099
1100       You can export the certificate and supply it to your clients. As an
1101       example, you can copy your certificate to a file named MJ.cer with the
1102       following command that assumes the entry has an alias of mykey:
1103
1104       keytool -exportcert -alias mykey -file MJ.cer
1105
1106       With the certificate and the signed JAR file, a client can use the
1107       jarsigner command to authenticate your signature.
1108
1109   IMPORT KEYSTORE
1110       The command importkeystore is used to import an entire keystore into
1111       another keystore, which means all entries from the source keystore,
1112       including keys and certificates, are all imported to the destination
1113       keystore within a single command. You can use this command to import
1114       entries from a different type of keystore. During the import, all new
1115       entries in the destination keystore will have the same alias names and
1116       protection passwords (for secret keys and private keys). If the keytool
1117       command cannot recover the private keys or secret keys from the source
1118       keystore, then it prompts you for a password. If it detects alias
1119       duplication, then it asks you for a new alias, and you can specify a
1120       new alias or simply allow the keytool command to overwrite the existing
1121       one.
1122
1123       For example, to import entries from a typical JKS type keystore key.jks
1124       into a PKCS #11 type hardware-based keystore, use the command:
1125
1126       keytool -importkeystore
1127           -srckeystore key.jks -destkeystore NONE
1128           -srcstoretype JKS -deststoretype PKCS11
1129           -srcstorepass <src keystore password>
1130           -deststorepass <destination keystore pwd>
1131
1132       The importkeystore command can also be used to import a single entry
1133       from a source keystore to a destination keystore. In this case, besides
1134       the options you see in the previous example, you need to specify the
1135       alias you want to import. With the -srcalias option specified, you can
1136       also specify the destination alias name in the command line, as well as
1137       protection password for a secret/private key and the destination
1138       protection password you want. The following command demonstrates this:
1139
1140       keytool -importkeystore
1141           -srckeystore key.jks -destkeystore NONE
1142           -srcstoretype JKS -deststoretype PKCS11
1143           -srcstorepass <src keystore password>
1144           -deststorepass <destination keystore pwd>
1145           -srcalias myprivatekey -destalias myoldprivatekey
1146           -srckeypass <source entry password>
1147           -destkeypass <destination entry password>
1148           -noprompt
1149
1150
1151   GENERATE CERTIFICATES FOR AN SSL SERVER
1152       The following are keytool commands to generate key pairs and
1153       certificates for three entities: Root CA (root), Intermediate CA (ca),
1154       and SSL server (server). Ensure that you store all the certificates in
1155       the same keystore. In these examples, RSA is the recommended the key
1156       algorithm.
1157
1158       keytool -genkeypair -keystore root.jks -alias root -ext bc:c
1159       keytool -genkeypair -keystore ca.jks -alias ca -ext bc:c
1160       keytool -genkeypair -keystore server.jks -alias server
1161       keytool -keystore root.jks -alias root -exportcert -rfc > root.pem
1162       keytool -storepass <storepass> -keystore ca.jks -certreq -alias ca |
1163           keytool -storepass <storepass> -keystore root.jks
1164           -gencert -alias root -ext BC=0 -rfc > ca.pem
1165       keytool -keystore ca.jks -importcert -alias ca -file ca.pem
1166       keytool -storepass <storepass> -keystore server.jks -certreq -alias server |
1167           keytool -storepass <storepass> -keystore ca.jks -gencert -alias ca
1168           -ext ku:c=dig,kE -rfc > server.pem
1169       cat root.pem ca.pem server.pem |
1170           keytool -keystore server.jks -importcert -alias server
1171
1172

TERMS

1174       Keystore
1175              A keystore is a storage facility for cryptographic keys and
1176              certificates.
1177
1178       Keystore entries
1179              Keystores can have different types of entries. The two most
1180              applicable entry types for the keytool command include the
1181              following:
1182
1183              Key entries: Each entry holds very sensitive cryptographic key
1184              information, which is stored in a protected format to prevent
1185              unauthorized access. Typically, a key stored in this type of
1186              entry is a secret key, or a private key accompanied by the
1187              certificate chain for the corresponding public key. See
1188              Certificate Chains. The keytool command can handle both types of
1189              entries, while the jarsigner tool only handles the latter type
1190              of entry, that is private keys and their associated certificate
1191              chains.
1192
1193              Trusted certificate entries: Each entry contains a single public
1194              key certificate that belongs to another party. The entry is
1195              called a trusted certificate because the keystore owner trusts
1196              that the public key in the certificate belongs to the identity
1197              identified by the subject (owner) of the certificate. The issuer
1198              of the certificate vouches for this, by signing the certificate.
1199
1200       KeyStore aliases
1201              All keystore entries (key and trusted certificate entries) are
1202              accessed by way of unique aliases.
1203
1204              An alias is specified when you add an entity to the keystore
1205              with the -genseckey command to generate a secret key, the
1206              -genkeypair command to generate a key pair (public and private
1207              key), or the -importcert command to add a certificate or
1208              certificate chain to the list of trusted certificates.
1209              Subsequent keytool commands must use this same alias to refer to
1210              the entity.
1211
1212              For example, you can use the alias duke to generate a new
1213              public/private key pair and wrap the public key into a self-
1214              signed certificate with the following command. See Certificate
1215              Chains.
1216
1217              keytool -genkeypair -alias duke -keypass dukekeypasswd
1218
1219
1220
1221              This example specifies an initial password of dukekeypasswd
1222              required by subsequent commands to access the private key
1223              associated with the alias duke. If you later want to change
1224              Duke's private key password, use a command such as the
1225              following:
1226
1227              keytool -keypasswd -alias duke -keypass dukekeypasswd -new newpass
1228
1229
1230
1231              This changes the password from dukekeypasswd to newpass. A
1232              password should not be specified on a command line or in a
1233              script unless it is for testing purposes, or you are on a secure
1234              system. If you do not specify a required password option on a
1235              command line, then you are prompted for it.
1236
1237       KeyStore implementation
1238              The KeyStore class provided in the java.security package
1239              supplies well-defined interfaces to access and modify the
1240              information in a keystore. It is possible for there to be
1241              multiple different concrete implementations, where each
1242              implementation is that for a particular type of keystore.
1243
1244              Currently, two command-line tools (keytool and jarsigner) and a
1245              GUI-based tool named Policy Tool make use of keystore
1246              implementations. Because the KeyStore class is public, users can
1247              write additional security applications that use it.
1248
1249              There is a built-in default implementation, provided by Oracle.
1250              It implements the keystore as a file with a proprietary keystore
1251              type (format) named JKS. It protects each private key with its
1252              individual password, and also protects the integrity of the
1253              entire keystore with a (possibly different) password.
1254
1255              Keystore implementations are provider-based. More specifically,
1256              the application interfaces supplied by KeyStore are implemented
1257              in terms of a Service Provider Interface (SPI). That is, there
1258              is a corresponding abstract KeystoreSpi class, also in the
1259              java.security package, which defines the Service Provider
1260              Interface methods that providers must implement. The term
1261              provider refers to a package or a set of packages that supply a
1262              concrete implementation of a subset of services that can be
1263              accessed by the Java Security API. To provide a keystore
1264              implementation, clients must implement a provider and supply a
1265              KeystoreSpi subclass implementation, as described in How to
1266              Implement a Provider in the Java Cryptography Architecture at
1267              http://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/HowToImplAProvider.html
1268
1269              Applications can choose different types of keystore
1270              implementations from different providers, using the getInstance
1271              factory method supplied in the KeyStore class. A keystore type
1272              defines the storage and data format of the keystore information,
1273              and the algorithms used to protect private/secret keys in the
1274              keystore and the integrity of the keystore. Keystore
1275              implementations of different types are not compatible.
1276
1277              The keytool command works on any file-based keystore
1278              implementation. It treats the keystore location that is passed
1279              to it at the command line as a file name and converts it to a
1280              FileInputStream, from which it loads the keystore
1281              information.)The jarsigner command can read a keystore from any
1282              location that can be specified with a URL.
1283
1284              For keytool and jarsigner, you can specify a keystore type at
1285              the command line, with the -storetype option. For Policy Tool,
1286              you can specify a keystore type with the Keystore menu.
1287
1288              If you do not explicitly specify a keystore type, then the tools
1289              choose a keystore implementation based on the value of the
1290              keystore.type property specified in the security properties
1291              file. The security properties file is called java.security, and
1292              resides in the security properties directory,
1293              java.home\lib\security on Windows and java.home/lib/security on
1294              Oracle Solaris, where java.home is the runtime environment
1295              directory. The jre directory in the SDK or the top-level
1296              directory of the Java Runtime Environment (JRE).
1297
1298              Each tool gets the keystore.type value and then examines all the
1299              currently installed providers until it finds one that implements
1300              a keystores of that type. It then uses the keystore
1301              implementation from that provider.The KeyStore class defines a
1302              static method named getDefaultType that lets applications and
1303              applets retrieve the value of the keystore.type property. The
1304              following line of code creates an instance of the default
1305              keystore type as specified in the keystore.type property:
1306
1307              KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
1308
1309
1310
1311              The default keystore type is jks, which is the proprietary type
1312              of the keystore implementation provided by Oracle. This is
1313              specified by the following line in the security properties file:
1314
1315              keystore.type=jks
1316
1317
1318
1319              To have the tools utilize a keystore implementation other than
1320              the default, you can change that line to specify a different
1321              keystore type. For example, if you have a provider package that
1322              supplies a keystore implementation for a keystore type called
1323              pkcs12, then change the line to the following:
1324
1325              keystore.type=pkcs12
1326
1327
1328
1329              Note: Case does not matter in keystore type designations. For
1330              example, JKS would be considered the same as jks.
1331
1332       Certificate
1333              A certificate (or public-key certificate) is a digitally signed
1334              statement from one entity (the issuer), saying that the public
1335              key and some other information of another entity (the subject)
1336              has some specific value. The following terms are related to
1337              certificates:
1338
1339              Public Keys: These are numbers associated with a particular
1340              entity, and are intended to be known to everyone who needs to
1341              have trusted interactions with that entity. Public keys are used
1342              to verify signatures.
1343
1344              Digitally Signed: If some data is digitally signed, then it is
1345              stored with the identity of an entity and a signature that
1346              proves that entity knows about the data. The data is rendered
1347              unforgeable by signing with the entity's private key.
1348
1349              Identity: A known way of addressing an entity. In some systems,
1350              the identity is the public key, and in others it can be anything
1351              from an Oracle Solaris UID to an email address to an X.509
1352              distinguished name.
1353
1354              Signature: A signature is computed over some data using the
1355              private key of an entity. The signer, which in the case of a
1356              certificate is also known as the issuer.
1357
1358              Private Keys: These are numbers, each of which is supposed to be
1359              known only to the particular entity whose private key it is
1360              (that is, it is supposed to be kept secret). Private and public
1361              keys exist in pairs in all public key cryptography systems (also
1362              referred to as public key crypto systems). In a typical public
1363              key crypto system, such as DSA, a private key corresponds to
1364              exactly one public key. Private keys are used to compute
1365              signatures.
1366
1367              Entity: An entity is a person, organization, program, computer,
1368              business, bank, or something else you are trusting to some
1369              degree.
1370
1371              Public key cryptography requires access to users' public keys.
1372              In a large-scale networked environment, it is impossible to
1373              guarantee that prior relationships between communicating
1374              entities were established or that a trusted repository exists
1375              with all used public keys. Certificates were invented as a
1376              solution to this public key distribution problem. Now a
1377              Certification Authority (CA) can act as a trusted third party.
1378              CAs are entities such as businesses that are trusted to sign
1379              (issue) certificates for other entities. It is assumed that CAs
1380              only create valid and reliable certificates because they are
1381              bound by legal agreements. There are many public Certification
1382              Authorities, such as VeriSign, Thawte, Entrust, and so on.
1383
1384              You can also run your own Certification Authority using products
1385              such as Microsoft Certificate Server or the Entrust CA product
1386              for your organization. With the keytool command, it is possible
1387              to display, import, and export certificates. It is also possible
1388              to generate self-signed certificates.
1389
1390              The keytool command currently handles X.509 certificates.
1391
1392       X.509 Certificates
1393              The X.509 standard defines what information can go into a
1394              certificate and describes how to write it down (the data
1395              format). All the data in a certificate is encoded with two
1396              related standards called ASN.1/DER. Abstract Syntax Notation 1
1397              describes data. The Definite Encoding Rules describe a single
1398              way to store and transfer that data.
1399
1400              All X.509 certificates have the following data, in addition to
1401              the signature:
1402
1403              Version: This identifies which version of the X.509 standard
1404              applies to this certificate, which affects what information can
1405              be specified in it. Thus far, three versions are defined. The
1406              keytool command can import and export v1, v2, and v3
1407              certificates. It generates v3 certificates.
1408
1409              X.509 Version 1 has been available since 1988, is widely
1410              deployed, and is the most generic.
1411
1412              X.509 Version 2 introduced the concept of subject and issuer
1413              unique identifiers to handle the possibility of reuse of subject
1414              or issuer names over time. Most certificate profile documents
1415              strongly recommend that names not be reused and that
1416              certificates should not make use of unique identifiers. Version
1417              2 certificates are not widely used.
1418
1419              X.509 Version 3 is the most recent (1996) and supports the
1420              notion of extensions where anyone can define an extension and
1421              include it in the certificate. Some common extensions are:
1422              KeyUsage (limits the use of the keys to particular purposes such
1423              as signing-only) and AlternativeNames (allows other identities
1424              to also be associated with this public key, for example. DNS
1425              names, email addresses, IP addresses). Extensions can be marked
1426              critical to indicate that the extension should be checked and
1427              enforced or used. For example, if a certificate has the KeyUsage
1428              extension marked critical and set to keyCertSign, then when this
1429              certificate is presented during SSL communication, it should be
1430              rejected because the certificate extension indicates that the
1431              associated private key should only be used for signing
1432              certificates and not for SSL use.
1433
1434              Serial number: The entity that created the certificate is
1435              responsible for assigning it a serial number to distinguish it
1436              from other certificates it issues. This information is used in
1437              numerous ways. For example, when a certificate is revoked its
1438              serial number is placed in a Certificate Revocation List (CRL).
1439
1440              Signature algorithm identifier: This identifies the algorithm
1441              used by the CA to sign the certificate.
1442
1443              Issuer name: The X.500 Distinguished Name of the entity that
1444              signed the certificate. See X.500 Distinguished Names. This is
1445              typically a CA. Using this certificate implies trusting the
1446              entity that signed this certificate. In some cases, such as root
1447              or top-level CA certificates, the issuer signs its own
1448              certificate.
1449
1450              Validity period: Each certificate is valid only for a limited
1451              amount of time. This period is described by a start date and
1452              time and an end date and time, and can be as short as a few
1453              seconds or almost as long as a century. The validity period
1454              chosen depends on a number of factors, such as the strength of
1455              the private key used to sign the certificate, or the amount one
1456              is willing to pay for a certificate. This is the expected period
1457              that entities can rely on the public value, when the associated
1458              private key has not been compromised.
1459
1460              Subject name: The name of the entity whose public key the
1461              certificate identifies. This name uses the X.500 standard, so it
1462              is intended to be unique across the Internet. This is the X.500
1463              Distinguished Name (DN) of the entity. See X.500 Distinguished
1464              Names. For example,
1465
1466              CN=Java Duke, OU=Java Software Division, O=Oracle Corporation, C=US
1467
1468
1469
1470              These refer to the subject's common name (CN), organizational
1471              unit (OU), organization (O), and country (C).
1472
1473              Subject public key information: This is the public key of the
1474              entity being named with an algorithm identifier that specifies
1475              which public key crypto system this key belongs to and any
1476              associated key parameters.
1477
1478       Certificate Chains
1479              The keytool command can create and manage keystore key entries
1480              that each contain a private key and an associated certificate
1481              chain. The first certificate in the chain contains the public
1482              key that corresponds to the private key.
1483
1484              When keys are first generated, the chain starts off containing a
1485              single element, a self-signed certificate. See -genkeypair in
1486              Commands. A self-signed certificate is one for which the issuer
1487              (signer) is the same as the subject. The subject is the entity
1488              whose public key is being authenticated by the certificate.
1489              Whenever the -genkeypair command is called to generate a new
1490              public/private key pair, it also wraps the public key into a
1491              self-signed certificate.
1492
1493              Later, after a Certificate Signing Request (CSR) was generated
1494              with the -certreq command and sent to a Certification Authority
1495              (CA), the response from the CA is imported with -importcert, and
1496              the self-signed certificate is replaced by a chain of
1497              certificates. See the -certreq and -importcert options in
1498              Commands. At the bottom of the chain is the certificate (reply)
1499              issued by the CA authenticating the subject's public key. The
1500              next certificate in the chain is one that authenticates the CA's
1501              public key.
1502
1503              In many cases, this is a self-signed certificate, which is a
1504              certificate from the CA authenticating its own public key, and
1505              the last certificate in the chain. In other cases, the CA might
1506              return a chain of certificates. In this case, the bottom
1507              certificate in the chain is the same (a certificate signed by
1508              the CA, authenticating the public key of the key entry), but the
1509              second certificate in the chain is a certificate signed by a
1510              different CA that authenticates the public key of the CA you
1511              sent the CSR to. The next certificate in the chain is a
1512              certificate that authenticates the second CA's key, and so on,
1513              until a self-signed root certificate is reached. Each
1514              certificate in the chain (after the first) authenticates the
1515              public key of the signer of the previous certificate in the
1516              chain.
1517
1518              Many CAs only return the issued certificate, with no supporting
1519              chain, especially when there is a flat hierarchy (no
1520              intermediates CAs). In this case, the certificate chain must be
1521              established from trusted certificate information already stored
1522              in the keystore.
1523
1524              A different reply format (defined by the PKCS #7 standard)
1525              includes the supporting certificate chain in addition to the
1526              issued certificate. Both reply formats can be handled by the
1527              keytool command.
1528
1529              The top-level (root) CA certificate is self-signed. However, the
1530              trust into the root's public key does not come from the root
1531              certificate itself, but from other sources such as a newspaper.
1532              This is because anybody could generate a self-signed certificate
1533              with the distinguished name of, for example, the VeriSign root
1534              CA. The root CA public key is widely known. The only reason it
1535              is stored in a certificate is because this is the format
1536              understood by most tools, so the certificate in this case is
1537              only used as a vehicle to transport the root CA's public key.
1538              Before you add the root CA certificate to your keystore, you
1539              should view it with the -printcert option and compare the
1540              displayed fingerprint with the well-known fingerprint obtained
1541              from a newspaper, the root CA's Web page, and so on.
1542
1543       The cacerts Certificates File
1544              A certificates file named cacerts resides in the security
1545              properties directory, java.home\lib\security on Windows and
1546              java.home/lib/security on Oracle Solaris, where java.home is the
1547              runtime environment's directory, which would be the jre
1548              directory in the SDK or the top-level directory of the JRE.
1549
1550              The cacerts file represents a system-wide keystore with CA
1551              certificates. System administrators can configure and manage
1552              that file with the keytool command by specifying jks as the
1553              keystore type. The cacerts keystore file ships with a default
1554              set of root CA certificates. You can list the default
1555              certificates with the following command:
1556
1557              keytool -list -keystore java.home/lib/security/cacerts
1558
1559
1560
1561              The initial password of the cacerts keystore file is changeit.
1562              System administrators should change that password and the
1563              default access permission of that file upon installing the SDK.
1564
1565              Note: It is important to verify your cacerts file. Because you
1566              trust the CAs in the cacerts file as entities for signing and
1567              issuing certificates to other entities, you must manage the
1568              cacerts file carefully. The cacerts file should contain only
1569              certificates of the CAs you trust. It is your responsibility to
1570              verify the trusted root CA certificates bundled in the cacerts
1571              file and make your own trust decisions.
1572
1573              To remove an untrusted CA certificate from the cacerts file, use
1574              the delete option of the keytool command. You can find the
1575              cacerts file in the JRE installation directory. Contact your
1576              system administrator if you do not have permission to edit this
1577              file
1578
1579       Internet RFC 1421 Certificate Encoding Standard
1580              Certificates are often stored using the printable encoding
1581              format defined by the Internet RFC 1421 standard, instead of
1582              their binary encoding. This certificate format, also known as
1583              Base64 encoding, makes it easy to export certificates to other
1584              applications by email or through some other mechanism.
1585
1586              Certificates read by the -importcert and -printcert commands can
1587              be in either this format or binary encoded. The -exportcert
1588              command by default outputs a certificate in binary encoding, but
1589              will instead output a certificate in the printable encoding
1590              format, when the -rfc option is specified.
1591
1592              The -list command by default prints the SHA1 fingerprint of a
1593              certificate. If the -v option is specified, then the certificate
1594              is printed in human-readable format. If the -rfc option is
1595              specified, then the certificate is output in the printable
1596              encoding format.
1597
1598              In its printable encoding format, the encoded certificate is
1599              bounded at the beginning and end by the following text:
1600
1601              -----BEGIN CERTIFICATE-----
1602              encoded certificate goes here.
1603              -----END CERTIFICATE-----
1604
1605
1606
1607       X.500 Distinguished Names
1608              X.500 Distinguished Names are used to identify entities, such as
1609              those that are named by the subject and issuer (signer) fields
1610              of X.509 certificates. The keytool command supports the
1611              following subparts:
1612
1613              commonName: The common name of a person such as Susan Jones.
1614
1615              organizationUnit: The small organization (such as department or
1616              division) name. For example, Purchasing.
1617
1618              localityName: The locality (city) name, for example, Palo Alto.
1619
1620              stateName: State or province name, for example, California.
1621
1622              country: Two-letter country code, for example, CH.
1623
1624              When you supply a distinguished name string as the value of a
1625              -dname option, such as for the -genkeypair command, the string
1626              must be in the following format:
1627
1628              CN=cName, OU=orgUnit, O=org, L=city, S=state, C=countryCode
1629
1630
1631
1632              All the italicized items represent actual values and the
1633              previous keywords are abbreviations for the following:
1634
1635              CN=commonName
1636              OU=organizationUnit
1637              O=organizationName
1638              L=localityName
1639              S=stateName
1640              C=country
1641
1642
1643
1644              A sample distinguished name string is:
1645
1646              CN=Mark Smith, OU=Java, O=Oracle, L=Cupertino, S=California, C=US
1647
1648
1649
1650              A sample command using such a string is:
1651
1652              keytool -genkeypair -dname "CN=Mark Smith, OU=Java, O=Oracle, L=Cupertino,
1653              S=California, C=US" -alias mark
1654
1655
1656
1657              Case does not matter for the keyword abbreviations. For example,
1658              CN, cn, and Cn are all treated the same.
1659
1660              Order matters; each subcomponent must appear in the designated
1661              order. However, it is not necessary to have all the
1662              subcomponents. You can use a subset, for example:
1663
1664              CN=Steve Meier, OU=Java, O=Oracle, C=US
1665
1666
1667
1668              If a distinguished name string value contains a comma, then the
1669              comma must be escaped by a backslash (\) character when you
1670              specify the string on a command line, as in:
1671
1672              cn=Peter Schuster, ou=Java\, Product Development, o=Oracle, c=US
1673
1674
1675
1676              It is never necessary to specify a distinguished name string on
1677              a command line. When the distinguished name is needed for a
1678              command, but not supplied on the command line, the user is
1679              prompted for each of the subcomponents. In this case, a comma
1680              does not need to be escaped by a backslash (\).
1681

WARNINGS

1683   IMPORTING TRUSTED CERTIFICATES WARNING
1684       Important: Be sure to check a certificate very carefully before
1685       importing it as a trusted certificate.
1686
1687       Windows Example:
1688
1689       View the certificate first with the -printcert command or the
1690       -importcert command without the -noprompt option. Ensure that the
1691       displayed certificate fingerprints match the expected ones. For
1692       example, suppose sends or emails you a certificate that you put it in a
1693       file named \tmp\cert. Before you consider adding the certificate to
1694       your list of trusted certificates, you can execute a -printcert command
1695       to view its fingerprints, as follows:
1696
1697         keytool -printcert -file \tmp\cert
1698           Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
1699           Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
1700           Serial Number: 59092b34
1701           Valid from: Thu Sep 25 18:01:13 PDT 1997 until: Wed Dec 24 17:01:13 PST 1997
1702           Certificate Fingerprints:
1703                MD5:  11:81:AD:92:C8:E5:0E:A2:01:2E:D4:7A:D7:5F:07:6F
1704                SHA1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE
1705                SHA256: 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90:
1706                        17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4
1707
1708
1709
1710       Oracle Solaris Example:
1711
1712       View the certificate first with the -printcert command or the
1713       -importcert command without the -noprompt option. Ensure that the
1714       displayed certificate fingerprints match the expected ones. For
1715       example, suppose someone sends or emails you a certificate that you put
1716       it in a file named /tmp/cert. Before you consider adding the
1717       certificate to your list of trusted certificates, you can execute a
1718       -printcert command to view its fingerprints, as follows:
1719
1720         keytool -printcert -file /tmp/cert
1721           Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
1722           Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
1723           Serial Number: 59092b34
1724           Valid from: Thu Sep 25 18:01:13 PDT 1997 until: Wed Dec 24 17:01:13 PST 1997
1725           Certificate Fingerprints:
1726                MD5:  11:81:AD:92:C8:E5:0E:A2:01:2E:D4:7A:D7:5F:07:6F
1727                SHA1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE
1728                SHA256: 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90:
1729                        17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4
1730
1731       Then call or otherwise contact the person who sent the certificate and
1732       compare the fingerprints that you see with the ones that they show.
1733       Only when the fingerprints are equal is it guaranteed that the
1734       certificate was not replaced in transit with somebody else's
1735       certificate such as an attacker's certificate. If such an attack took
1736       place, and you did not check the certificate before you imported it,
1737       then you would be trusting anything the attacker signed, for example, a
1738       JAR file with malicious class files inside.
1739
1740       Note: It is not required that you execute a -printcert command before
1741       importing a certificate. This is because before you add a certificate
1742       to the list of trusted certificates in the keystore, the -importcert
1743       command prints out the certificate information and prompts you to
1744       verify it. You can then stop the import operation. However, you can do
1745       this only when you call the -importcert command without the -noprompt
1746       option. If the -noprompt option is specified, then there is no
1747       interaction with the user.
1748
1749   PASSWORDS WARNING
1750       Most commands that operate on a keystore require the store password.
1751       Some commands require a private/secret key password. Passwords can be
1752       specified on the command line in the -storepass and -keypass options.
1753       However, a password should not be specified on a command line or in a
1754       script unless it is for testing, or you are on a secure system. When
1755       you do not specify a required password option on a command line, you
1756       are prompted for it.
1757
1758   CERTIFICATE CONFORMANCE WARNING
1759       The Internet standard RFC 5280 has defined a profile on conforming
1760       X.509 certificates, which includes what values and value combinations
1761       are valid for certificate fields and extensions. See the standard at
1762       http://tools.ietf.org/rfc/rfc5280.txt
1763
1764       The keytool command does not enforce all of these rules so it can
1765       generate certificates that do not conform to the standard. Certificates
1766       that do not conform to the standard might be rejected by JRE or other
1767       applications. Users should ensure that they provide the correct options
1768       for -dname, -ext, and so on.
1769

NOTES

1771   IMPORT A NEW TRUSTED CERTIFICATE
1772       Before you add the certificate to the keystore, the keytool command
1773       verifies it by attempting to construct a chain of trust from that
1774       certificate to a self-signed certificate (belonging to a root CA),
1775       using trusted certificates that are already available in the keystore.
1776
1777       If the -trustcacerts option was specified, then additional certificates
1778       are considered for the chain of trust, namely the certificates in a
1779       file named cacerts.
1780
1781       If the keytool command fails to establish a trust path from the
1782       certificate to be imported up to a self-signed certificate (either from
1783       the keystore or the cacerts file), then the certificate information is
1784       printed, and the user is prompted to verify it by comparing the
1785       displayed certificate fingerprints with the fingerprints obtained from
1786       some other (trusted) source of information, which might be the
1787       certificate owner. Be very careful to ensure the certificate is valid
1788       before importing it as a trusted certificate. See Importing Trusted
1789       Certificates Warning. The user then has the option of stopping the
1790       import operation. If the -noprompt option is specified, then there is
1791       no interaction with the user.
1792
1793   IMPORT A CERTIFICATE REPLY
1794       When you import a certificate reply, the certificate reply is validated
1795       with trusted certificates from the keystore, and optionally, the
1796       certificates configured in the cacerts keystore file when the
1797       -trustcacerts option is specified. See The cacerts Certificates File.
1798
1799       The methods of determining whether the certificate reply is trusted are
1800       as follows:
1801
1802       · If the reply is a single X.509 certificate, then the keytool command
1803         attempts to establish a trust chain, starting at the certificate
1804         reply and ending at a self-signed certificate (belonging to a root
1805         CA). The certificate reply and the hierarchy of certificates is used
1806         to authenticate the certificate reply from the new certificate chain
1807         of aliases. If a trust chain cannot be established, then the
1808         certificate reply is not imported. In this case, the keytool command
1809         does not print the certificate and prompt the user to verify it,
1810         because it is very difficult for a user to determine the authenticity
1811         of the certificate reply.
1812
1813       · If the reply is a PKCS #7 formatted certificate chain or a sequence
1814         of X.509 certificates, then the chain is ordered with the user
1815         certificate first followed by zero or more CA certificates. If the
1816         chain ends with a self-signed root CA certificate and the-
1817         trustcacerts option was specified, the keytool command attempts to
1818         match it with any of the trusted certificates in the keystore or the
1819         cacerts keystore file. If the chain does not end with a self-signed
1820         root CA certificate and the -trustcacerts option was specified, the
1821         keytool command tries to find one from the trusted certificates in
1822         the keystore or the cacerts keystore file and add it to the end of
1823         the chain. If the certificate is not found and the -noprompt option
1824         is not specified, the information of the last certificate in the
1825         chain is printed, and the user is prompted to verify it.
1826
1827       If the public key in the certificate reply matches the user's public
1828       key already stored with alias, then the old certificate chain is
1829       replaced with the new certificate chain in the reply. The old chain can
1830       only be replaced with a valid keypass, and so the password used to
1831       protect the private key of the entry is supplied. If no password is
1832       provided, and the private key password is different from the keystore
1833       password, the user is prompted for it.
1834
1835       This command was named -import in earlier releases. This old name is
1836       still supported in this release. The new name, -importcert, is
1837       preferred going forward.
1838

SEE ALSO

1840       · jar(1)
1841
1842       · jarsigner(1)
1843
1844       · Trail: Security Features in Java SE at
1845         http://docs.oracle.com/javase/tutorial/security/index.html
1846
1847
1848
1849JDK 8                            03 March 2015                      keytool(1)
Impressum