Java provides a utility keytool (stored in java_home/bin directory) used to administer keystores containing cryptographic keys, X.509 certificate chains, and trusted certificates. Programmers use this tool to administer their own private/public key pairs and associated digital certificates for use of self-authentication or data integrity. It also allows users to manage secret keys used in symmetric encryption/decryption (e.g. DES). For a list of options, use the following command:
keytool -h
Before using this tool, let us quickly understand the different related concepts such as key store, trust store, etc
1. Key Store
A keystore, as the name implies, is a repository of keys and certificates and can be a file or a h/w device. There are different standards for keystore file formats. PKCS #12 is a portable industry standard for storage and/or transport of private keys, certificates, miscellaneous secrets, and other items. It is one of the PKCS (Public-Key Cryptography Standards) family of standards published by RSA Laboratories. Files conforming to PKCS #12 usually have extensions .pi2 or .pfx.
In addition to supporting PKCS #12 standard, Java has its own proprietary standards (hence not portable) JKS (Java Key Store) provided by “SUN” and its extension JCEKS (Java Cryptography Extension Key Store) provided by “SunJCE” that support almost the same functionalities of PKCS #12. The JCEKS keystore gives much stronger protection (see Table 19.2:) for stored private keys by using Triple DES encryption. Moreover, only JCEKS keystores can store secret keys. JKS and JCEKS files usually have extensions .jks and .jceks respectively.
A keystore is protected by a store password, which is specified at the time of its creation. This password is required for any access to the keystore further. Furthermore, each secret or private key inside a keystore can be protected by an individual password. Since, there is no need to keep public key certificates secret, they do not have passwords.
Java introduced the keytool application for manipulating such keystores. It can also be used to generate self-signed certificates for test purposes. Before using keytool utility, let us understand the format of a keystore.
2. Keystore Entries
In a JKS type keystore, each entry may be either of the following two types:
Key Entries
This type of entry may contain either a secret key (called secret key entry) or a private key together with a certificate chain for the corresponding public key (called private key entry). Note that each of these key entries contains very sensitive cryptographic key information, which is optionally stored in a protected format to prevent unauthorized access.
Trusted Certificate Entries
Each of these types of entries contains a single trusted public key certificate of some party. The certificate is said to be trusted since the owner of the keystore trusts party having this certificate whose issuer vouches this by signing the certificate. These types of entries are used to authenticate other parties.
2.1. Truststore
A keystore having only trusted certificate entries is also called truststore. So, a truststore is a specific kind of keystore having only certificate entries.
3. Keystore Aliases
All keys and trusted certificates stored in the keystore are accessed through aliases. An alias is a unique name associated with a certificate entry that keytool uses to uniquely identify each certificate under its control. Aliases are case-insensitive. An alias is specifically used to add, delete, modify, import or export an entry to the keystore using keytool command with different options.
The following is a list of useful commands for managing keys. When passwords for key store and key are prompted, supply a suitable password (at least six characters long). We used the password “123456” for all examples in this chapter.
The keytool assumes a default keystore file .keystore which is located in your home directory or profile directory (for example C:\Users\root for Windows 7 and $home in Unix/Linux). To use another keystore, the option -keystore is used with keytool command.
4. Public Key Generation
Generate a private/public key pair with its associated self signed certificate:
keytool -genkey -keystore test.ks -dname ”CN=Test, OU=IT, O=JU, L=Kolkata, ST=WB, C=IN”
The defaults for various option values are given below:
-alias ”mykey”
-keyalg
”DSA” (for option -genkeypair or -genkey)
”DES” (for option -genseckey)
-keysize
1024 (for option -genkeypair or -genkey)
56 (for option -genseckey and -keyalg is ”DES”)
168 (for option -genseckey and -keyalg is ”DESede”)
-validity 90 (in days)
The signature algorithm (-sigalg option) for a certificate is determined from the private key generation algorithm. For dsa and rsa key generation algorithms, the -sigalg option defaults to SHA1withDSA and MD5withRSA respectively.
To refer to a particular entry in the keystore, -alias option is used. The following adds an entry named test to the key store test.ks.
keytool -genkey -alias test -keystore test.ks -dname ”CN=Test, OU=IT, O=JU, L=Kolkata, ST=WB, C=IN”
The following adds an entry named test to the key store test.ks using RSA.
keytool -genkey -alias test -keyalg RSA -keystore test.ks -dname ”CN=Test, OU=IT, O=JU, L=Kolkata, ST=WB, C=IN”
If an application references a key store file without specifying the type, the type as specified (usually jks) by the keystore.type property in the Java security properties file <JAVA_HOME>\lib\ security\java.security is assumed. Consequently, by default, keytool uses JKS as the format of the keystore and truststore. Use -storetype option set to pkcs12 or jks to work with PKCS12 or JKS keystores and truststores respectively.
5. Changing Password
keytool -storepasswd -keystore test.jks
Asks for the old and new password for the key store test.jks.
6. Generating a Certificate Chain
The following commands creates four key pairs named ca1, ca1, ca2, and ca4:
keytool -alias cal -dname CN=ca1 -genkeypair -keystore test.jks -storepass
123456 -keypass 123456
keytool -alias ca2 -dname CN=ca2 -genkeypair -keystore test.jks -storepass
123456 -keypass 123456
keytool -alias ca3 -dname CN=ca3 -genkeypair -keystore test.jks -storepass
123456 -keypass 123456
keytool -alias ca4 -dname CN=ca4 -genkeypair -keystore test.jks -storepass
123456 -keypass 123456
The following command extracts ca1’s self signed certificate and stores in a file ca1.pem:
keytool -export -rfc -alias ca1 -keystore test.jks -storepass 123456 -file ca1.pem
The following command creates a certificate sign request for ca2’s certificate and stores in file ca2.csr in PEM format.
keytool -alias ca2 -certreq -keystore test.jks -storepass 123456 -file ca2.csr
The following command creates a certificate for ca2 signed by ca1 and stores in a file ca2.pem:
keytool -alias ca1 -gencert -infile ca2.csr -keystore test.jks -storepass 123456 -rfc -outfile ca2.pem
The following creates a chain of certificates; ca2’s certificate signed by ca1 followed by ca1’s self signed certificate:
type ca1.pem >> ca2.pem
This certificate chain is then imported to the keystore having alias ca2:
keytool -alias ca2 -importcert -file ca2.pem -keystore test.jks -storepass 123456
Similarly, the following series of commands creates a chain of three certificates:
keytool -alias ca3 -certreq -keystore test.jks -storepass 123456 -file ca3.csr
keytool -alias ca2 -gencert -infile ca3.csr -keystore test.jks -storepass
123456 -rfc -outfile ca3.pem
type ca1.pem >> ca3.pem
keytool -alias ca3 -importcert -file ca3.pem -keystore test.jks -storepass 123456
Similarly, the following series of commands creates a chain of four certificates:
keytool -alias ca4 -certreq -keystore test.jks -storepass 123456 -file ca4.csr keytool -alias ca3 -gencert -infile ca4.csr -keystore test.jks -storepass 123456 -rfc -outfile ca4.pem type ca1.pem >> ca4.pem
keytool -alias ca4 -importcert -file ca4.pem -keystore test.jks -storepass 123456
7. Generating a Certificate Using Openssl
In the area of cryptographic functionality, OpenSSL is a well-know powerful opensource library that includes a command line utility that can be used to perform a variety of cryptographic functions. This section introduces some of the powerful openSSL commands. To work with openSSl, download a suitable version from http://www.openssi.org/. We downloaded a file openssi-0.9.8h-i-bin. zip and unzipped in a directory E:\ajp\sec\openssi. Include the directory E:\Net\ss\openssi\ bin in your PATH environment variable. Additionally, on windows, the environment variables used by openssl have to be set as follows:
set RANDFILE=E:\ajp\sec\openssl\rnd
set OPENSSL_CONF=E:\ajp\sec\openssl\share\openssl.cnf
Now, OpenSSL is ready to use. The following are some useful commands to work with cryptography.
Creating Self-signed Certificate
openssl genrsa -des3 -out CA.key 1024
openssl req -new -key CA.key -out CA.csr
openssl x509 -req -days 365 -in CA.csr -signkey CA.key -out CA.crt
Creating Certificate Signed by the Server
openssl genrsa -des3 -out client.key 1024
openssl req -new -key client.key -out client.csr
openssl x509 -req -CA CA.crt -CAkey CA.key -in client.csr -out client.crt -days
365 -Cacreateserial
Creating Java Key Store (JKS) from a Private Key and Certificate
With a private key and public certificate, creating a JKS key store can be done in two steps: create a PKCS12 key store using openssl first, then convert it into a JKS using keytool.
openssl pkcs12 -export -name mykey -in client.crt -inkey client.key -out
keystore.p12
keytool -importkeystore -destkeystore client.ks -srckeystore keystore.p12 – srcstoretype pkcs12 -alias mykey
Converting Der Key File to Pem Key File
openssl rsa -inform der -in p.der -out p.pem
Creating a JKS Key store from a Chain of Certificates
Use the following command to create a PEM certificate file containing a chain of certificates.
copy client.crt com.crt
type CA.crt >> com.crt
In this case, the PEM certificate file com.crt contains two certificates, client.crt and CA.crt. Now, create a PKCS12 key store from this combined certificate.
openssl pkcs12 -export -name mykey -in com.crt -inkey client.key -out com.p12
This PKCS12 file com.p12 contains an entry named “mykey” containing client’s private key and a chain of two certificates. Now, import (convert) this PKCS12 file in a JKS file com.ks.
keytool -importkeystore -destkeystore com.ks -srckeystore com.p12 -srcstoretype pkcs12 -alias mykey
Secret Key Generation
Generate a secrete (sysmmetric) key using DES:
keytool -genseckey -keyalg DES -storetype jceks -keystore sec.ks
Note that only JCEKS keystores can store secret keys. So, -storetype is mentioned as jceks. Generate a 128-bit secret (sysmmetric) key using AES:
keytool -genseckey -keyalg AES -keysize 128 -storetype jceks -keystore sec.ks
Currently supported secret key generation algorithms are DES, AES, ARCFOUR, Blowfish, DESede, HmacSHAl, HmacSHA256, HmacSHA384, HmacSHA512 and RC2.
Viewing Key Store Entries
To view the contents of a keystore, – list option is used. View the content of the entry mykey of the key store test.jks.
keytool -list -alias mykey -keystore test.jks
If no alias is specified, it displays all entries of key store test.jks:
keytool -list -keystore test.jks
The -list option does not, by default, display certificate information. Use -v to see the certificate information:
keytool -v -list -keystore test.jks
To see certificate in PEM format, use -rfc option:
keytool -rfc -list -keystore test.jks
Deleting Key Store Entries
Delete an entry identified by alias mykey from the key store test.jks.
keytool -delete -alias mykey -keystore test.jks
Exporting Certificate
Export the certificate corresponding to alias mykey in the keystore test.jks in a file test.cer.
keytool -export -alias mykey -keystore test.jks -file test.cer
This command exports the certificate at the bottom of the certificate chain in that keystore entry identified by alias mykey. If, instead, mykey is the alias for a trusted certificate entry, then that trusted certificate is exported. The specified alias must correspond to a private/public key entry. Note that for secret key entry, no certificate is stored, hence exporting certificate will not work. To export the certificate in PEM format, use -rfc option:
keytool -export -alias mykey -keystore test.jks -jfc -file test.pem
Viewing Certificate
View the content of a certificate file test.cer.
keytool -printcert -file test.cer
The keytool utility understands both DER as well as PEM certificate encodings.
Converting Keystore Format
Convert from JKS to PKCS12 format:
keytool -importkeystore -srckeystore test.j ks -srestoretype jks -destkeystore
test.pfx -deststoretype pkcs12
Convert from JKS to JCEKS format:
keytool -importkeystore -srckeystore test.jks -srestoretype jks -destkeystore test.jceks -deststoretype jceks
Convert from PKCS12 to JKS format:
keytool -importkeystore -srckeystore test.pfx -srcstoretype pkcs12 -destkeystore test.jks -deststoretype jks
Convert from PKCS12 to JCEKS format:
keytool -importkeystore -srckeystore test.pfx -srcstoretype pkcs12 -destkeystore test.jceks -deststoretype jceks
Convert from PKCS12 to PEM format:
openssl pkcs12 -in test.pfx -out test.pem
Generating Certificate Signing Request
Certificates generated by keytool can be exported in a form suitable for submission to a Certificate Authority such as VeriSign. The following is an example:
keytool -keystore test.ks -certreq -alias mykey -keyalg dsa -file out.csr
This stores the signing request data in a file out.csr.
Source: Uttam Kumar Roy (2015), Advanced Java programming, Oxford University Press.