Customizing the Default Key and Trust Stores, Store Types, and Store Passwords

Whenever a default SSLSocketFactory or SSLServerSocketFactory is created (via a call to SSLSocketFactory.getDefault or SSLServerSocketFactory.getDefault), and this default SSLSocketFactory (or SSLServerSocketFactory) comes from the JSSE reference implementation, a default SSLContext is associated with the socket factory. (The default socket factory will come from the JSSE implementation.)

This default SSLContext is initialized with a default KeyManager and a TrustManager. If a keystore is specified by the javax.net.ssl.keyStore system property, then the KeyManager created by the default SSLContext will be a KeyManager implementation for managing the specified keystore. In this case, if such a property exists but the file it specifies doesn't, then an error will be thrown. If no javax.net.ssl.keyStore property exists, then a default keystore is searched for. If a keystore named <install_dir>/jre/lib/security/jssecacerts is found, it is used. If not, then a keystore named <install_dir>/jre/lib/security/cacerts is searched for and used (it must exist).If a keystore is specified by the javax.net.ssl.keyStore system property, then the KeyManager created by the default SSLContext will be a KeyManager implementation for managing the specified keystore. (The actual implementation will be as specified in Customizing the Default Key and Trust Managers.)

Similarly, if a truststore is specified by the javax.net.ssl.trustStore system property, then the TrustManager created by the default SSLContext will be a TrustManager implementation for managing the specified truststore. In this case, if such a property exists but the file it specifies doesn't, then an error will be thrown. If no javax.net.ssl.trustStore property exists, then a default truststore is searched for. If a truststore named <install_dir>/jre/lib/security/jssecacerts is found, it is used. If not, then a truststore named <install_dir>/jre/lib/security/cacerts is searched for and used (it must exist).

Important: The SDK ships with a limited number of trusted root certificates in the <install_dir>/jre/lib/security/cacerts file. As documented in keytool, it is your responsibility to maintain (that is, add and remove) the certificates contained in this file if you use this file as a truststore.

Depending on the certificate configuration of the servers you contact, you may need to add additional root certificates. Obtain the needed specific root certificates from the appropriate vendor.

If system properties javax.net.ssl.keyStoreType, or javax.net.ssl.keyStorePassword, or both are also specified, they are treated as the default KeyManager keystore type and password, respectively. If there is no type specified, the default type is that returned by KeyStore.getDefaultType(), which is the value of the keystore.type security property, or jks if no such security property is specified. If there is no keystore password specified, it is assumed to be changeit.

Similarly, if system properties javax.net.ssl.trustStoreType or javax.net.ssl.trustStorePassword, or both are also specified, they are treated as the default truststore type and password, respectively. If there is no type specified, the default type is that returned by KeyStore.getDefaultType(). If there is no truststore password specified, it is assumed to be "".

Important: This section describes the current JSSE reference implementation behavior. The system properties described in this section are not guaranteed to continue to have the same names and types (system or security) or even to exist at all in future releases. They are also not guaranteed to be examined and used by any other JSSE implementations. If they are examined by an implementation, that implementation should handle them in the same manner as the JSSE reference implementation does, as described herein.