Enabling TLS support after setup
If the server has been set up without support for TLS, enable TLS support later by completing the following tasks.
Steps
-
Obtain a certificate chain.
For more information about obtaining a certificate chain, see Certificate chains. To prepare a Java KeyStore JKS or PKCS #12 key store with an appropriate certificate chain and private key, use the
manage-certificates
tool. We also recommend that you create a trust store that the server can use. -
Configure the key and trust manager providers.
For more information, see Configuring key and trust manager providers.
-
Configure connection handlers.
For more information, see Configuring connection handlers.
Configuring key and trust manager providers
After you have a key store, configure a key manager provider to access it.
The server is preconfigured with key manager providers, JKS
and PKCS12
, that you can use with JKS or PKCS #12 key stores, respectively. In most cases, you can update the appropriate key manager provider to reference the key store that you plan to use, as shown in the following example:
dsconfig set-key-manager-provider-prop \ --provider-name JKS \ --set enabled:true \ --set key-store-file:config/keystore \ --set key-store-pin-file:config/keystore.pin
A similar change configures a trust manager provider to reference the appropriate trust store, as shown in the following example:
dsconfig set-trust-manager-provider-prop \ --provider-name JKS \ --set enabled:true \ --set include-jvm-default-issuers:true \ --set trust-store-file:config/truststore \ --set trust-store-pin-file:config/truststore.pin
If all clients and servers use certificates that are signed by issuers and are included in the JVM’s default trust store, you can use the |
Caching key and trust managers
When you create key and trust manager providers, caching is enabled by default, allowing the manager providers to avoid loading key store and trust store files from disk when establishing connections to process requests.
Invalidating the cache
The manager provider reloads files from the configured key store or trust store and refreshes the cache under any of the following conditions:
-
The cached manager for the configured store has a
null
value. -
The path to the cached store doesn’t match the path of the configured store.
-
The length of the cached store doesn’t match the length of the configured store.
-
The last-updated time for the cached store doesn’t match the last-updated time for the configured store.
Enabling or disabling caching (optional)
You can define whether caching is enabled by using the enable-key-manager-caching
or enable-trust-manager-caching
properties. Supply a value of false
to disable caching, causing manager providers to load managers for each connection. Supply a value of true
to re-enable caching.
To create a key manager provider with caching disabled, supply the enable-key-manager-caching
property with a value of false
, as shown in the following example:
dsconfig create-key-manager-provider \ --provider-name JKS \ --type file-based \ --set enabled:true \ --set key-store-file:config/keystore \ --set key-store-type:JKS \ --set key-store-pin-file:config/keystore.pin \ --set enable-key-manager-caching:false
To create a trust manager provider with caching disabled, supply the enable-trust-manager-caching
property with a value of false
, as shown in the following example:
dsconfig create-trust-manager-provider \ --provider-name JKS \ --type file-based \ --set enabled:true \ --set trust-store-file:config/truststore \ --set trust-store-type:JKS \ --set enable-trust-manager-caching:false
To re-enable caching, set a value of true
for the same caching property used to create the manager provider, as shown in the following example:
dsconfig set-trust-manager-provider-prop \ --provider-name JKS \ --set enable-trust-manager-caching:true
Configuring connection handlers
After you configure the key and trust manager providers, update the connection handlers to use the key and trust manager providers.
Steps
-
For the LDAP connection handler, use the following command to enable StartTLS with a configuration change. By default, the LDAP connection handler accepts non-secure connections.
Example:
dsconfig set-connection-handler-prop \ --handler-name "LDAP Connection Handler" \ --set allow-start-tls:true \ --set key-manager-provider:JKS \ --set trust-manager-provider:JKS \ --set ssl-cert-nickname:server-cert \ --set ssl-client-auth-policy:optional
-
If you did not configure secure communication during setup, the LDAPS connection handler is disabled. To configure LDAPS support in this scenario, enable the connection handler and configure most of the same settings. You must set
allow-start-tls
tofalse
anduse-ssl
totrue
. See the following code for an example configuration.Example:
dsconfig set-connection-handler-prop \ --handler-name "LDAPS Connection Handler" \ --set enabled:true \ --set key-manager-provider:JKS \ --set trust-manager-provider:JKS \ --set ssl-cert-nickname:server-cert \ --set ssl-client-auth-policy:optional
Example:
The following example uses a similar configuration change to enable the HTTPS connection handler.
dsconfig set-connection-handler-prop \ --handler-name "HTTPS Connection Handler" \ --set enabled:true \ --set listen-port:443 \ --set key-manager-provider:JKS \ --set trust-manager-provider:JKS \ --set ssl-cert-nickname:server-cert
Updating the topology registry
After the server connection handlers are updated to enable TLS, update the topology registry to provide information about the new configuration.
The topology registry holds information about server instances that are part of the environment, and it helps to facilitate inter-server communication, such as replication, mirroring portions of the configuration, and the PingDirectory server’s automatic backend server-discovery functionality.
The following table details the two types of entries that require updating.
Configuration Type | Update description | ||
---|---|---|---|
Server instance listener configuration |
|
||
Server instance configuration |
The following example code sets the LDAPS and HTTPS ports, indicates that StartTLS support is enabled, and instructs other instances to use SSL (LDAPS) when communicating with the instance. dsconfig set-server-instance-prop \ --instance-name ds1 \ --set ldaps-port:636 \ --set https-port:443 \ --set preferred-security:ssl \ --set start-tls-enabled:true |