Open in app

Sign in

Write

Sign in

Introduction to the Java keytool command

Gregory Cernera
6 min readOct 12, 2022

--

Topics Covered…

What is the keytool command?
What is a key?
What is a keystore?
Generating a secret key
Listing a keystore
Generating a keypair
Exporting a certificate
Printing a certificate
Importing a certificate
Deleting a key

What is the keytool command?

keytool is a Java utility command that allows users to create, manage, and delete keys and certificates in keystores. This article will explain the basics of the keytool utility and provide some basic examples to follow.

What is a key?

A cryptographic key is a stream of bytes that can be used to encode, decode, and sign data. A key can be generated from a number of different symmetric and asymmetric cryptographic algorithms. Symmetric key cryptography refers to the process of using the same key for encryption and decryption and includes algorithms such as AES, DES, TripleDES, and Blowfish. Asymmetric cryptography refers to the process of using separate keys for encrypting and decrypting — a public key and a private key. Examples of asymmetric crypto algorithms include RSA, DSA, and Elliptic-Curve.

What is a keystore?

A keystore is a file that holds or “stores” keys and certificates. There are different types of keystores with separate capabilities. For example, a Java keystore (JKS) is the standard keystore format originally used by Java; a JCE keystore (JCEKS) uses the Java Cryptography Extension (JCE) to provide an improved keystore format with stronger protection than the JKS; and a PKCS12 keystore stores key entries and is the industry standard format.

Generating a secret key

In order to generate a secret key, we need to use the -genseckey option. Here’s an example…

keytool -genseckey -alias key.AES -keyalg AES -keypass pass123 -keystore keystore.pkcs12 -storetype PKCS12 -keysize 128 -storepass pass123

You may notice some extra options included in the command as well. Here are the descriptions for each:

  • -alias An alias specifies the name of our key or certificate
  • -keyalg The algorithm we want to use to generate our key
  • -keypass The key password
  • -keystore The name of the keystore that we want to manage/update. If the keystore does not exist, it will be created.
  • -storetype The type of keystore that we want to be created
  • -keysize The number of bits we want for the key size. This number depends on the type of algorithm used to create the key.
  • -storepass The keystore password

Using the provided example as a reference, we can see that the command generates a secret AES, 128-bit key that’s protected by the password “pass123” and wants to store that key in a new PKCS12 keystore named “keystore.pkcs12” that is protected by the password “pass123”

Listing a keystore

Now that we have something in our keystore, we may want to view the contents of that keystore to see what kinds of keys or certificates it holds. We can do this with the -list command.

keytool -list -keystore keystore.pkcs12 -storepass pass123

This command will list the contents of the keystore we just created like so…

Keystore type: pkcs12
Keystore provider: SUNYour keystore contains 1 entrykey.aes, Oct 11, 2022, SecretKeyEntry,

The output shows us what type of keystore this file is, the security provider that created that keystore, and a list of key entries contained in the keystore. Our keystore only contains the one “key.aes” key we created in the previous step.

If we want just the information on a specific key, we can use the -alias option to specify which key to look at…

keytool -list -keystore keystore.pkcs12 -storepass pass123 -alias key.aes

So now it will only display the information related to that key.

key.aes, Oct 11, 2022, SecretKeyEntry,

Generating a keypair

If we want to create a public/private key pair, we can use the -genkeypair or -genkey command…

keytool -genkeypair -alias keypair.RSA -keyalg RSA -keystore keystore.pkcs12 -storepass pass123 -storetype PKCS12

We will then be prompted with a series of questions that will be used to affiliate with this key pair certificate…

What is your first and last name?
  [Unknown]:  Name
What is the name of your organizational unit?
  [Unknown]:  Unit
What is the name of your organization?
  [Unknown]:  Org
What is the name of your City or Locality?
  [Unknown]:  City
What is the name of your State or Province?
  [Unknown]:  State
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=Name, OU=Unit, O=Org, L=City, ST=State, C=US correct? (type "yes" or "no")
  [no]:  yes

This command creates a private key and a public key, and then wraps the public key with a self-signed certificate and stores it in a certificate chain. Our keystore.pkcs12 file now contains a newly created private key along with its associated certificate chain.

We can list the contents of the keystore again to make sure that the key pair is added, and we can use the flag -v for a more verbose output…

keytool -list -keystore keystore.pkcs12 -storepass pass123 -alias keypair.RSA

And shows us the output…

Alias name: keypair.rsa
Creation date: Oct 11, 2022
Entry type: keyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Name, OU=Unit, O=Org, L=City, ST=State, C=US
Issuer: CN=Name, OU=Unit, O=Org, L=City, ST=State, C=US
Serial number: 1e09b20c
Valid from: 10/11/22 11:03 PM until: 1/9/23 10:03 PM
Certificate fingerprints:
         MD5:  D3:77:1B:1B:D8:96:73:32:9C:7F:01:B0:B1:56:BC:E3
         SHA1: A4:28:19:4A:B7:35:6B:FD:61:A3:04:C6:EA:A4:21:19:F2:48:E8:0B
         SHA256: CE:55:6F:AC:3E:6D:56:14:A9:C8:3F:8D:19:B6:38:C4:91:DF:50:DE:5F:87:81:77:11:7E:70:04:D9:8D:D6:9B
         Signature algorithm name: SHA256withRSA
         Version: 3Extensions:#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 3f eb 18 6a 60 3d d3 21  54 6e 06 26 01 dd 46 e2  ...j....Tn....F.
0010: 50 b6 17 1a                                        P...
]
]

Exporting a certificate

If we want to export that certificate chain we just created, we can use the -exportcert command.

keytool -exportcert -alias keypair.rsa -file my.cert -storepass pass123 -keystore keystore.pkcs12

The -file option specifies the name of the new file to which we want to export this certificate.

After running this command, we will get the following output upon a successful execution…

Certificate stored in file <my.cert>

Printing a certificate

We can also view the contents of our newly created certificate file with the -printcert command…

keytool -printcert -file my.cert

Which will give us the information of the certificate…

Owner: CN=Name, OU=Unit, O=Org, L=City, ST=State, C=US
Issuer: CN=Name, OU=Unit, O=Org, L=City, ST=State, C=US
Serial number: 1e09b20c
Valid from: 10/11/22 11:03 PM until: 1/9/23 10:03 PM
Certificate fingerprints:
         MD5:  D3:77:1B:1B:D8:96:73:32:9C:7F:01:B0:B1:56:BC:E3
         SHA1: A4:28:19:4A:B7:35:6B:FD:61:A3:04:C6:EA:A4:21:19:F2:48:E8:0B
         SHA256: CE:55:6F:AC:3E:6D:56:14:A9:C8:3F:8D:19:B6:38:C4:91:DF:50:DE:5F:87:81:77:11:7E:70:04:D9:8D:D6:9B
         Signature algorithm name: SHA256withRSA
         Version: 3Extensions:#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 3f eb 18 6a 60 3d d3 21  54 6e 06 26 01 dd 46 e2  ...j....Tn....F.
0010: 50 b6 17 1a                                        P...
]
]

Importing a certificate

We can also import our new my.cert file into another keystore using the -importcert command…

keytool -importcert -file my.cert -alias cert1 -keystore keystore2.jks -storepass pass123 -storetype JKS

This command will import the certificate from my.cert into a new Java keystore file named keystore2.jks and store the certificate with the alias cert1.

The output will display the certificate and ask if this certificate can be trusted. At which point you will specify “yes” or “no”.

Owner: CN=Name, OU=Unit, O=Org, L=City, ST=State, C=US
Issuer: CN=Name, OU=Unit, O=Org, L=City, ST=State, C=US
Serial number: 1e09b20c
Valid from: 10/11/22 11:03 PM until: 1/9/23 10:03 PM
Certificate fingerprints:
         MD5:  D3:77:1B:1B:D8:96:73:32:9C:7F:01:B0:B1:56:BC:E3
         SHA1: A4:28:19:4A:B7:35:6B:FD:61:A3:04:C6:EA:A4:21:19:F2:48:E8:0B
         SHA256: CE:55:6F:AC:3E:6D:56:14:A9:C8:3F:8D:19:B6:38:C4:91:DF:50:DE:5F:87:81:77:11:7E:70:04:D9:8D:D6:9B
         Signature algorithm name: SHA256withRSA
         Version: 3Extensions:#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 3f eb 18 6a 60 3d d3 21  54 6e 06 26 01 dd 46 e2  ...j....Tn....F.
0010: 50 b6 17 1a                                        P...
]
]Trust this certificate? [no]:  yes

If the certificate can be trusted, then it will be added to your new keystore has specified.

Deleting a key

Finally, we can also delete entries in our keystores if we have the correct passwords. This can be done with the -delete command…

keytool -delete -alias key.aes -keystore keystore.pkcs12 -storepass pass123 -keypass pass123

The key.aes entry will now be removed from our keystore.

Conclusion

This article just scratches the surface into the capabilities of the keytool command. For more information, you can read Oracle’s official documentation on the keytool command.

Thanks for reading! ☕

Java
Keytool
Java Security

--

--

Gregory Cernera

Written by Gregory Cernera

53 Followers

Advisory Software Engineer at IBM — more about me at https://cernera.me/

Help

Status

About

Careers

Press

Blog

Privacy

Terms

Text to speech

Teams