Keystores and Truststores

Keystores and Truststores

A  keystore   is a database of key material. Key material is used for a variety of purposes, including authentication and data integrity. There are various types of keystores available, including "PKCS12" and Sun's "JKS."

Generally speaking, keystore information can be grouped into two different categories: key entries and trusted certificate entries. A key entry consists of an entity's identity and its private key, and can be used for a variety of cryptographic purposes. In contrast, a trusted certificate entry only contains a public key in addition to the entity's identity. Thus, a trusted certificate entry can not be used where a private key is required, such as in a  javax.net.ssl.KeyManager . In the JDK implementation of "JKS", a keystore may contain both key entries and trusted certificate entries.

A  truststore   is a keystore which is used when making decisions about what to trust. If you receive some data from an entity that you already trust, and if you can verify that the entity is the one it claims to be, then you can assume that the data really came from that entity.

An entry should only be added to a truststore if the user makes a decision to trust that entity. By either generating a keypair or by importing a certificate, the user has given trust to that entry, and thus any entry in the keystore is considered a trusted entry.

It may be useful to have two different keystore files: one containing just your key entries, and the other containing your trusted certificate entries, including Certification Authority (CA) certificates. The former contains private information, while the latter does not. Using two different files instead of a single keystore file provides for a cleaner separation of the logical distinction between your own certificates (and corresponding private keys) and others' certificates. You could provide more protection for your private keys if you store them in a keystore with restricted access, while providing the trusted certificates in a more publicly accessible keystore if needed.

 

 Creating a Simple Keystore and Truststore

   

1. Create a new keystore and self-signed certificate with corresponding public/private keys.

   % keytool -genkey -alias duke -keyalg RSA \
     -validity 7 -keystore keystore 
   
    Enter keystore password:  password
    What is your first and last name?
    [Unknown]:  Duke
    What is the name of your organizational unit?
    [Unknown]:  Java Software
    What is the name of your organization?
    [Unknown]:  Sun Microsystems, Inc.
    What is the name of your City or Locality?
    [Unknown]:  Palo Alto
    What is the name of your State or Province?
    [Unknown]:  CA
    What is the two-letter country code for this unit?
    [Unknown]:  US 
    Is CN=Duke, OU=Java Software, O="Sun Microsystems, Inc.",
    L=Palo Alto, ST=CA, C=US correct?
    [no]:  yes
   
    Enter key password for <duke>
     (RETURN if same as keystore password):  <CR>
         

   This is the keystore that the server will use.

    

2. Examine the keystore. Notice the entry type is keyEntry which means that this entry has a private key associated with it (shown in red).

   % keytool -list -v -keystore keystore
   Enter keystore password:  password
   
   Keystore type: jks
   Keystore provider: SUN
   
   Your keystore contains 1 entry
   
   Alias name: duke
   Creation date: Dec 20, 2001
   Entry type: keyEntry
   Certificate chain length: 1
   Certificate[1]:
   Owner: CN=Duke, OU=Java Software, O="Sun Microsystems, Inc.", 
   L=Palo Alto, ST=CA, C=US
   Issuer: CN=Duke, OU=Java Software, O="Sun Microsystems, Inc.", L=Palo Alto, ST=CA, C=US
   Serial number: 3c22adc1
   Valid from: Thu Dec 20 19:34:25 PST 2001 until: Thu Dec 27 19:34:25 PST 2001
   Certificate fingerprints:
       MD5: F1:5B:9B:A1:F7:16:CF:25:CF:F4:FF:35:3F:4C:9C:F0
       SHA1: B2:00:50:DD:B6:CC:35:66:21:45:0F:96:AA:AF:6A:3D:E4:03:7C:74
         

    

3. Export and examine the self-signed certificate.

   % keytool -export -alias duke -keystore keystore -rfc \
     -file duke.cer
   Enter keystore password:  password
   Certificate stored in file <duke.cer>
   % cat duke.cer
   -----BEGIN CERTIFICATE-----       
   MIICXjCCAccCBDwircEwDQYJKoZIhvcNAQEEBQAwdjELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNB  
   MRIwEAYDVQQHEwlQYWxvIEFsdG8xHzAdBgNVBAoTFlN1biBNaWNyb3N5c3RlbXMsIEluYy4xFjAU
   BgNVBAsTDUphdmEgU29mdHdhcmUxDTALBgNVBAMTBER1a2UwHhcNMDExMjIxMDMzNDI1WhcNMDEx
   MjI4MDMzNDI1WjB2MQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0ExEjAQBgNVBAcTCVBhbG8gQWx0
   bzEfMB0GA1UEChMWU3VuIE1pY3Jvc3lzdGVtcywgSW5jLjEWMBQGA1UECxMNSmF2YSBTb2Z0d2Fy
   ZTENMAsGA1UEAxMERHVrZTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA1loObJzNXsi5aSr8
   N4XzDksD6GjTHFeqG9DUFXKEOQetfYXvA8F9uWtz8WInrqskLTNzwXgmNeWkoM7mrPpK6Rf5M3G1
   NXtYzvxyi473Gh1h9k7tjJvqSVKO7E1oFkQYeUPYifxmjbSMVirWZgvo2UmA1c76oNK+NhoHJ4qj
   eCUCAwEAATANBgkqhkiG9w0BAQQFAAOBgQCRPoQYw9rWWvfLPQuPXowvFmuebsTc28qI7iFWm6BJ
   TT/qdmzti7B5MHOt9BeVEft3mMeBU0CS2guaBjDpGlf+zsK/UUi1w9C4mnwGDZzqY/NKKWtLxabZ
   5M+4MAKLZ92ePPKGpobM2CPLfM8ap4IgAzCbBKd8+CMp8yFmifze9Q==
   -----END CERTIFICATE-----
         

   Alternatively, you could generate Certificate Signing Request (CSR) with -certreq and send that to a Certificate Authority (CA) for signing, but again, that's beyond the scope of this example.

    

4. Import the certificate into a new truststore.

   % keytool -import -alias dukecert -file duke.cer \
     -keystore truststore
   Enter keystore password:  trustword
   Owner: CN=Duke, OU=Java Software, O="Sun Microsystems, Inc.", L=Palo Alto, ST=CA, C=US
   Issuer: CN=Duke, OU=Java Software, O="Sun Microsystems, Inc.", L=Palo Alto, ST=CA, C=US
   Serial number: 3c22adc1
   Valid from: Thu Dec 20 19:34:25 PST 2001 until: Thu Dec 27 19:34:25 PST 2001
   Certificate fingerprints:
       MD5: F1:5B:9B:A1:F7:16:CF:25:CF:F4:FF:35:3F:4C:9C:F0
       SHA1: B2:00:50:DD:B6:CC:35:66:21:45:0F:96:AA:AF:6A:3D:E4:03:7C:74
   Trust this certificate? [no]:  yes
   Certificate was added to keystore
         

5. Examine the truststore. Note that the entry type is trustedCertEntry, which means that a private key is not available for this entry (shown in red). It also means that this file is not suitable as a KeyManager's keystore.

   % keytool -list -v -keystore truststore 
   Enter keystore password:  trustword
   
   Keystore type: jks
   Keystore provider: SUN
   
   Your keystore contains 1 entry
   
   Alias name: dukecert
   Creation date: Dec 20, 2001
   Entry type: trustedCertEntry
   
   Owner: CN=Duke, OU=Java Software, O="Sun Microsystems, Inc.", L=Palo Alto, ST=CA, C=US
   Issuer: CN=Duke, OU=Java Software, O="Sun Microsystems, Inc.", L=Palo Alto, ST=CA, C=US
   Serial number: 3c22adc1
   Valid from: Thu Dec 20 19:34:25 PST 2001 until: Thu Dec 27 19:34:25 PST 2001
   Certificate fingerprints:
       MD5: F1:5B:9B:A1:F7:16:CF:25:CF:F4:FF:35:3F:4C:9C:F0
       SHA1: B2:00:50:DD:B6:CC:35:66:21:45:0F:96:AA:AF:6A:3D:E4:03:7C:74
         

   Now run your applications with the appropriate key stores. This example assumes the default X509KeyManager and X509TrustManager are used, thus we will select the keystores using the system properties described in Customization.

   % java -Djavax.net.ssl.keyStore=keystore \
     -Djavax.net.ssl.keyStorePassword=password Server
   
   % java -Djavax.net.ssl.trustStore=truststore \
     -Djavax.net.ssl.trustStorePassword=trustword Client