The replace-certificate tool performs the following steps:

  1. Obtain a new certificate chain.
  2. Make necessary updates to the key manager provider and the connection handler configurations
  3. 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.
  • To replace a listener certificate, run the replace-listener-certificate subcommand of the replace-certificate tool.
    Note:

    You can replace certificates manually, but the replace-certificate tool automates the process. The replace-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:

    ArgumentDescription
    --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.
    Note:

    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.

    Note:

    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.
    Note:

    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.