Java Keytool

Java Keytool is a PKI toolkit for Java environments, used which manage Sun JKS keystores - a small mini-database consisting of a single file used to store PKI properties such as certificates and private files. This toolkit is important because it used to create files used by JSSE (Java Secure Socket Extension), the javax.net.ssl classes used for SSL/TLS authentication.

The complete manual is available at http://download.oracle.com/javase/7/docs/technotes/tools/windows/keytool.html.

Contents

Java keytool: Create a SSL/TLS javax.net.ssl.keyStore

This examples creates a SSL/TLS javax.net.ssl.keyStore containing the client identity (Private Key, Certificate and Certificate Chain / Path) for a client used in SSL/TLS Mutual Authentication.

Note: This step is only intended for SSL/TLS Client Authentication (aka Mutual Authentication, aka Two-Way Authentication). If you are only interested in Server Authentication, this is not what you want to do.

Parameters used in example:

ParameterMeaning / ContextValue used in example
keystoreFilename of SSL/TLS javax.net.ssl.keyStore file keystore
dnameDistinguished name identifying the certificate, set according to CA requirements."CN=Test, OU=Test, O=Test, L=Test, S=Test, C=Test"
aliasAlias used to store private key and client certificate in keystorekeyAlias
aliasAlias used to store certificate chain / path in keystore ca0, ca1, ca2, ...
keypassPassword used to protect keypassword
storepassPassword used to protect keystore (use same as keypass!) password
fileCertificate Signing Request (CSR) file to be sent to CA. keyAlias.csr
file Client certificate filekeyAlias.cer
fileClient certificate chain / path certificate files ca-root.cer, ca-int-1.cer, ca-int-2.cer, ...
  1. Create a KeyStore, generate a private key, and store private key in alias keyAlias (or any other easily remembered alias name).
    Use the same key password and store password, and select a descriptive dname.
    keytool -genkey -dname "CN=Test, OU=Test, O=Test, L=Test, S=Test, C=Test" -alias keyAlias
        -keypass password -storepass password -keystore KeyStore
  2. Create a Certificate Signing Request (CSR) for keyAlias, and save into file keyAlias.csr.
    keytool -certreq -alias keyAlias -file keyAlias.csr -keypass password -storepass password -keystore KeyStore
  3. Obtain a Certificate using CSR from a Certificate Authority, usually a commercial vendor. Refer to Working with Certificate Authorities. Do not forget to state that you are requesting a Client certificate (or perhaps a Client and Server certificate).
  4. Install Certificate Chain; chain of certificate used sign certificate. Select a unique alias for each certificate you import, e.g. ca0, ca1 and so on. Extracting certificate chain certificates from Client certificate using Microsoft Windows describes how to create necessary .cer files. It should also be possible to import to a complete certificate chain directly if contained in a PKCS#7 .p7b file.
    1. Install Root CA Certificate
      keytool -import -alias ca0 -file ca-root.cer -trustcacerts -storepass password -keystore KeyStore
    2. Install Intermediate CA Certificates (if any).
      3. keytool -import -alias ca1 -file ca-int-1.cer -trustcacerts -storepass password -keystore KeyStore
      keytool -import -alias ca2 -file ca-int-2.cer -trustcacerts -storepass password -keystore KeyStore
      ...
    3. Install Client Certificate into keyAlias.
      keytool -import -alias keyAlias -file keyAlias.cer -storepass password -keystore KeyStore

 

Java keytool: Convert a javax.net.ssl.keyStore into PKCS12 file

Java Keytool JKS keystore is a proprietary format with little or no support outside of the Java world. For verification / test / backup purposes, it is very useful to be able to convert client identity contained in a javax.net.ssl.keyStore into the more popular Personal Information Exchange (PKCS12) file format.

Note: This is an optional thing to do. You do not have to create PKCS12 files unless you have specific reason to do so.

  1. Prerequisite: Obtain a third party tool which can export private key from keystore, for example ExportPriv.java provided by mark.foster.cc.
  2. Export private key from keytool (example using ExportPriv.java):
    1. Compile ExportPriv.java
      %JAVA_HOME%\bin\javac ExportPriv.java
    2. Export private key from alias keyAlias into PKCS8 file exported-pkcs8.key.
      java ExportPriv KeyStore keyAlias password > exported-pkcs8.key
  3. Export certificate for keyAlias into file exported.crt.
    keytool -export -rfc -alias keyAlias -file exported.crt -keystore KeyStore
  4. Combine certificate (exported.crt) and private key (exported-pkcs8.key) into PKCS12 file exported.pfx using OpenSSL.
    openssl pkcs12 -export -out exported.pfx -inkey exported-pkcs8.key -in exported.crt
  5. Remove exported-pkcs8.key.