Introduction - Keytool Keys and Keystores reference

Background

The main uses of cryptographic keys are SSL Secure Sockets Layer (SSL)/Transport Layer Security (TLS) for communication with clients and servers. The Keytool commands allow you to generate a new Java Keytool keystore file, create a keys, X.509 Certificates, Certificate Authorities (CA), Certificate Signing Requests (CSR), X.509 chains and import certificates. Any root or intermediate certificates will need to be imported before importing the primary certificate for your domain. The following examples will help guide you through the steps required to set up a server.

Keys for SSL/TLS

To use SSL/TLS (Secure Connection) you need to provide a set of public/private keys. You cannot use secret keys for SSL/TLS. A secure connection has two sides - the SSL/TLS server side and the SSL/TLS client side. Each side has two keystores - a SSL/TLS keystore and an SSL/TLS truststore. Note the word "keystore" is used both to mean a store of keys and an SSL/TLS keystore. This means, the SSL/TLS keystore and SSL/TLS truststore are both keystores. In fact, the SSL/TLS keystore and the SSL/TLS truststore are only logical roles and it is perfectly legal to use the same physical keystore file for both.
The SSL keystore contains a private key that is used to prove the authenticity of this SSL/TLS side to the other side of an SSL/TLS connection. The SSL/TLS truststore contains public key certificates of trusted parties.

To setup keys for your server, you can:
Option 1 - Generate a private key and a corresponding self-signed public key certificate and put it in your keystore. (Self Signed)
Option 2 - Obtain a certificate from a Certificate Authority and replace your self-signed certificate with it. (Internal/External Certificate Authority)
Option 3 - Export the public key certificate of your secret key and distribute it to the parties that will interact with you. (Client Authentication required - Employees are issued personal certificates)

For encryption you have two alternatives:

  • use a public/private key pair
  • use a secret key

For public key encryption the most popular algorithm is RSA. RSA is used for compatibility with legacy systems but is much slower than Elliptical Curves. Generally encryption with secret keys is much faster and much more secure than encryption with public keys. We will cover RSA, Elliptical Curves (EC) (Public/Private Keys) and AES (Private key) types of encryption and for signing requests/certificates.

Public/private keys and certificates

SSL and asymmetric encryption algorithms such as RSA (which is the default encryption algorithm of the Server) use public/private keys. Public and private keys have a one-to-one correspondence - matching public and private keys are called a "key pair". Normally inside a keystore a public key comes wrapped in an X.509 certificate. Most keystore operations actually involve the whole public key certificate and not only the public key.

Secret keys

Secret keys are used by symmetric encryption algorithms such as AES. Note that some keystore formats such as JKS and PKCS#12 do not support secret keys. You cannot use secret keys for SSL/TLS (the SSL protocol actually generates secret keys on the fly, but normally you don't have control over them).

Keystore's

A keystore, as the name implies, provides storage for keys. It can be a file or a hardware device. The most popular keystore file formats used by Java programs are JKS, JCEKS and PKCS#12. The legacy JKS keystore with its “SHA-1 and XOR” encryption method was replaced by JCEKS, which uses Triple-DES (3DES) encryption to protect serialized keys when they are written to disk. We also have an option of the Java default PKCS12.

See the following table for comparison:

Keytool Keystores'
Keystore file format Origin Store public/private keys & certificates Store secret keys Notes
JKS Proprietary Yes No Do not use
JCEKS Proprietary Yes Yes Can be used
PKCS#12 Standard Yes No Can be used

Note: Only one of the above keystore formats can store secret keys, that is JCEKS. Also, in general JCEKS offers greater protection than JKS.
JKS, JCEKS and PKCS#12 keystores are protected by a password. Furthermore, each private or secret key inside a keystore can be protected by an individual password. Public key certificates do not have passwords, because normally there is no need to keep them secret.

For options on algorithms, keys, signatures and so on, please see the Oracle Cryptology Reference. For Keytool commands, please see the Java Platform, Standard Edition Tools Reference For the in depth explanation of the Java Cryptography Architecture, please see the Oracle Providers Documentation for JDK 8

***Warning: Different store and key passwords not supported for PKCS12 KeyStore
***Warning: Do not name the keystore.JKS/JCEKS/PKCS12 - it will not default to the storetype (i.e. name.jks or name.jceks or name.pkcs12 - instead please use jceks.keystore or pkcs12.keystore to denote the type being used