Java Keytool

About

Java Keytool is a key and certificate management utility that comes with the Java Development Kit (JDK). It allows users to administer their own public/private key pairs and associated certificates for use in self-authenticated applications or data integrity and authentication services. It provides functionalities for managing keystores, which are repositories for cryptographic keys and certificates used for secure communication in Java applications. Keytool allows tasks like creating, importing, exporting, and managing keys and certificates within a keystore.

circle-info

A keystore is a database file (usually in JKS - Java Key Store format) that stores cryptographic keys and certificates.

TrustStore is a specific type of KeyStore that holds the trusted certificates used to verify the identity of peers.

Keys come in pairs: public and private. Public keys are used for encryption and verification, while private keys are used for decryption and signing.

Certificates are digital documents that bind a public key to an entity (e.g., person, server) and are issued by a Certificate Authority (CA).

Alias is a unique identifier for an entry in a keystore.

Keytool Command Options

keytool -genseckey

keytool -genkeypair and -changealias

keytool -keypasswd and -importkeystore

Key

Generating a Symmetric Key

A symmetric key is a single key used for both encryption and decryption. This is commonly used in algorithms like AES.

  • -genseckey: Generates a secret (symmetric) key.

  • -keyalg AES: Specifies the algorithm (e.g., AES).

  • -keysize 256: Specifies the key size.

Generating an Asymmetric Key Pair

An asymmetric key pair consists of a private key and a public key. These are used in algorithms like RSA for encryption, digital signatures, and key exchange.

  • -genkeypair: Generates an asymmetric key pair.

  • -alias myrsakey: Specifies the alias for the key entry.

  • -keyalg RSA: Specifies the algorithm for the key pair.

  • -keysize 2048: Specifies the key size in bits.

  • -keystore keystore.jks: Specifies the keystore file.

  • -dname: Distinguished Name for the certificate associated with the key pair.

  • -storepass changeit: Password for the keystore.

  • -keypass keypassword: Password for the private key.

Setting a Key Entry's Alias

Changing the alias of an existing key entry in the keystore.

  • -changealias: Command to change the alias of a key entry.

  • -alias oldalias: Current alias of the key entry.

  • -destalias newalias: New alias for the key entry.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Changing a Key Password

Changing the password associated with a specific key in the keystore.

  • -keypasswd: Command to change the password of a key entry.

  • -alias mykey: Specifies the alias of the key entry.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

  • -keypass oldkeypassword: Current password of the key.

  • -new newkeypassword: New password for the key.

Exporting a Key Pair

Exporting a key pair involves converting the key pair from the keystore to a format that can be used by other tools, like PKCS#12

  • -importkeystore: Command to import/export a keystore.

  • -srckeystore keystore.jks: Source keystore file.

  • -destkeystore keystore.p12: Destination keystore file.

  • -deststoretype PKCS12: Destination keystore type.

  • -srcalias mykey: Alias of the key entry in the source keystore.

  • -deststorepass changeit: Password for the destination keystore.

  • -srcstorepass changeit: Password for the source keystore.

  • -srckeypass keypassword: Password for the source key.

Importing a Key Pair

Importing a key pair involves adding a key pair from an external file (like PKCS#12) into the keystore.

  • -importkeystore: Command to import/export a keystore.

  • -srckeystore keystore.p12: Source keystore file.

  • -destkeystore keystore.jks: Destination keystore file.

  • -srcstoretype PKCS12: Source keystore type.

  • -srcstorepass changeit: Password for the source keystore.

  • -deststorepass changeit: Password for the destination keystore.

  • -destkeypass keypassword: Password for the destination key.

  • -alias mykey: Alias of the key entry in the source keystore.

Deleting a Key Entry

Deleting a key entry removes the key and its associated certificate from the keystore.

  • -delete: Command to delete a key entry from the keystore.

  • -alias mykey: Alias of the key entry to delete.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Certificate

Creating a Certificate

Creating a self-signed certificate or generating a Certificate Signing Request (CSR) for obtaining a signed certificate from a Certificate Authority (CA).

  • -genkeypair: Generates a key pair and a self-signed certificate.

  • -alias mycert: Specifies the alias for the certificate entry.

  • -keyalg RSA: Specifies the algorithm for the key pair.

  • -keysize 2048: Specifies the key size in bits.

  • -keystore keystore.jks: Specifies the keystore file.

  • -dname: Distinguished Name for the certificate.

  • -storepass changeit: Password for the keystore.

  • -keypass keypassword: Password for the private key.

  • -validity 365: Validity period of the certificate in days.

Importing a Certificate

Importing a certificate into a keystore.

  • -importcert: Imports a certificate into the keystore.

  • -alias mycert: Specifies the alias for the certificate entry.

  • -file mycert.crt: Path to the certificate file to be imported.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Exporting a Certificate

Exporting a certificate from a keystore.

  • -exportcert: Exports a certificate from the keystore.

  • -alias mycert: Specifies the alias for the certificate entry.

  • -file mycert_export.crt: Path to the output file where the certificate will be saved.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Displaying Certificate Information

Displaying detailed information about a certificate stored in a keystore.

  • -list -v: Lists the contents of the keystore in verbose mode, showing detailed information.

  • -alias mycert: Specifies the alias for the certificate entry.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Checking Certificate Expiration Date

Checking the expiration date of a certificate stored in a keystore.

  • -list -v: Lists the contents of the keystore in verbose mode, showing detailed information.

  • -alias mycert: Specifies the alias for the certificate entry.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

  • | grep -i "valid from": Filters the output to show the validity period of the certificate.

Renewing an Expired Certificate

Renewing a certificate that is about to expire by generating a new Certificate Signing Request (CSR) and importing the renewed certificate.

circle-info

Steps:

  1. Generate a new CSR using the existing key pair.

  2. Submit the CSR to a Certificate Authority (CA) to get a renewed certificate.

  3. Import the renewed certificate into the keystore.

CSR Generation

  • -certreq: Generates a Certificate Signing Request (CSR).

  • -alias mycert: Specifies the alias for the certificate entry.

  • -file mycert.csr: Path to the CSR file.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Importing Renewed Certificate

  • -importcert: Imports a certificate into the keystore.

  • -file renewed_mycert.crt: Path to the renewed certificate file.

Certificate Signing Request (CSR)

Generating a CSR

Generating a Certificate Signing Request (CSR) involves creating a request for a digital certificate from a Certificate Authority (CA). This request includes your public key and information about your organization.

  • -certreq: Command to generate a CSR.

  • -alias mykey: Alias of the key pair for which the CSR is generated.

  • -file mycert.csr: Path to the output CSR file.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Submitting a CSR to a CA

Submitting a CSR to a Certificate Authority (CA) involves sending the CSR file to the CA for signing. The CA will verify the information and return a signed certificate.

circle-info

Steps:

  1. Generate a CSR (see above).

  2. Submit the CSR to the CA: This step is typically done through the CA's web interface or via email.

  3. Receive the signed certificate from the CA.

Note that each CA has a different process for submitting a CSR. Follow the specific instructions provided by the CA.

Importing a Signed Certificate from a CSR

Importing a signed certificate into a keystore involves adding the signed certificate returned by the CA into the keystore. You may also need to import the CA's root and intermediate certificates.

  • -importcert: Command to import a certificate into the keystore.

  • -alias caroot: Alias for the CA root certificate.

  • -file caroot.crt: Path to the CA root certificate file.

  • -alias mykey: Alias for the signed certificate.

  • -file mycert_signed.crt: Path to the signed certificate file.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Certificate Chain

Importing a Certificate Chain

A certificate chain (or certificate path) includes the end-entity certificate, any intermediate certificates, and the root certificate. Importing a certificate chain involves adding all these certificates to the keystore in the correct order.

  • -importcert: Command to import certificates into the keystore.

  • -trustcacerts: Trust the CA certificates in the chain.

  • -alias mykey: Alias for the certificate chain.

  • -file mycert_chain.pem: Path to the file containing the certificate chain.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Note: The mycert_chain.pem file should contain the end-entity certificate followed by intermediate certificates and finally the root certificate.

Verifying a Certificate Chain

Verifying a certificate chain ensures that the certificate chain is valid and trusted. This involves checking the signatures of each certificate in the chain up to the root certificate.

  • -list -v: Lists the contents of the keystore in verbose mode, showing detailed information.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Importing and Exporting Certificates with CA Certs

Importing and exporting certificates with CA certificates involve transferring certificates and their associated CA certificates between keystores or between keystores and files.

Importing a CA Certificate

  • -importcert: Command to import a certificate into the keystore.

  • -alias caroot: Alias for the CA certificate.

  • -file caroot.crt: Path to the CA certificate file.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Exporting a Certificate

  • -exportcert: Exports a certificate from the keystore.

  • -alias mykey: Alias for the certificate entry.

  • -file mycert_export.crt: Path to the output file where the certificate will be saved.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Keystore

Creating a Keystore

Creating a new keystore involves generating a keystore file and optionally adding an initial key pair or certificate.

  • -genkeypair: Generates a key pair and creates a keystore if it doesn't exist.

  • -alias mykey: Specifies the alias for the key pair.

  • -keyalg RSA: Specifies the algorithm for the key pair.

  • -keysize 2048: Specifies the key size in bits.

  • -keystore keystore.jks: Specifies the keystore file.

  • -dname: Distinguished Name for the certificate.

  • -storepass changeit: Password for the keystore.

  • -keypass keypassword: Password for the private key.

  • -validity 365: Validity period of the certificate in days.

Importing a Certificate into a Keystore

Importing a certificate into an existing keystore.

  • -importcert: Imports a certificate into the keystore.

  • -alias mycert: Specifies the alias for the certificate entry.

  • -file mycert.crt: Path to the certificate file to be imported.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Changing a Keystore Password

Changing the password used to protect the keystore.

  • -storepasswd: Changes the keystore password.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Current password for the keystore.

  • -new newpassword: New password for the keystore.

Viewing Keystore Details

Viewing details of the keystore and its contents.

  • -list -v: Lists the contents of the keystore in verbose mode, showing detailed information.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Backing Up a Keystore

Backing up a keystore by copying the keystore file to a safe location. Use standard file copy commands (e.g., cp for Unix/Linux, copy for Windows) to create a backup of the keystore file.

Listing Entries in a Keystore

Listing the aliases of all entries in the keystore.

  • -list: Lists the contents of the keystore.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Deleting an Entry from a Keystore

Deleting a specific entry (identified by its alias) from the keystore.

  • -delete: Deletes an entry from the keystore.

  • -alias mycert: Specifies the alias of the entry to be deleted.

  • -keystore keystore.jks: Specifies the keystore file.

  • -storepass changeit: Password for the keystore.

Importing a Keystore

Importing an existing keystore involves copying or merging its contents into another keystore.

There is no direct command to import one keystore into another; instead, export entries from the source keystore and import them into the target keystore.

Exporting a Keystore

Exporting a keystore involves creating a copy of the keystore file.

Use standard file copy commands (e.g., cp for Unix/Linux, copy for Windows) to create a copy of the keystore file.

Truststore

Creating a TrustStore

Creating a new truststore involves generating a truststore file and optionally adding trusted certificates. An empty truststore is a keystore with no certificates or key entries. This can be useful as a starting point to which you can later add trusted certificates.

Non-Empty Truststore

  • -genkeypair: Generates a key pair.

  • -alias temp: Temporary alias for the key pair.

  • -keyalg RSA: Algorithm for the key pair.

  • -keystore truststore.jks: Specifies the truststore file.

  • -dname: Distinguished name for the certificate.

  • -storepass changeit: Password for the truststore.

  • -keypass tempkeypass: Password for the private key.

  • -validity 1: Validity period of the certificate in days (set to a very short period since it's temporary).

circle-info

Although the above command generates a key pair, a truststore typically contains trusted certificates. You can import trusted certificates into this truststore as shown in the next section.

Empty Truststore

circle-info

The above steps are necessary because Java Keytool does not provide a direct command to create an empty keystore. The temporary entry is used to create the keystore file, which is then deleted to make the keystore empty.

Adding a trusted Certificate

Adding a trusted certificate to a truststore involves importing the certificate into the truststore.

  • -importcert: Imports a certificate into the keystore (or truststore).

  • -alias caroot: Specifies the alias for the trusted certificate.

  • -file caroot.crt: Path to the certificate file to be imported.

  • -keystore truststore.jks: Specifies the truststore file.

  • -storepass changeit: Password for the truststore

Removing an Untrusted Certificate

Removing a certificate from the truststore involves deleting the entry identified by its alias.

  • -delete: Deletes an entry from the keystore (or truststore).

  • -alias caroot: Specifies the alias of the entry to be deleted.

  • -keystore truststore.jks: Specifies the truststore file.

  • -storepass changeit: Password for the truststore.

Listing Entries in a Truststore

Listing the aliases of all entries in the truststore.

  • -list: Lists the contents of the keystore (or truststore).

  • -keystore truststore.jks: Specifies the truststore file.

  • -storepass changeit: Password for the truststore.

Verifying TrustStore Contents

Verifying the contents of the truststore involves listing detailed information about each entry to ensure the certificates are correct and trusted.

  • -list -v: Lists the contents of the keystore (or truststore) in verbose mode, showing detailed information.

  • -keystore truststore.jks: Specifies the truststore file.

  • -storepass changeit: Password for the truststore.

Updating a TrustStore

Updating a truststore involves adding, removing, or replacing trusted certificates. Use the -importcert and -delete commands as described below to add, remove, or replace certificates in the truststore.

Backing Up a TrustStore

Backing up a truststore involves copying the truststore file to a safe location.

circle-info

Use standard file copy commands (e.g., cp for Unix/Linux, copy for Windows) to create a backup of the truststore file.

Last updated