Keytool

Short Description

Keytool is a tool for managing key pairs, secret keys and certificates.

Keytool usage

keytool {-<command_name>} {-<command_option>} {<option_value>}... -J<java_option> 

Description

The Keytool utility enables managing keys and X.509 certificates used for authentication of an entity or self-authentication. The tool stores the certificates and keys in a keystore database. Keystore is usually implemented as a file and protected with a password. For a more detailed description of the tool, see http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html. The current implementation fully fits this description and features some additional functionality.

Document Overview

This document focuses on the usage aspects of the Harmony implementation of the tool. Currently, the doc lists the Keytool commands and options.

options

This section lists all the options that the current Keytool implementation can use. Each option has a name, a description, and sometimes the default value specified. If the option has no default value and is critical for the command its value is prompted for. The "Y" mark in the Shared column indicates that the option is common for two or more commands. Options and commands can be provided in any order.

Commands

This section lists the Keytool commands with allowed options and a description. If no command is specified "-help" command is assumed.

-certreq {-alias <alias>} {-file <csr_file>} 
{-sigalg <signature_algorithm>} {-keypass <key_password>} 
{-sigprovider <signature_provider_name>} {-ksprovider <keystore_provider_name>} 
{-provider <provider_name>} {-keystore <keystore_path>} {-storepass <store_password>} {-v} 
{-storetype <store_type>} {-cacerts <cacerts_path>} {-cacertspass <cacerts_password>}

Generates a certificate signing request (CSR) based on data taken from the keystore entry associated with the given <alias>. The certificate request is printed to the file <csr_file>, if its name is supplied; otherwise, printed to stdout.

-checkcrl {-file <certificate_file>} {-crlfile <crl_file>} 
{-certprovider <cert_provider_name>} {-mdprovider <MD_provider_name>} {-ksprovider 
<keystore_provider_name>} {-provider <provider_name>} {-keystore <keystore_path>} 
{-storepass <store_password>} {-v} {-storetype <store_type>} {-cacerts <cacerts_path>} 
{-cacertspass <cacerts_password>}

Checks wheter the certificate given in <certificate_file> is in the CRL, which is stored in the <crl_file> file. If the file name is not given, stdin is used.

-convert {-convtype <result_type>} {-convkeystore <result_store>}
{-convstorepass <result_store_pass>} {-convkeys} {-convprovider <convert_provider_name>} 
{-ksprovider <keystore_provider_name>} {-provider <provider_name>} 
{-keystore <keystore_path>} {-storepass <store_password>} {-v} {-storetype 
<store_type>} {-cacerts <cacerts_path>} {-cacertspass <cacerts_password>}

Converts keystore to the type <result_type> and saves it to <result_store> and protects with password <result_store_pass>. If <result_store_pass> is not set, <store_password> is used. If -convkeys option is specified, Keytool tries to convert key entries. Only entries with password equal to the keystore password are converted.

-delete {-alias <alias>} {-ksprovider <keystore_provider_name>}
{-provider <provider_name>} {-keystore <keystore_path>} 
{-storepass <store_password>} {-v} {-storetype <store_type>} {-cacerts <cacerts_path>} 
{-cacertspass <cacerts_password>} 

Removes from the keystore the entry associated with <alias>.

-export {-rfc | -v} {-alias <alias>} {-file <certificate_file>} {-ksprovider <keystore_provider_name>} 
{-provider <provider_name>} {-keystore <keystore_path>} {-storepass <store_password>} 
{-v} {-storetype <store_type>} {-cacerts <cacerts_path>} {-cacertspass <cacerts_password>} 

Reads an X.509 certificate associated with <alias> and prints it into the given <certificate_file> file. If the file name is not given, the certificate is printed to stdout. If -rfc option is used, the certificate is printed in the printable BASE64 encoding (PEM); otherwise, it is printed in the binary encoding (DER).
Options -rfc and -v are not required.

-genkey {-alias <alias>} {-keyalg 
<key_algorithm>} {-keysize <key_size>} {-sigalg <signature_algorithm>} 
{-validity <validity_period>} {-dname <X500_distinguished_dname>} 
{-x509version <X509_version>} {-ca} {-certserial <cert_serial_number>} 
{-secretkey} {-keypass <key_password>} {-issuer <issuer_alias>} {-issuerpass 
<issuer_password>} {-keyprovider <key_provider_name>} {-certprovider <cert_provider_name>} 
{-sigprovider <signature_provider_name>} {-ksprovider <keystore_provider_name>} 
{-provider <provider_name>} {-keystore <keystore_path>} {-storepass <store_password>} 
{-v} {-storetype <store_type>} {-cacerts <cacerts_path>} {-cacertspass <cacerts_password>}  

Generates a key pair or a secret key.

Generating a key pair

A key pair is composed of a private and a public key. For generating a key pair, Keytool does the following:

1. Wraps the public key into a self-signed X.509 (v1, v2, v3) certificate.
2. Puts the certificate into a single-element certificate chain
   OR signs the certificate with private key from another key entry <issuer_alias>.
3. Adds its chain to the newly generated certificate.
   Keytool uses <issuer_password> to recover the <issuer_alias> entry.
4. Adds a new entry with the generated private key and the chain with alias <alias> and protected with <key_password> to the keystore.

The subject of the new certificate is generated based on <X500_distinguished_dname>. If it is not given on the command line, a prompt appears. The certificate validity period is set to <validity_period>. The X.509 certificate version is set to <X509_version> and the certificate serial number is set to <cert_serial_number>. If "-ca" option is specified, the certificate can be used to sign another certificates.

Generating a secret key

If a secret key is generated, it is put into a secret key entry, with a null certificate chain. If the -secretkey option is specified, a secret key is generated instead of the key pair and certificate generated by default.

-help {<command_name>}

Shows a help message for the specified command name with usage details and a description. If no command name is given, the command shows the list of the commands with their short descriptions.

-import {-alias <alias>} {-file <certificate_file>} 
{-noprompt} {-trustcacerts} {-keypass <key_password>} {-cacerts <cacerts_path>} 
{-cacertspass <cacerts_password>} {-certprovider <cert_provider_name>} 
{-mdprovider <MD_provider_name>} {-ksprovider <keystore_provider_name>} 
{-provider <provider_name>} {-keystore <keystore_path>} {-storepass <store_password>} 
{-v} {-storetype <store_type>} {-cacerts <cacerts_path>} {-cacertspass <cacerts_password>} 

Reads an X.509 certificate or a PKCS#7 formatted certificate chain from the file <certificate_file> and puts it into the entry identified by <alias>. If the input file is not specified, Keytool reads the certificates from the standard input. If <alias> already exists, the imported certificate chain is interpreted as a reply to CSR generated for the certificate associated with <alias>. Otherwise, it is considered to be a trusted certificate.

If the -noprompt option is specified, Keytool adds the certificate to the keystore even if an equal certificate is in keystore or the certificate issuer's certificate is not in the keystore (and in cacerts if -trustcacerts option is specified). Otherwise, you are asked to confirm that the certificate should be imported.

-keyclone {-alias <alias>} {-dest <dest_alias>} {-new <new_password>}
{-keypass <key_password>} {-ksprovider <keystore_provider_name>} {-provider <provider_name>}
{-keystore <keystore_path>} {-storepass <store_password>} {-v} 
{-storetype <store_type>} {-cacerts <cacerts_path>} {-cacertspass <cacerts_password>} 

Copies the key and the certificate chain (if any) from the keystore entry identified by <alias> into a newly created one with alias <dest_alias> and protected with password <new_password>. If any of <dest_alias> or <new_password> is not specified it is prompted for.

-keypasswd {-alias <alias>} {-keypass 
<old_key_password>} {-new <new_password>} {-ksprovider <keystore_provider_name>} 
{-provider <provider_name>} {-keystore <keystore_path>} {-storepass <store_password>} 
{-v} {-storetype <store_type>} {-cacerts <cacerts_path>} {-cacertspass <cacerts_password>} 

Changes the key password of the entry associated with alias <alias> to <new_password>.

-list {-rfc | -v} {-alias <alias>} 
{-mdprovider <MD_provider_name>} {-ksprovider <keystore_provider_name>} 
{-provider <provider_name>} {-keystore <keystore_path>} {-storepass <store_password>} 
{-v} {-storetype <store_type>} {-cacerts <cacerts_path>} {-cacertspass <cacerts_password>} 

Prints the contents of the entry associated with the <alias>. If no alias is specified, the contents of the entire keystore is printed. If the -rfc option is used, certificates are printed in printable BASE64 encoding (PEM). Otherwise, Keytool prints these in binary encoding (DER). The -rfc and -v options may not be specified.

-printcert {-v} {-file <certificate_file>} {-certprovider <cert_provider_name>}
{-mdprovider <MD_provider_name>} {-provider <provider_name>}      

Prints a detailed description of the certificate contained in file <certificate_file> in a human-readable format: its owner and issuer, the serial number, the validity period and fingerprints. Keystore is not used.

-selfcert {-alias <alias>} {-dname <X500_distinguished_dname>} 
{-validity <validity_period>} {-sigalg <signature_algorithm>} 
{-keypass <key_password>} {-ca} {-certserial <cert_serial_number>} {-sigprovider 
<signature_provider_name>} {-ksprovider <keystore_provider_name>} 
{-provider <provider_name>} {-keystore <keystore_path>} {-storepass <store_password>} 
{-v} {-storetype <store_type>} {-cacerts <cacerts_path>} {-cacertspass <cacerts_password>} 

Generates an X.509 (v1, v2, v3) self-signed certificate using a key pair associated with <alias>. If X.500 Distinguished Name is supplied, it is used as both the subject and issuer of the certificate. Otherwise, the distinguished name associated with <alias> is used. Keytool can get the signature algorithm, the validity period and the certificate serial number from the command line or from the keystore entry identified by <alias>.

If the -ca option is specified, the generated certificate can be used for signing other certifictes. If the -secretkey option is specified, a secret key is generated instead of the key pair and a certificate generated by default.

-storepasswd  {-new <new_password>} 
{-ksprovider <keystore_provider_name>} {-provider <provider_name>} 
{-keystore <keystore_path>} {-storepass <store_password>} {-v} {-storetype 
<store_type>} {-cacerts <cacerts_path>} {-cacertspass <cacerts_password>}  

Changes the keystore password to <new_password>.

-verify {-file <certificate_file>} 
{-crlfile <crl_file>} {-trustcacerts} {-cacerts <cacerts_path>} 
{-cacertspass <cacerts_password>} {-certprovider <cert_provider_name>} 
{-sigprovider <signature_provider_name>} {-mdprovider <MD_provider_name>}
{-ksprovider <keystore_provider_name>} {-provider <provider_name>} 
{-keystore <keystore_path>} {-storepass <store_password>} {-v} {-storetype <store_type>} 
{-cacerts <cacerts_path>} {-cacertspass <cacerts_password>} 

A cerificate chain is built by looking up the certificate of the issuer of the current certificate. If a certificate is self-signed, it is assumed to be the root CA. After that, Keytool searches the certificates in the lists of revoked certificates. Certificate signatures are checked and the certificate path is built in the same way as in the import operation. If an error occurs, Keytool does not stop the flow unless an attempt to continue is made. The results of the verification are printed to stdout.