Manage keys, certificates and keystores

Background

The main uses of cryptographic keys in the product are SSL (see section Secure Sockets Layer (SSL) Support) and encryption (see section Tivoli Directory Integrator Server Instance Security).

For detailed information on security concepts and how they are used in the IBM® JVM, see http://www.ibm.com/developerworks/java/jdk/security/.

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.

Again in most cases inside a keystore a private key is accompanied by the corresponding public key certificate.

Secret keys

Secret keys are used by symmetric encryption algorithms such as DES, AES and RC4. Note that some keystore formats such as JKS and PKCS#12 do not support secret keys.

You cannot use secret keys for SSL (the SSL protocol actually generates secret keys on the fly, but normally you don't have control over them).

Keystores

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. See the following table for comparison:

Note that the only one of the above keystore formats that can store secret keys 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.

Keys for SSL

For detailed information on using SSL with the IBM JVM see: http://www.ibm.com/developerworks/java/jdk/security/60/secguides/jsse2Docs/JSSE2RefGuide.html.

To use SSL you need to provide a set of public/private keys. You cannot use secret keys for SSL.

An SSL connection has two sides - the SSL server side and the SSL client side. Each side has two keystores - an SSL keystore and an SSL truststore. Note that the word "keystore" is used both to mean a store of keys and an SSL keystore. So SSL keystore and SSL truststore are both keystores. In fact, the SSL keystore and the SSL 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 side to the other side of an SSL connection. The SSL truststore contains public key certificates of trusted parties.

1. To setup keys for your SSL server, you can: Generate a private key and a corresponding self-signed public key certificate and put it in your SSL keystore. (see section "Generate a public/private key pair and a self-signed certificate"). This step is needed only if your side of the SSL connection has to prove its authenticity to its peers - that is if you are the SSL server or if you are the SSL client and client authentication is required.
2. [Optionally] Obtain a certificate from a Certificate Authority and replace your self-signed certificate with it. (see section "Import public key certificate in a keystore")
3. [Optionally] Export the public key certificate of your private key and distribute it to the SSL parties that will interact with you. (see section "Export public key certificate from a keystore") If you are using a certificate from a Certificate Authority then it will be enough for others to have only the certificate of the Certificate Authority itself.
4. Import certificates of trusted parties in your SSL truststore (see section "Import public key certificate in a keystore"). This step is mandatory for SSL clients. For SSL servers it is necessary only if client authentication is required.

Keys for encryption

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. Note that other popular public key algorithms such as DiffieHellman (key exchange) and DSA (digital signature) cannot be used for encryption.

Generally encryption with secret keys is much faster and much more secure than encryption with public keys. However, by default the Directory Integrator Server uses public key encryption with RSA to preserve compatibility with earlier versions.

Tools

The IBM JVM provides two utilities for working with keys and certificates - keytool and Ikeyman. keytool is a command-line utility that is popular in the Java community. Ikeyman is a GUI tool from IBM, which provides many of the features of 'keytool'. Both tools are located in the TDI_install_dir/jvm/jre/bin folder. For detailed information about these tools see the documentation of the IBM JVM: http://www.ibm.com/developerworks/java/jdk/security/

Default keystores shipped with the product:

List the contents of a keystore

Use the list command of keytool. For example the following command lists information about the keys (alias and type) inside the keystore file mystore.jck; the format of the keystore is JCEKS and its password is "mystorepass":

keytool -list -storetype jceks -keystore mystore.jck -storepass mystorepass 

Create keys

Generate a public/private key pair and a self-signed certificate

For example the following keytool command generates an RSA public/private key pair with alias "myserverkey" and a X.509 self-signed public key certificate:

keytool -genkeypair -alias myserverkey -dname cn=myserver.mydomain.com 
-validity 365 -keyalg RSA -keysize 1024
	-keypass mykeypass -storetype jceks -keystore mystore.jck -storepass 
mystorepass 

The distinguished name of the owner of the certificate is "cn=myserver.mydomain.com", which should be the same as the DNS name of the server that will use the self-signed certificate for SSL (for public key encryption the content of the certificate does not matter much). The certificate is valid for 365 days. The size of the generated RSA key is 1024 bytes. The password of the private key is "mykeypass". The key pair is stored in a keystore file mystore.jck with format JCEKS (if the file does not exist, it will be created). The password of the keystore is "mystorepass".

The mystore.jck keystore can be used as an SSL keystore of a server program that runs on the "myserver.mydomain.com" host. The keystore also contains a public key certificate for the private key, so it can be used as an SSL truststore for clients that connect to the server on "myserver.mydomain.com". (Although to give your private key to clients is completely unnecessary and generally a bad security practice.)

Obtain a certificate from a Certificate Authority

Normally the process of acquiring and using CA-signed certificates goes like this:

First a key pair and a self-signed certificate is generated (see section "Generate a public/private key pair and a self-signed certificate"). After that a certificate for the public key is requested from a Certification Authority. When the Certification Authority sends back the signed certificate, the certificate is imported into the appropriate truststore, replacing the self-signed certificate.

For example using keytool you can generate a Certificate Signing Request for the "myserverkey" key from the mystore.jck keystore like this:

keytool -certreq -file myreq.csr -alias myserverkey -keypass mykeypass 
-storetype jceks
	-keystore mystore.jck -storepass mystorepass

This command creates a Certificate Signing Request in the myRequest.csr file for the public key with alias "myserverkey". The created Certificate Signing Request now can be sent to a Certification Authority. When the new certificate arrives, you can import it in the keystore as described in section "Import public key certificate in a keystore". The following keytool command generates a 256 bit AES key with alias "myseckey":

keytool -genseckey -keyalg AES -alias myseckey -keysize 256 -keypass mykeypass 
-storetype jceks
	-keystore mystore.jck -storepass mystorepass 

The new key is stored in a JCEKS keystore file mystore.jck with password "mystorepass". The password that protects the secret key is "mykeypass".

Copy key from one keystore to another

For example you can copy the key pair created in section "Generate a public/private key pair and a self-signed certificate" with the following keytool command:

keytool -importkeystore  -srckeystore mystore.jck -destkeystore myotherstore.jks 
-srcstoretype jceks
	-deststoretype jks -srcstorepass mystorepass -deststorepass myotherstorepass 
-srcalias myserverkey
	-destalias myotherserverkey -srckeypass mykeypass -destkeypass myotherkeypass

The copy will be stored under alias "myotherserverkey" in the JKS keystore file myotherstore.jks (if it does not exist the file will be created).

Convert keystore from one format to another

For example you can convert the JCEKS keystore created in section "Generate a public/private key pair and a self-signed certificate" to a JKS keystore myotherstore.jks with the following keytool command:

keytool -importkeystore  -srckeystore mystore.jck -destkeystore 
myotherstore.jks -srcstoretype jcek
	-deststoretype jks -srcstorepass mystorepass -deststorepass 
myotherstorepass

The command will eventually ask for the password of each individual private or secret key inside the source keystore. Note that JKS and PKCS#12 keystores cannot hold secret keys. You should not try to convert a keystore that contains secret keys to either JKS or PKCS#12.

Export public key certificate from a keystore

The following command exports the public key certificate created in section "Generate a public/private key pair and a self-signed certificate" to a binary file myserverkey.der:

keytool -exportcert -alias myserverkey -file myserverkey.der 
-storetype JCEKS -keystore mystore.jck
	-storepass mystorepass

The resulting .der file contains the DER encoding of the X.509 certificate. It is a binary file. To get the same binary data in text form (base-64 encoded form of the DER encoding of the X.509 certificate) use the "-rfc" option of keytool:

keytool -exportcert -alias myserverkey -file myserverkey.arm 
-storetype JCEKS -keystore mystore.jck
	-storepass mystorepass -rfc

Import public key certificate in a keystore

To import a new trusted certificate in a keystore use a command like this:

keytool -importcert -alias myserverkey -file myserverkey.der 
-storetype JCEKS -keystore mystore.jck
	-storepass mystorepass

keytool will attempt to verify the signer of the certificate which you are trying to import. This means constructing a certificate chain from the imported certificate to some other trusted certificate. If a chain cannot be established, keytool will ask you whether you are certain that the certificate needs to be imported.

To import a certificate that is a response from a Certificate Authority to a Certificate Signing Request (this means you already have a private key in the keystore for that certificate) use a command like this:

keytool -importcert -alias myserverkey -keypass mykeypass -file 
myserverkey.der -storetype JCEKS -keystore mystore.jck
	-storepass mystorepass

Note that when you import a certificate for an existing private key, you have to specify the password of the private key. keytool will attempt to verify the signer of the certificate by constructing a certificate chain to a trusted certificate. If a chain cannot be established, the import will fail - you will not be asked to verify the authenticity of the certificate. To have a successful import of an answer to a Certificate Signing Request, you have to trust the Certificate Authority which issued the certificate. If your Certificate Authority is one of the popular ones (for example, VeriSign or Thawte) you could rely on the certificates in the default truststore of the JVM (java.home/lib/security/cacerts) by using the "-trustcacerts" option of keytool:

keytool -importcert -alias myserverkey -keypass mykeypass -file 
myserverkey.der -storetype JCEKS -keystore mystore.jck
	-storepass mystorepass -trustcacerts

Extend the validity of a certificate using keytool

Suppose you have a JCEKS keystore called mystore.jck that includes an expired (or about to expire) self-signed certificate whose alias name is "myserverkey". The keystore has the associated private key in it. Assume that the password for the keystore is "mystorepass" and the password for the private key is "mykeypass". Now, if you want to extend the validity of this certificate by another 365 days, you can run the following command using keytool:

keytool -selfcert -v -alias myserverkey -keypass mykeypass -validity 365 
-storetype jceks -keystore mystore.jck
	-storepass mystorepass 

The above operation will generate a new self-signed certificate, that has the same DN, SIGALG, KEYS as the original certificate but has a new SERIAL NUMBER and VALIDITY period.

Note:

The generated new certificate will automatically replace the original one.

So if you need the original one later for reference or for any reason, you must keep a copy of the original keystore before doing the certificate extension explained above.

Note that this works only for self-signed certificates. It actually generates a new self-signed certificate for the public key, so you need to export it and update the truststores of the SSL parties that you are going to communicate with.

Work with keys stored in PFX/PKCS#12 files

As far as Java is concerned PKCS#12 is just another type of keystore (like JCEKS and JKS). To work with PKCS#12 keystores just set the "-storetype" option of keytool to "pkcs12". For example the following command lists the content of a mystore.p12 PKCS#12 file with password "mystorepass":

keytool -list -storetype pkcs12 -keystore mystore.p12 -storepass mystorepass

Create a keystore file

You don't need to create keystore files before you use them - keytool will automatically create a new keystore file, when it needs to write something to a file that does not exist. For example, if you generate a new key or import a certificate in a non-existing keystore, keytool will create the keystore file first.

Run keytool in FIPS mode

To run keytool in FIPS-compliant mode use the "-providerClass" option on each command like this:

keytool -list -storetype JCEKS -keystore mystore.jck -storepass mystorepass
	-providerClass com.ibm.crypto.fips.provider.IBMJCEFIPS