Manages a keystore (database) of private keys and their associated X.509 certificate chains authenticating the corresponding public keys. Also manages certificates from trusted entities.
keytool [ commands ]
keytool is a key and certificate management utility. It enables users to administer their own public/private key pairs and associated certificates for use in self-authentication (where the user authenticates himself/herself to other users/services) or data integrity and authentication services, using digital signatures. It also allows users to cache the public keys (in the form of certificates) of their communicating peers.A certificate is a digitally signed statement from one entity, saying that the public key of some other entity has a particular value. (See Certificates.) When data is digitally signed, the signature can be verified to check the data integrity and authenticity. Integrity means that the data has not been modified or tampered with, and authenticity means the data indeed comes from whoever claims to have created and signed it.
keytool stores the keys and certificates in a so-called keystore. The default keystore implementation implements the keystore as a file. It protects private keys with a password.
The jarsigner tool uses information from a keystore to generate or verify digital signatures for Java ARchive (JAR) files. (A JAR file packages class files, images, sounds, and/or other digital data in a single file). jarsigner verifies the digital signature of a JAR file, using the certificate that comes with it (it is included in the signature block file of the JAR file), and then checks whether or not the public key of that certificate is "trusted", i.e., is contained in the specified keystore.
Please note: the keytool and jarsigner tools completely replace the javakey tool provided in JDK 1.1. These new tools provide more features than javakey, including the ability to protect the keystore and private keys with passwords, and the ability to verify signatures in addition to generating them. There is no backwards compatibility between the keystore format and the database format used by javakey in 1.1.
Keystore Entries
There are two different types of entries in a keystore:
- key/certificate entries - each has a private key and an associated certificate "chain".
- trusted certificate entries - each contains a single certificate. It is called a "trusted certificate" because you trust that the public key in the certificate indeed belongs to the identity identified by the "subject" (owner) of the certificate. The issuer of the certificate vouches for this, by signing the certificate.
Keystore Aliases
All keystore entries (key/certificate and trusted certificate entries) are accessed via unique aliases. Aliases are case-insensitive; the aliases
Hugo
andhugo
would refer to the same keystore entry.An alias is specified when you add an entity to the keystore using the -genkey command to generate a key pair (public and private key) or the -import command to add a certificate to the list of trusted certificates. Subsequent keytool commands must use this same alias to refer to the entity.
For example, suppose you use the alias duke to generate a new public/private key pair and wrap the public key into a self-signed certificate via the following command:
keytool -genkey -alias duke -keypass dukekeypasswdThis specifies an inital password of "dukekeypasswd" required by subsequent commands to access the private key assocated with the aliasduke
. If you later want to change duke's private key password, you would use a command like the following:keytool -keypasswd -alias duke -keypass dukekeypasswd -new newpassThis changes the password from "dukekeypasswd" to "newpass".Please note: A password should not actually be specified on a command line or in a script unless it is for testing purposes, or you are on a secure system. If you don't specify a required password option on a command line, you will be prompted for it. When typing in a password at the password prompt, the password is echoed (displayed exactly as typed), so be careful not to type it in front of anyone.
Keystore Location
Each keytool command has a-keystore
option for specifying the name and location of the persistent keystore file for the keystore managed by keytool. The keystore is by default stored in a file named .keystore in the user's home directory, as determined by the "user.home" system property.Keystore Creation
A keystore is created whenever you use either a -genkey or -import command to add data to a keystore that doesn't yet exist.More specifically, if you specify, in the
-keystore
option, a keystore that doesn't yet exist, that keystore will be created.If you don't specify a
-keystore
option, the default keystore is a file named.keystore
in your home directory. If that file does not yet exist, it will be created.Keystore Implementation
A keystore implementation is a concrete implementation of theKeyStore
abstract class provided in thejava.security
package. This class supplies well-defined interfaces to access and modify the information in a keystore.Currently, there are two command-line tools that make use of KeyStore: keytool and jarsigner, and also a GUI-based tool named policytool. Since
KeyStore
is publicly available, JDK users can write additional security applications that use it.The default
KeyStore
implementation, provided by Sun Microsystems, implements the keystore as a file. It protects private keys with a password.A client may, if desired, write their own
KeyStore
implementation, for example if they would like to use a different (not file-based) keystore format. Keystores with different formats are not compatible; for example, a non-file-basedKeystore
implementation would not be able to load a Sun keystore. However, such an implementation could still use the keytool and jarsigner tools on its own keystores.To have the tools utilize a
KeyStore
implementation other than the default, change the value of thekeystore
property in the security properties file. Thekeystore
property value is assumed to specify the fully qualified class name of theKeyStore
implementation. The security properties file is called java.security, and it resides in the JDK security properties directory,java.home\lib\security
, where java.home is the JDK installation directory.Thus, to change to a
KeyStore
implementation other than the default, change the linekeystore=sun.security.tools.JavaKeyStorein the security properties file to point to the different keystore implementation.For example, if the
KeyStore
implementation is provided in a file namedSecureKeys.class
, and that file resides in thekeymgmtsolutions.tools
package, change the line to:keystore=keymgmtsolutions.tools.SecureKeysThe above sets the value of the "keystore" property to "keymgmtsolutions.tools.SecureKeys".
Supported Algorithms and Key Sizes
At this time, only the DSA key algorithm and the DSA with SHA-1 signature algorithm are supported by the default implementation. Thus, the keyalg and sigalg options for various commands, if provided, must be equal to the defaults for those options, which are "DSA" and "DSA/SHA-1", respectively.
The key size must be in the range from 512 to 1024 bits, and must be a multiple of 64. The default key size is 1024 bits.
Certificates
A certificate is a digitally signed statement from one entity (the issuer), saying that the public key of some other entity (the subject) has some particular value. If you trust the issuer, you trust that the association in the certificate between the specified public key and the subject is authentic.
Here are a few definitions:
- A public key is a number associated with a particular entity, and is intended to be known to everyone who needs to have trusted interactions with that entity.
- An entity is a person, organization, program, computer, business, bank, etc.
- If some data is digitally signed by an entity, it has been stored with the entity's name, and an unforgeable digital signature (string of bits) asserting that the entity wrote or agrees to the data. The signature can be verified to check the data integrity and authenticity.
- A signature is computed from some data and the private key of an entity.
- A private key is a number that is supposed to be known only to the particular entity whose private key it is (that is, it's supposed to be kept secret). A private key is always associated with a single public key.
Note that (a) private and public keys are paired, (b) private keys are used to sign, and (c) public keys are used to verify signatures.
Another term related to certificates is Certification Authority (CA). A CA is an entity (e.g., a business) that is trusted to sign (issue) certificates for other people (entities). CAs usually have some kind of legal responsibilities for their vouching for the binding between a public key and its owner. There are many such Certification Authorities, such as VeriSign, GTE, and so on.
Using keytool, it is possible to display, import, and export certificates. It is also possible to generate self-signed certificates.
keytool currently handles X.509 certificates.
X.509 Certificates
The X.509 standard defines what information can go into a certificate, and how to encode the certificate information (the data format). All X.509 certificates have the following data, in addition to the signature and a specification of the signature algorithm used:
- Version
This identifies which version of the X.509 standard applies to this certificate, which affects what information can be specified in it. keytool can import and export v1, v2, and v3 certificates. It generates v1 certificates.
- Subject Name
The name of the entity whose public key the certificate contains. This name uses the X.500 standard, so it is intended to be unique across the Internet. This is the X.500 Distinguished Name (DN) of the entity, for example,CN=Duke Smith, OU=JavaSoft, O=Sun Microsystems Inc, C=US(These refer to the subject's common name, organizational unit, organization, and country, respectively)
- Public Key
This is the public key of the entity named by the subject name.
- Issuer Name
The X.500 Distinguished Name of the entity that signed the certificate. This is normally a Certification Authority (CA). Using this certificate implies trusting the entity that signed this certificate. (Note that in some cases, such as root or top-level CA certificates, the issuer signs its own certificate.)
- Serial Number
The entity that creates a certificate is responsible for assigning it a serial number to distinguish it from other certificates it generates.
- Validity Period
Each certificate is valid only for a limited amount of time. This period is described by a start date and time and an end date and time, and can be as short as a few seconds or almost as long as a century.Those base features are part of X.509 Version 1, the first version. X.509 Version 1 has been available since 1988, is widely deployed, and is the most generic.
X.509 Version 2 introduced the concept of subject and issuer unique identifiers to handle the possibility of reuse of subject and/or issuer names over time. Most certificate profile documents strongly recommend that names not be reused, and that certificates should not make use of unique identifiers. Version 2 certificates are not widely used.
X.509 Version 3 is the most recent (1996) and supports the notion of extensions, whereby anyone can define an extension and include it in the certificate. Some common extensions in use today are key usage, certificate policies, and subject/issuer alternative name.
X.500 Distinguished Names
X.500 Distinguished Names are used to identify entities, such as those which are named by thesubject
andissuer
(signer) fields of X.509 certificates. keytool supports the following subparts:
- commonName - common name of a person, e.g., "Susan Jones"
- organizationUnit - small organization (e.g, department or division) name, e.g., "Purchasing"
- organizationName - large organization name, e.g., "ABCSystems, Inc."
- localityName - locality (city) name, e.g., "Palo Alto"
- stateName - state or province name, e.g., "California"
- country - two-letter country code, e.g., "CH"
When supplying a distinguished name string as the value of a
-dname
option, as for the-genkey
or-selfcert
commands, the string must be in the following format:CN=cName, OU=orgUnit, O=org, L=city, S=state, C=countryCodewhere all the italicized items represent actual values and the above keywords are abbreviations for the following:
CN=commonName OU=organizationUnit O=organizationName L=localityName S=stateName C=countryA sample distinguished name string is
CN=Mark Smith, OU=JavaSoft, O=Sun, L=Cupertino, S=California, C=USand a sample command using such a string iskeytool -genkey -dname "CN=Mark Smith, OU=JavaSoft, O=Sun, L=Cupertino, S=California, C=US" -alias markCase does not matter for the keyword abbreviations. For example, "CN", "cn", and "Cn" are all treated the same.
Order matters; each subcomponent must appear in the designated order. However, it is not necessary to have all the subcomponents. You may use a subset, for example:
CN=Steve Meier, OU=SunSoft, O=Sun, C=USIf a distinguished name string value contains a comma, it must be escaped by a "\" character, as in
cn=peter schuster, o=Sun Microsystems\, Inc., o=sun, c=usIt is never necessary to specify a distinguished name string on a command line. If it is needed for a command, but not supplied on the command line, the user is prompted for each of the subcomponents.
The Internet RFC 1421 Certificate Encoding Standard
Certificates are often stored using the printable encoding format defined by the Internet RFC 1421 standard, instead of a human-readable format. This certificate format facilitates exporting certificates to other applications.
The
-import
and-printcert
commands expect the certificate they read to be in this format, and the-export
command outputs a certificate in this format, as does the-list
command if the-rfc
option is specified.In this format, the encoded certificate is bounded at the beginning by
-----BEGIN CERTIFICATE-----and at the end by
-----END CERTIFICATE-----Certificate Chains
Each key/certificate entry in a keystore has a private key and an associated certificate "chain". The first certificate in the chain contains the public key corresponding to the private key.
When keys are first generated (see the -genkey command), the chain starts off containing a single element, a self-signed certificate. A self-signed certificate is one for which the issuer (signer) is the same as the subject (the entity whose public key is being authenticated by the certificate). Whenever the
-genkey
command is called to generate a new public/private key pair, it also wraps the public key into a self-signed certificate.Later, after a Certificate Signing Request (CSR) has been generated (see the -csr command) and sent to a Certification Authority (CA), the response from the CA is imported (see -import), and the self-signed certificate is replaced by a chain of certificates. At the bottom of the chain is the certificate (reply) issued by the CA that handled the certificate request. The next certificate in the chain is one that authenticates the CA's public key.
In many cases, this is a self-signed certificate (that is, a certificate from the CA authenticating its own public key) and the last certificate in the chain. In other cases, the CA may return a chain of certificates. In this case, the bottom certificate in the chain is the same (a certificate signed by the CA, authenticating the public key of the key/certificate entry), but the second certificate in the chain is a certificate signed by a different CA, authenticating the public key of the CA you sent the CSR to. Then, the next certificate in the chain will be a certificate authenticating the second CA's key, and so on, until a self-signed "root" certificate is reached. Each certificate in the chain (after the first) thus authenticates the public key of the signer of the previous certificate in the chain.
Many CAs only return the issued certificate, with no supporting chain, especially when there is a flat hierarchy (no intermediates CAs). This is the only reply format currently recognized by keytool. In this case, the certificate chain must be established from trusted certificate information already stored in the keystore.
A different reply format (defined by the PKCS#7 standard) also includes the supporting certificate chain, in addition to the issued certificate. This reply format is currently not handled by keytool, but will be supported in a future version.
The top-level (root) CA certificate is self-signed. However, the trust into the root's public key does not come from the root certificate itself (anybody could generate a self-signed certificate with the distinguished name of say, the VeriSign root CA!), but from other sources like a newspaper. The root CA public key is widely known. The only reason it is stored in a certificate is because this is the format understood by most tools, so the certificate in this case is only used as a "vehicle" to transport the root CA's public key. Before you add the root CA certificate to your keystore, you should view it (using the
-printcert
option) and compare the displayed fingerprint with the well-known fingerprint (obtained from a newspaper, the root CA's webpage, etc.).Importing Certificates
To import a certificate from a file, use the -import command, as in
keytool -import -alias joe -file jcertfile.cerThis sample command imports the certificate in the file jcertfile.cer and stores it in the keystore entry identified by the alias joe.
You import a certificate for two reasons:
- to add it to the list of trusted certificates, or
- to import a certificate reply received from a CA as the result of submitting a Certificate Signing Request (see the -csr command) to that CA.
Which type of import is intended is indicated by the value of the
-alias
option. If the alias exists in the database, and identifies an entry with a private key, then it is assumed you want to import a certificate reply. keytool checks whether the public key in the certificate reply matches the public key stored with the alias, and exits if they are different. If the alias identifies the other type of keystore entry, the certificate will not be imported. If the alias does not exist, then it will be created and associated with the imported certificate.WARNING Re: Importing Trusted Certificates
IMPORTANT: Be sure to check a certificate very carefully before importing it as a trusted certificate!View it first (using the
-printcert
command, or the-import command
without the-noprompt
option), and make sure that the displayed certificate fingerprint(s) match the expected ones. For example, suppose someone sends or emails you a certificate, and you put it in a file named/tmp/cert
. Before you consider adding the certificate to your list of trusted certificates, execute a-printcert
command to view its fingerprints, as inkeytool -printcert -file /tmp/cert Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll Serial Number: 59092b34 Valid from: Thu Sep 25 18:01:13 PDT 1997 until: Wed Dec 24 17:01:13 PST 1997 Certificate Fingerprints: MD5: 11:81:AD:92:C8:E5:0E:A2:01:2E:D4:7A:D7:5F:07:6F SHA1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FEThen call or otherwise contact the person who sent the certificate, and compare the fingerprint(s) that you see with the ones that they show. Only if they are equal is it guaranteed that the certificate has not been replaced in transit with somebody else's (e.g., an attacker's) certificate. If such an attack took place, and you did not check the certificate before you imported it, you would end up trusting anything the attacker has signed (e.g., a JAR file with malicious class files inside).Note: it is not required that you execute a
-printcert
command prior to importing a certificate, since before adding a certificate to the list of trusted certificates in the keystore, the-import
command prints out the certificate information and prompts you to verify it. You then have the option of aborting the import operation. Note, however, this is only the case if you invoke the-import
command without the-noprompt
option. If the-noprompt
option is given, there is no interaction with the user.Exporting Certificates
To export a certificate to a file, use the -export command, as in
keytool -export -alias jane -file janecertfile.cerThis sample command exportsjane
's certificate to the file janecertfile.cer. That is, ifjane
is the alias for a key/certificate entry, the command exports the certificate at the bottom of the certificate chain in that keystore entry. This is the certificate that authenticatesjane
's public key.If, instead,
jane
is the alias for a trusted certificate entry, then that trusted certificate is exported.Displaying Certificates
To print out the contents of a keystore entry, use the -list command, as in
keytool -list -alias joeIf you don't specify an alias, as inkeytool -listthe contents of the entire keystore are printed.To display the contents of a certificate stored in a file, use the -printcert command, as in
keytool -printcert -file certfile.cerThis displays information about the certificate stored in the file
certfile.cer
.Note: This works independently of a keystore, i.e., you do not need a keystore in order to display a certificate that's stored in a file.
Generating a self-signed certificate
A self-signed certificate is one for which the issuer (signer) is the same as the subject (the entity whose public key is being authenticated by the certificate). Whenever the
-genkey
command is called to generate a new public/private key pair, it also wraps the public key into a self-signed certificate.You may occasionally wish to generate a new self-signed certificate. For example, you may want to use the same key pair under a different identity (distinguished name). For example, suppose you change departments. You can then:
To generate a self-signed certificate, use the -selfcert command, as in
- copy (clone) the original key/certificate entry. See -keyclone.
- generate a new self-signed certificate for the cloned entry, using your new distinguished name. See below.
- generate a Certificate Signing Requests for the cloned entry, and import the reply certificate. See the -csr and -import commands.
- delete the original (now obsolete) entry. See -delete.
keytool -selfcert -alias dukeNew -keypass b92kqmp -dname "cn=Duke Smith, ou=Purchasing, o=BlueSoft, c=US"The generated certificate is stored as a single-element certificate chain in the keystore entry identified by the specified alias (in this case "dukeNew"), where it replaces the existing certificate chain.
The various commands and their options are listed and described below . Note:
- All command and option names are preceded by a minus sign (-).
- The options for each command may be provided in any order.
- All items not italicized or in braces or square brackets are required to appear as is.
- Braces surrounding an option signify that a default value will be used if the option is not specified on the command line.
- Brackets surrounding an option signify that the user is prompted for the value(s) if the option is not specified on the command line. (For a
-keypass
option, if you do not specify the option on the command line, keytool will first attempt to use the keystore password to recover the private key, and if this fails, will then prompt you for the private key password.)
- Items in italics (option values) represent the actual values that must be supplied. For example, here is the format of the
-printcert
command:keytool -printcert {-file cert_file} {-v}When specifying a
-printcert
command, replace cert_file with the actual file name, as in:keytool -printcert -file VScert.cer
- Option values must be quoted if they contain a blank (space).
- The
-list
command is the default. Thus, the command linekeytoolis equivalent tokeytool -listOption Defaults
Below are the defaults for various option values.-alias "mykey" -keyalg "DSA" -keysize 1024 -sigalg "DSA/SHA-1" -validity 90 -keystore the file named .keystore in the user's home directory -file stdin if reading, stdout if writingOptions that Appear for Most Commands
The-v
option can appear for all commands except-help
. If it appears, it signifies "verbose" mode; detailed certificate information will be output.There are two options that may appear for all commands operating on a keystore:
-keystore keystore
- The keystore (database file) location. Defaults to the file .keystore in the user's home directory, as determined by the "user.home" system property.
-storepass storepass
- The password which is used to protect the integrity of the keystore.
storepass must be at least 6 characters long. It must be provided to all commands that modify the keystore contents. For such commands, if a
-storepass
option is not provided at the command line, the user is prompted for it.When retrieving information from the keystore, the password is optional; if no password is given, the integrity of the retrieved information cannot be checked and a warning is displayed.
Be careful with passwords - see Warning Regarding Passwords.
Warning Regarding Passwords
Most commands operating on a keystore require the store password. Some commands require a private key password.
Passwords can be specified on the command line (in the
-storepass
and-keypass
options, respectively). However, a password should not be specified on a command line or in a script unless it is for testing purposes, or you are on a secure system.If you don't specify a required password option on a command line, you will be prompted for it. When typing in a password at the password prompt, the password is echoed (displayed exactly as typed), so be careful not to type it in front of anyone.
See also the Command and Option Notes.Adding Data to the Keystore
-genkey {-alias alias} {-keyalg keyalg} {-keysize keysize} {-sigalg sigalg} [-dname dname] [-keypass keypass] {-validity valDays} {-keystore keystore} [-storepass storepass] {-v}
Generates a key pair (a public key and associated private key). Wraps the public key into an X.509 v1 self-signed certificate, which is stored as a single-element certificate chain. This certificate chain and the private key are stored in a new keystore entry identified by alias.
keyalg specifies the algorithm to be used to generate the key pair, and keysize specifies the size of each key to be generated. sigalg specifies the algorithm that should be used to sign the self-signed certificate; this algorithm must be compatible with keyalg. See Supported Algorithms and Key Sizes.
dname specifies the X.500 Distinguished Name to be associated with alias, and is used as the
issuer
andsubject
fields in the self-signed certificate. If no distinguished name is provided at the command line, the user will be prompted for one.keypass is a password used to protect the private key of the generated key pair. If no password is provided, the user is prompted for it. If you press RETURN at the prompt, the key password is set to the same password as that used for the keystore. keypass must be at least 6 characters long. Be careful with passwords - see Warning Regarding Passwords.
valDays tells the number of days for which the certificate should be considered valid.
-import {-alias alias} {-file cert_file} [-keypass keypass] {-noprompt} {-keystore keystore} [-storepass storepass] {-v}
Reads the certificate from the file cert_file, and stores it in the keystore entry identified by alias. If no file is given, the certificate is read from stdin.
keytool can import X.509 v1, v2, and v3 certificates. The certificate must be provided in printable encoding format, as defined by the Internet RFC 1421 standard.
When importing a new trusted certificate, alias must not yet exist in the keystore. Be very careful to ensure the certificate is valid prior to importing it as a "trusted" certificate! -- see WARNING Re: Importing Trusted Certificates. Before adding a certificate to the list of trusted certificates in the keystore, the certificate information is printed out, and the user is prompted to verify it, e.g., by comparing the displayed certificate fingerprints with the fingerprints obtained from some other (trusted) source of information, which might be the certificate owner himself/herself. The user then has the option of aborting the import operation. If the
-noprompt
option is given, however, there will be no interaction with the user.When importing a certificate reply, the certificate reply is validated using trusted certificates from the keystore, until a self-signed certificate (belonging to a root CA) is reached. The certificate reply and the hierarchy of certificates used to authenticate the certificate reply form the new certificate chain of alias, and replace the old certificate chain associated with this entry. The old chain can only be replaced if a valid keypass, the password used to protect the private key of the entry, is supplied. If no password is provided, and the private key password is different from the keystore password, the user is prompted for it. Be careful with passwords - see Warning Regarding Passwords.
-selfcert {-alias alias} {-sigalg sigalg} {-dname dname} {-validity valDays} [-keypass keypass] {-keystore keystore} [-storepass storepass] {-v}
Generates an X.509 v1 self-signed certificate, using keystore information including the private key and public key associated with alias. If dname is supplied at the command line, it is used as the X.500 Distinguished Name for both the
issuer
andsubject
of the certificate. Otherwise, the X.500 Distinguished Name associated with alias (at the bottom of its existing certificate chain) is used.The generated certificate is stored as a single-element certificate chain in the keystore entry identified by alias, where it replaces the existing certificate chain.
sigalg specifies the algorithm that should be used to sign the certificate. See Supported Algorithms and Key Sizes.
In order to access the private key, the appropriate password must be provided, since private keys are protected in the keystore with a password. If keypass is not provided at the command line, and is different from the password used to protect the integrity of the keystore, the user is prompted for it. Be careful with passwords - see Warning Regarding Passwords.
valDays tells the number of days for which the certificate should be considered valid.
Exporting Data
-csr {-alias alias} {-sigalg sigalg} {-file csr_file} [-keypass keypass] {-keystore keystore} [-storepass storepass] {-v}
Generates a Certificate Signing Request (CSR), using the PKCS#10 format.
A CSR is intended to be sent to a certificate authority (CA). The CA will authenticate the certificate requestor (usually off-line) and will return a certificate or certificate chain, used to replace the existing certificate chain (which initially consists of a self-signed certificate) in the keystore.
The private key and X.500 Distinguished Name associated with alias are used to create the PKCS#10 certificate request. In order to access the private key, the appropriate password must be provided, since private keys are protected in the keystore with a password. If keypass is not provided at the command line, and is different from the password used to protect the integrity of the keystore, the user is prompted for it.
Be careful with passwords - see Warning Regarding Passwords.
sigalg specifies the algorithm that should be used to sign the CSR. See Supported Algorithms and Key Sizes.
The CSR is stored in the file csr_file. If no file is given, the CSR is output to stdout.
Use the import command to import the response from the CA.
-export {-alias alias} {-file cert_file} {-keystore keystore} {-storepass storepass} {-v}
Reads (from the keystore) the certificate associated with alias, and stores it in the file cert_file.
If no file is given, the certificate is output to stdout. The certificate is output in printable encoding format, as defined by the Internet RFC 1421 standard.
If alias refers to a trusted certificate, that certificate is output. Otherwise, alias refers to a key entry with an associated certificate chain. In that case, the first certificate in the chain is returned. This certificate authenticates the public key of the entity addressed by alias.
Displaying Data
-list {-alias alias} {-keystore keystore} {-storepass storepass} {-v | -rfc}
Prints (to stdout) the contents of the keystore entry identified by alias. If no alias is specified, the contents of the entire keystore are printed.
If the
-rfc
option is specified, then certificate contents will be printed using the printable encoding format as defined by the Internet RFC 1421 standard, instead of a human-readable format.You cannot specify both
-v
and-rfc
.
-printcert {-file cert_file} {-v}
Reads the certificate from the file cert_file, and prints its contents in a human-readable format. If no file is given, the certificate is read from stdin.
The certificate must be provided in printable encoding format, as defined by the Internet RFC 1421 standard.
Note: This option can be used independently of a keystore.
Managing the Keystore
-keyclone {-alias alias} [-dest dest_alias] [-keypass keypass] [-new new_keypass] {-keystore keystore} [-storepass storepass] {-v}
Creates a new keystore entry, which has the same private key and certificate chain as the original entry.
The original entry is identified by alias (which defaults to "mykey" if not provided). The new (destination) entry is identified by dest_alias. If no destination alias is supplied at the command line, the user is prompted for it.
If the private key password is different from the keystore password, then the entry will only be cloned if a valid keypass is supplied. This is the password used to protect the private key associated with alias. If no key password is supplied at the command line, and the private key password is different from the keystore password, the user is prompted for it. The private key in the cloned entry may be protected with a different password, if desired. If no
-new
option is supplied at the command line, the user is prompted for the new entry's password (and may choose to let it be the same as for the cloned entry's private key).Be careful with passwords - see Warning Regarding Passwords.
This command can be used to establish multiple certificate chains corresponding to a given key pair, or for backup purposes.
-storepasswd {-new new_storepass} {-keystore keystore} [-storepass storepass] {-v}
Changes the password used to protect the integrity of the keystore contents. The new password is new_storepass, which must be at least 6 characters long.
Be careful with passwords - see Warning Regarding Passwords.
-keypasswd {-alias alias} [-keypass old_keypass] [-new new_keypass] {-keystore keystore} [-storepass storepass] {-v}
Changes the password under which the private key identified by alias is protected, from old_keypass to new_keypass.
If the
-keypass
option is not provided at the command line, and the private key password is different from the keystore password, the user is prompted for it.If the
-new
option is not provided at the command line, the user is prompted for it.
Be careful with passwords - see Warning Regarding Passwords.
-delete [-alias alias] {-keystore keystore} [-storepass storepass] {-v}
Deletes from the keystore the entry identified by alias. The user is prompted for the alias, if no alias is provided at the command line.
Getting Help
-help
Lists all the commands and their options.
Passing a Flag to the Runtime System
-Jflag
Passes the specified flag directly to the runtime system. For a list of possible flags, type
java -h
orjava -X
at the command line.
Suppose you want to create a keystore for managing your public/private key pair and certificates from entities you trust.
Generating Your Key Pair
The first thing you need to do is create a keystore and generate the key pair. You could use a command such as the following:
keytool -genkey -dname "cn=Mark Jones, ou=JavaSoft, o=Sun, c=US" -alias business -keypass kpi135 -keystore \working\mykeystore -storepass ab987c -validity 180(Please note: This must be typed as a single line. Multiple lines are used in the examples just for legibility purposes.)
This command creates the keystore named "mykeystore" in the "working" directory (assuming it doesn't already exist), and assigns it the password "ab987c". It generates a public/private key pair for the entity whose "distinguished name" has a common name of "Mark Jones", organizational unit of "JavaSoft", organization of "Sun" and two-letter country code of "US". It uses the default "DSA" key generation algorithm to create the keys, both 1024 bits long.
It creates a self-signed certificate (using the default "DSA/SHA-1" signature algorithm) that includes the public key and the distinguished name information. This certificate will be valid for 180 days, and is associated with the private key in a keystore entry referred to by the alias "business". The private key is assigned the password "kpi135".
The command could be significantly shorter if option defaults were accepted. As a matter of fact, no options are required; defaults are used for unspecified options that have default values, and you are prompted for any required values. Thus, you could simply have the following:
keytool -genkeyIn this case, a keystore entry with alias "mykey" is created, with a newly-generated key pair and a certificate that is valid for 90 days. This entry is placed in the keystore named ".keystore" in your home directory. (The keystore is created if it doesn't already exist.) You will be prompted for the distinguished name information, the keystore password, and the private key password.The rest of the examples assume you executed the
-genkey
command without options specified, and that you responded to the prompts with values equal to those given in the first-genkey
command, above (a private key password of "kpi135", etc.)Requesting a Signed Certificate from a Certification Authority
So far all we've got is a self-signed certificate. A certificate is more likely to be trusted by others if it is signed by a Certification Authority (CA). To get such a signature, you first generate a Certificate Signing Request (CSR), via the following:
keytool -csr -file MarkJ.csrThis creates a CSR (for the entity identified by the default alias "mykey") and puts the request in the file named "MarkJ.csr". Submit this file to a CA, such as VeriSign, Inc. The CA will authenticate you, the requestor (usually off-line), and then will return a certificate, signed by them, authenticating your public key. (In some cases, they will actually return a chain of certificates, each one authenticating the public key of the signer of the previous certificate in the chain.)Importing a Certificate for the CA
You need to replace your self-signed certificate with the one from the CA. But first you need a "trusted certificate" entry in your keystore that authenticates the CA's public key, so their signature, e.g., on the certificate they send to you in response to your CSR, can be verified.
A certificate from a CA is usually either self-signed, or signed by another CA (in which case you need a certificate authenticating that CA's public key). Suppose you obtain a file named "VeriSign.cer" that is purportedly a self-signed certificate from VeriSign, Inc., authenticating that CA's public key. Be very careful to ensure the certificate is valid prior to importing it as a "trusted" certificate! If you trust that this certificate is valid, then you can add it to your keystore via the following:
keytool -import -alias vs -file VeriSign.cerThis creates a "trusted certificate" entry in the keystore, with the data from the file "VeriSign.cer", and assigns the alias "vs" to the entry.Importing the Certificate Reply from the CA
Now you can replace your self-signed certificate with the one from VeriSign via the following, which assumes the returned certificate is named "VSMarkJ.cer":
keytool -import -file VSMarkJ.cerWhen a certificate reply is imported, it is validated using trusted certificates from the keystore (in this case the one authenticating VeriSign's public key), until a self-signed certificate (belonging to a root CA) is reached. The certificate reply and the hierarchy of certificates used to authenticate the certificate reply (in this case, just the self-signed certificate authenticating VeriSign's public key) form the new certificate chain.
Exporting a Certificate Authenticating Your Public Key
Suppose you have used the jarsigner tool to sign a Java ARchive (JAR) file. Clients that want to use the file will want to authenticate your signature.In order to do so, they need your public key. You supply this to them by sending them a copy of the certificate authenticating your public key. Copy that certificate to a file named
MJ.cer
via the following:keytool -export -alias mykey -file MJ.cerGiven that certificate, and the signed JAR file, a client can use the jarsigner tool to authenticate your signature.Changing Your Distinguished Name but Keeping your Key Pair
Suppose your distinguished name changes, for example because you have changed departments or moved to a different city. If desired, you may still use the public/private key pair you've previously used, and yet update your distinguished name. For example, suppose your name is Susan Miller, and you created your initial key/certificate entry with the aliassMiller
and the distinguished name"cn=Susan Miller, ou=Finance Department, o=BlueSoft, c=us"Suppose you change from the Finance Department to the Accounting Department. You can still use the previously-generated public/private key pair and yet update your distinguished name by doing the following. First, copy (clone) your key/certificate entry:keytool -keyclone -alias sMiller -dest sMillerNew(This prompts for the initial and destination private key passwords, since they aren't provided at the command line.) Now you need to change the certificate chain associated with the copy, so that the first certificate in the chain uses your different distinguished name. Start by generating a self-signed certificate with the appropriate name:keytool -selfcert -alias sMillerNew -dname "cn=Susan Miller, ou=Accounting Department, o=BlueSoft, c=us"Then generate a Certificate Signing Request based on the information in this new certificate:
keytool -csr -alias sMillerNewWhen you get the CA certificate reply, import it:keytool -import -alias sMillerNew -file VSSMillerNew.cerAfter importing the certificate reply, you may want to remove the initial key/certificate entry that used your old distinguished name:keytool -delete -alias sMiller