keytool

This qualifier specifies the type of keystore to be instantiated.

• {-rfc}: Output in RFC (Request For Comment) style

• {-infile infile}: Input file name

• {-outfile outfile}: Output file name

• {-alias alias}: Alias name of the entry to process

• {-sigalg sigalg}: Signature algorithm name

• {-dname dname}: Distinguished name

• {-startdate startdate}: Certificate validity start date and time

• {-ext ext}*: X.509 extension

• {-validity days}: Validity number of days

• [-keypass arg]: Key password

• {-keystore keystore}: Keystore name

• [-storepass arg]: Keystore password

• {-storetype type}: Keystore type

• {-providername name}: Provider name

• {-providerclass class [-providerarg arg]}: Add security provider by fully qualified class name with an optional configure argument. For example, if MyProvider is a legacy provider loaded via reflection,

  keytool -providerclass com.example.MyProvider ...

• {-providerpath list}: Provider classpath

• {-v}: Verbose output

• {-protected}: Password provided through a protected mechanism

Generates a certificate as a response to a certificate request file (which can be created by the keytool -certreq command). The command reads the request from infile (if omitted, from the standard input), signs it using alias's private key, and outputs the X.509 certificate into outfile (if omitted, to the standard output). When-rfc is specified, the output format is Base64-encoded PEM; otherwise, a binary DER is created.

The sigalg value specifies the algorithm that should be used to sign the certificate. The startdate argument is the start time and date that the certificate is valid. The valDays argument tells the number of days for which the certificate should be considered valid.

When dname is provided, it is used as the subject of the generated certificate. Otherwise, the one from the certificate request is used.

The ext value shows what X.509 extensions will be embedded in the certificate. Read Common Options for the grammar of -ext.

The -gencert option enables you to create certificate chains. The following example creates a certificate, e1, that contains three certificates in its certificate chain.

The following commands creates four key pairs named ca, ca1, ca2, and e1:

keytool -alias ca -dname CN=CA -genkeypair
keytool -alias ca1 -dname CN=CA -genkeypair
keytool -alias ca2 -dname CN=CA -genkeypair
keytool -alias e1 -dname CN=E1 -genkeypair

The following two commands create a chain of signed certificates; ca signs ca1 and ca1 signs ca2, all of which are self-issued:

keytool -alias ca1 -certreq |
    keytool -alias ca -gencert -ext san=dns:ca1 |
    keytool -alias ca1 -importcert

keytool -alias ca2 -certreq |
    $KT -alias ca1 -gencert -ext san=dns:ca2 |
    $KT -alias ca2 -importcert

The following command creates the certificate e1 and stores it in the file e1.cert, which is signed by ca2. As a result, e1 should contain ca, ca1, and ca2 in its certificate chain:

keytool -alias e1 -certreq | keytool -alias ca2 -gencert > e1.cert

• {-alias alias}: Alias name of the entry to process

• {-keyalg alg}: Key algorithm name

• {-keysize size}: Key bit size

• {-groupname name}: Group name. For example, an Elliptic Curve name

• {-sigalg alg}: Signature algorithm name

• -destalias alias: Destination alias

• [-dname name]: Distinguished name

• {-startdate date}: Certificate validity start date and time

• [-ext value]*: X.509 extension

• {-validity days}: Validity number of days

• [-keypass arg]: Key password

• {-keystore keystore}: Keystore name

• [-storepass arg]: Keystore password

• {-storetype type}: Keystore type

• {-providername name}: Provider name

• {-providerclass class [-providerarg arg]}: Add security provider by fully qualified class name with an optional configure argument.

• {-providerpath list}: Provider classpath

• {-v}: Verbose output

• {-protected}: Password provided through a protected mechanism

Generates a key pair (a public key and associated private key). Wraps the public key into an X.509 v3 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.

The keyalg value specifies the algorithm to be used to generate the key pair, and the keysize value specifies the size of each key to be generated. The sigalg value specifies the algorithm that should be used to sign the self-signed certificate. This algorithm must be compatible with the keyalg value.

The groupname value specifies a named group when generating a key pair. The groupname option is preferred over the keysize option because there may be more than one curve of the same size. For example:

keytool -genkeypair -keyalg EC -groupname secp384r1

will generate an Elliptic Curve key pair by using the secp384r1 curve.

The dname value specifies the X.500 Distinguished Name to be associated with the value of alias, and is used as the issuer and subject fields in the self-signed certificate. If no distinguished name is provided at the command line, then the user is prompted for one.

The value of keypass is a password used to protect the private key of the generated key pair. If no password is provided, then the user is prompted for it. If you press the Return key at the prompt, then the key password is set to the same password as the keystore password. The keypass value must be at least 6 characters.

The value of startdate specifies the issue time of the certificate, also known as the "Not Before" value of the X.509 certificate's Validity field.

The option value can be set in one of these two forms:

([+-]nnn[ymdHMS])+

[yyyy/mm/dd] [HH:MM:SS]

With the first form, the issue time is shifted by the specified value from the current time. The value is a concatenation of a sequence of subvalues. Inside each subvalue, the plus sign (+) means shift forward, and the minus sign (-) means shift backward. The time to be shifted is nnn units of years, months, days, hours, minutes, or seconds (denoted by a single character of y, m, d, H, M, or S respectively). The exact value of the issue time is calculated using the java.util.GregorianCalendar.add(int field, int amount) method on each subvalue, from left to right. For example, by specifying, the issue time will be:

Calendar c = new GregorianCalendar();
c.add(Calendar.YEAR, -1);
c.add(Calendar.MONTH, 1);
c.add(Calendar.DATE, -1);
return c.getTime()

With the second form, the user sets the exact issue time in two parts, year/month/day and hour:minute:second (using the local time zone). The user can provide only one part, which means the other part is the same as the current date (or time). The user must provide the exact number of digits as shown in the format definition (padding with 0 when shorter). When both the date and time are provided, there is one (and only one) space character between the two parts. The hour should always be provided in 24 hour format.

When the option is not provided, the start date is the current time. The option can be provided at most once.

The value of valDays specifies the number of days (starting at the date specified by -startdate, or the current date when -startdate is not specified) for which the certificate should be considered valid.

This command was named -genkey in earlier releases. The old name is still supported in this release. The new name, -genkeypair, is preferred going forward.

• {-alias alias}: Alias name of the entry to process

• [-keypass arg] : Key password

• {-keyalg alg}: Key algorithm name

• {-keysize size}: Key bit size

• {-keystore keystore}: Keystore name

• [-storepass arg]: Keystore password

• {-storetype type}: Keystore type

• {-providername name}: Provider name

• {-providerclass class [providerarg arg]}: Add security provider by fully qualified class name with an optional configure argument.

• {-providerpath list}: Provider classpath

• {-v}: Verbose output

• {-protected}: Password provided through a protected mechanism

Generates a secret key and stores it in a new KeyStore.SecretKeyEntry identified by alias.

The value of keyalg specifies the algorithm to be used to generate the secret key, and the value of keysize specifies the size of the key to be generated. The keypass value is a password that protects the secret key. If no password is provided, then the user is prompted for it. If you press the Return key at the prompt, then the key password is set to the same password that is used for the keystore. The keypass value must be at least 6 characters.

• {-alias alias}: Alias name of the entry to process

• [-keypass arg]: Key password

• {-keyalg alg}: Key algorithm name

• {-keysize size}: Key bit size

• {-keystore keystore}: Keystore name

• [-storepass arg]: Keystore password

• {-storetype type}: Keystore type

• {-providername name}: Provider name

• {-providerclass class [-providerarg arg]}: Add security provider by fully qualified class name with an optional configure argument.

• {-providerpath list}: Provider classpath

• {-v}: Verbose output

• {-protected}: Password provided through a protected mechanism

Imports a passphrase and stores it in a new KeyStore.SecretKeyEntry identified by alias. The passphrase may be supplied via the standard input stream; otherwise the user is prompted for it. keypass is a password used to protect the imported passphrase. If no password is provided, the user is prompted for it. If you press the Return key 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.

• {-srckeystore keystore}: Source keystore name

• {-destkeystore keystore}: Destination keystore name

• {-srcstoretype type}: Source keystore type

• {-deststoretype type}: Destination keystore type

• [-srcstorepass arg]: Source keystore password

• [-deststorepass arg]: Destination keystore password

• {-srcprotected Source keystore password protected

• {-srcprovidername name}: Source keystore provider name

• {-destprotected}: Destination keystore password protected

• {-destprovidername name}: Destination keystore provider name

• {-srcalias alias}: Source alias

• {-destalias alias}: Destination alias

• [-srckeypass arg]: Source key password

• [-destkeypass arg]: Destination key password

• {-noprompt}: Do not prompt

• {-providerclass class [-providerarg arg]}: Add security provider by fully qualified class name with an optional configure argument

• {-providerpath list}: Provider classpath

• {-v}: Verbose output

Imports a single entry or all entries from a source keystore to a destination keystore.

When the -srcalias option is provided, the command imports the single entry identified by the alias to the destination keystore. If a destination alias is not provided with destalias, then srcalias is used as the destination alias. If the source entry is protected by a password, then srckeypass is used to recover the entry. If srckeypass is not provided, then the keytool command attempts to use srcstorepass to recover the entry. If srcstorepass is either not provided or is incorrect, then the user is prompted for a password. The destination entry is protected with destkeypass. If destkeypass is not provided, then the destination entry is protected with the source entry password. For example, most third-party tools require storepass and keypass in a PKCS #12 keystore to be the same. In order to create a PKCS #12 keystore for these tools, always specify a -destkeypass to be the same as -deststorepass.

If the -srcalias option is not provided, then all entries in the source keystore are imported into the destination keystore. Each destination entry is stored under the alias from the source entry. If the source entry is protected by a password, then srcstorepass is used to recover the entry. If srcstorepass is either not provided or is incorrect, then the user is prompted for a password. If a source keystore entry type is not supported in the destination keystore, or if an error occurs while storing an entry into the destination keystore, then the user is prompted whether to skip the entry and continue or to quit. The destination entry is protected with the source entry password.

If the destination alias already exists in the destination keystore, then the user is prompted to either overwrite the entry or to create a new entry under a different alias name.

If the -noprompt option is provided, then the user is not prompted for a new destination alias. Existing entries are overwritten with the destination alias name. Entries that cannot be imported are skipped and a warning is displayed.

• {-file file}: Input file name

• {-v}: Verbose output

Prints the content of a PKCS #10 format certificate request, which can be generated by the keytool -certreq command. The command reads the request from file. If there is no file, then the request is read from the standard input.

• {-alias alias}: Alias name of the entry to process

• {-sigalg alg}: Signature algorithm name

• {-file file}: Output file name

• [-keypass arg]: Key password

• {-keystore keystore}: Keystore name

• {-dname name}: Distinguished name

• [-storepass arg]: Keystore password

• {-storetype type}: Keystore type

• {-providername name}: Provider name

• {-providerclass class [-providerarg arg]}: Add security provider by fully qualified class name with an optional configure argument.

• {-providerpath list}: Provider classpath

• {-v}: Verbose output

• {-protected }: Password provided through a protected mechanism

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 authenticates 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 associated with alias is used to create the PKCS #10 certificate request. To access the private key, the correct password must be provided. If keypass is not provided at the command line and is different from the password used to protect the integrity of the keystore, then the user is prompted for it. If dname is provided, then it is used as the subject in the CSR. Otherwise, the X.500 Distinguished Name associated with alias is used.

The sigalg value specifies the algorithm that should be used to sign the CSR.

The CSR is stored in the file certreq_file. If no file is specified, then the CSR is output to stdout.

Use the importcert command to import the response from the CA.

• -file crl: Input file name

• {-v}: Verbose output

Reads the Certificate Revocation List (CRL) from the file crl. A CRL is a list of digital certificates that were revoked by the CA that issued them. The CA generates the crl file.

Note: This option can be used independently of a keystore.

• [-new arg]: New password

• {-keystore keystore}: Keystore name

• [-storepass arg]: Keystore password

• {-storetype type}: Keystore type

• {-providername name}: Provider name

• {-providerclass class [-providerarg arg]}: Add security provider by fully qualified class name with an optional configure argument.

• {-providerpath list}: Provider classpath

• {-v}: Verbose output

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.

• {-alias alias}: Alias name of the entry to process

• [-keypass old_keypass]: Key password

• [-new new_keypass]: New password

• {-keystore keystore}: Keystore name

• {-storepass arg}: Keystore password

• {-storetype type}: Keystore type

• {-providername name}: Provider name

• {-providerclass class [-providerarg arg]}: Add security provider by fully qualified class name with an optional configure argument.

• {-providerpath list}: Provider classpath

• {-v}: Verbose output

Changes the password under which the private/secret key identified by alias is protected, from old_keypass to new_keypass, which must be at least 6 characters.

If the -keypass option is not provided at the command line, and the key password is different from the keystore password, then the user is prompted for it.

If the -new option is not provided at the command line, then the user is prompted for it

• [-alias alias]: Alias name of the entry to process

• {-keystore keystore}: Keystore name

• [-storepass arg]: Keystore password

• {-storetype type}: Keystore type

• {-providername name}: Provider name

• {-providerclass class [-providerarg arg]}: Add security provider by fully qualified class name with an optional configure argument.

• {-providerpath list}: Provider classpath

• {-v}: Verbose output

• {-protected}: Password provided through a protected mechanism

Deletes from the keystore the entry identified by alias. The user is prompted for the alias, when no alias is provided at the command line.

• {-alias alias}: Alias name of the entry to process

• [-destalias alias]: Destination alias

• [-keypass arg]: Key password

• {-keystore keystore}: Keystore name

• [-storepass arg]: Keystore password

• {-storetype type}: Keystore type

• {-providername name}: Provider name

• {-providerclass class [-providerarg arg]}: Add security provider by fully qualified class name with an optional configure argument.

• {-providerpath list}: Provider classpath

• {-v}: Verbose output

• {-protected}: Password provided through a protected mechanism

Move an existing keystore entry from the specified alias to a new alias, destalias. If no destination alias is provided, then the command prompts for one. If the original entry is protected with an entry password, then the password can be supplied with the -keypass option. If no key password is provided, then the storepass (if provided) is attempted first. If the attempt fails, then the user is prompted for a password.

Lists the basic commands and their options.

For more information about a specific command, enter the following, where command_name is the name of the command: keytool -command_name -help.

A keystore is a storage facility for cryptographic keys and certificates.

A certificate (or public-key certificate) is a digitally signed statement from one entity (the issuer), saying that the public key and some other information of another entity (the subject) has some specific value. The following terms are related to certificates:

Public Keys: These are numbers associated with a particular entity, and are intended to be known to everyone who needs to have trusted interactions with that entity. Public keys are used to verify signatures.

Digitally Signed: If some data is digitally signed, then it is stored with the identity of an entity and a signature that proves that entity knows about the data. The data is rendered unforgeable by signing with the entity's private key.

Identity: A known way of addressing an entity. In some systems, the identity is the public key, and in others it can be anything from an Oracle Solaris UID to an email address to an X.509 distinguished name.

Signature: A signature is computed over some data using the private key of an entity. The signer, which in the case of a certificate is also known as the issuer.

Private Keys: These are numbers, each of which is supposed to be known only to the particular entity whose private key it is (that is, it is supposed to be kept secret). Private and public keys exist in pairs in all public key cryptography systems (also referred to as public key crypto systems). In a typical public key crypto system, such as DSA, a private key corresponds to exactly one public key. Private keys are used to compute signatures.

Entity: An entity is a person, organization, program, computer, business, bank, or something else you are trusting to some degree.

Public key cryptography requires access to users' public keys. In a large-scale networked environment, it is impossible to guarantee that prior relationships between communicating entities were established or that a trusted repository exists with all used public keys. Certificates were invented as a solution to this public key distribution problem. Now a Certification Authority (CA) can act as a trusted third party. CAs are entities such as businesses that are trusted to sign (issue) certificates for other entities. It is assumed that CAs only create valid and reliable certificates because they are bound by legal agreements. There are many public Certification Authorities, such as VeriSign, Thawte, Entrust, and so on.

You can also run your own Certification Authority using products such as Microsoft Certificate Server or the Entrust CA product for your organization. With the keytool command, it is possible to display, import, and export certificates. It is also possible to generate self-signed certificates.

The keytool command currently handles X.509 certificates.

A certificates file named cacerts resides in the security properties directory, java.home\lib\security on Windows and java.home/lib/security on Oracle Solaris, where java.home is the runtime environment's directory, which would be the jre directory in the SDK or the top-level directory of the JRE.

The cacerts file represents a system-wide keystore with CA certificates. System administrators can configure and manage that file with the keytool command by specifying jks as the keystore type. The cacerts keystore file ships with a default set of root CA certificates. You can list the default certificates with the following command:

keytool -list -keystore java.home\lib\security\cacerts

The initial password of the cacerts keystore file is changeit. System administrators should change that password and the default access permission of that file upon installing the SDK.

Note: It is important to verify your cacerts file. Because you trust the CAs in the cacerts file as entities for signing and issuing certificates to other entities, you must manage the cacerts file carefully. The cacerts file should contain only certificates of the CAs you trust. It is your responsibility to verify the trusted root CA certificates bundled in the cacerts file and make your own trust decisions.

To remove an untrusted CA certificate from the cacerts file, use the delete option of the keytool command. You can find the cacerts file in the JRE installation directory. Contact your system administrator if you do not have permission to edit this file

Certificates are often stored using the printable encoding format defined by the Internet RFC 1421 standard, instead of their binary encoding. This certificate format, also known as Base64 encoding, makes it easy to export certificates to other applications by email or through some other mechanism.

Certificates read by the -importcert and -printcert commands can be in either this format or binary encoded. The -exportcert command by default outputs a certificate in binary encoding, but will instead output a certificate in the printable encoding format, when the -rfc option is specified.

The -list command by default prints the SHA256 fingerprint of a certificate. If the -v option is specified, then the certificate is printed in human-readable format. If the -rfc option is specified, then the certificate is output in the printable encoding format.

In its printable encoding format, the encoded certificate is bounded at the beginning and end by the following text:

-----BEGIN CERTIFICATE-----

encoded certificate goes here. 

-----END CERTIFICATE-----

X.500 Distinguished Names are used to identify entities, such as those that are named by the subject and issuer (signer) fields of X.509 certificates. The keytool command supports the following subparts:

commonName: The common name of a person such as Susan Jones.

organizationUnit: The small organization (such as department or division) name. For example, Purchasing.

localityName: The locality (city) name, for example, Palo Alto.

stateName: State or province name, for example, California.

country: Two-letter country code, for example, CH.

When you supply a distinguished name string as the value of a -dname option, such as for the -genkeypair command, the string must be in the following format:

CN=cName, OU=orgUnit, O=org, L=city, S=state, C=countryCode

All the italicized items represent actual values and the previous keywords are abbreviations for the following:

CN=commonName
OU=organizationUnit
O=organizationName
L=localityName
S=stateName
C=country

A sample distinguished name string is:

CN=Mark Smith, OU=Java, O=Oracle, L=Cupertino, S=California, C=US

A sample command using such a string is:

keytool -genkeypair -dname "CN=Mark Smith, OU=Java, O=Oracle, L=Cupertino,
S=California, C=US" -alias mark

Case 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 can use a subset, for example:

CN=Steve Meier, OU=Java, O=Oracle, C=US

If a distinguished name string value contains a comma, then the comma must be escaped by a backslash (\) character when you specify the string on a command line, as in:

cn=Peter Schuster, ou=Java\, Product Development, o=Oracle, c=US

It is never necessary to specify a distinguished name string on a command line. When the distinguished name is needed for a command, but not supplied on the command line, the user is prompted for each of the subcomponents. In this case, a comma does not need to be escaped by a backslash (\).