Replacing listener certificates
Certificate authorities typically restrict the lifespans of the certificates that they sign. If you use a certification authority to issue listener certificates, you are likely replacing the certificates on a regular basis.
About this task
The replace-certificate
tool performs the following steps:
-
Obtain a new certificate chain.
-
Make necessary updates to the key manager provider and the connection handler configurations
-
Update the server instance listener configuration with the new certificate.
The replace-certificate
tool offers the following modes of operation:
- Interactive mode
-
Walks you through the process of obtaining a new certificate and installing it in the server. Interactive mode also displays the non-interactive commands that are required to achieve the same result.
- Non-interactive mode
-
Useful when scripting the process of replacing a certificate.
Steps
-
To replace a listener certificate, run the
replace-listener-certificate
subcommand of thereplace-certificate
tool.You can replace certificates manually, but the
replace-certificate
tool automates the process. Thereplace-certificate
tool provides information about multiple listener certificates during the transitional phase that occurs when you install them.The
replace-listener-certificate
subcommand takes arguments that provide the following information:-
Arguments required to authenticate to , such as
--bindDN
and--bindPasswordFile
-
Details about the key store that contains the new certificate
-
Updates that must be made to the key and trust manager providers
-
Whether to signal the HTTP connection handler to reload its certificates after the update is complete
The following arguments are available:
Argument Description --source-key-store-file {path}
Path to the Java KeyStore (JKS) or PKCS #12 file that contains the private key entry with the new certificate chain. This argument is required.
--source-key-store-password {password}
Clear-text password that is needed to access the contents of the source key store.
--source-key-store-password-file {path}
Path to the file that contains the password necessary to access the contents of the source key store. The file can contain the password in the clear or can be encrypted with a definition from the server’s encryption settings database.
--source-certificate-alias {alias}
Password that is required to access the appropriate private key in the source key store. If neither the
--source-private-key-password
nor the--source-private-key-password-file
argument is provided, the key store password is used as the private key password.--source-private-key-password-file {path}
Path to the file that contains the password needed to access the appropriate private key in the source key store. The file can contain the password in the clear or can be encrypted with a definition from the server’s encryption settings database. If neither the
--source-private-key-password
nor the--source-private-key-password-file
argument is provided, the key store password is used as the private key password.--key-manager-provider {name}
Name of the key manager provider that is updated to use the new certificate chain. The value must identify a file-based key manager provider, and the new certificate chain must be enabled. Defaults to
JKS
if a value is not specified.--trust-manager-provider {name}
Name of the trust manager provider that is updated with the information required to trust the new certificate chain. The value must identify a file-based trust manager provider, and the new certificate chain must be enabled. If neither this argument nor the
--use-jvm-default-trust-manager-provider
argument is provided, the tool assumes that the name of the trust manager provider is identical to the name of the key manager provider.--use-jvm-default-trust-manager-provider
Indicates that the server must be configured to use the JVM-default trust manager provider, which trusts certificates signed by issuers in the
cacerts
trust store provided with the Java virtual machine (JVM), rather than updating an existing trust manager provider.--target-certificate-alias {alias}
Alias to use for the new certificate in the key manager provider’s key store, and for appropriate updates in the trust manager provider’s trust store. Defaults to an alias of
server-cert
if a value is not specified.If the key manager provider’s key store, or the trust manager provider’s trust store, already contains an entry with the given alias, the existing entry is renamed.
--reload-http-connection-handler-certificates
Indicates that the tool is requesting that the server cause any HTTPS-based connection handlers to reload their certificates, so that the connection handlers can use the updated certificate.
LDAP connection handlers react to the change immediately and start presenting the new certificate chain during subsequent TLS negotiations. HTTPS connection handlers continue using the former certificate until the connection handler is restarted or until the connection handler is asked specifically to reload its certificates.
This option might prevent clients with existing TLS sessions that were negotiated with the former certificate from being resumed.
-
-
To remove earlier certificates from the server instance listener configuration, run the
purge-retired-listener-certificates
subcommand.The
purge-retired-listener-certificates
subcommand does not take arguments other than the ones that are required to authenticate to the server.By default, the
replace-certificate
tool updates the server instance listener configuration object to include the new listener certificate, and it merges the old and new certificates residing in the configuration object.