Certification authorities typically restrict the lifespans of the certificates that they sign. If you use a certification authority to issue listener certificates, you probably need to replace the certificates on a regular basis. This task includes 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.

Although you can replace certificates manually, the replace-certificate tool helps to automate the process. The replace-certificate tool is particularly useful because it provides information about multiple listener certificates, at least during the transitional phase that occurs when you install them.

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. In addition to the convenience this offers, 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.

The replace-listener-certificate subcommand handles all of the work that is involved in replacing a listener certificate. Besides the arguments that are required to authenticate to PingDirectory Server, such as --bindDN and --bindPasswordFile, the replace-listener-certificate subcommand also takes arguments that provide the following information:

  • Details about the keystore 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:

  • --source-key-store-file {path} – Path to the 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} – Cleartext password that is needed to access the contents of the source keystore.
  • --source-key-store-password-file {path} – Path to the file that contains the password necessary to access the contents of the source keystore. 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 keystore. If neither the --source-private-key-password nor the --source-private-key-password-file argument is provided, the keystore 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 keystore. 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 keystore 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 it 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 it 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 truststore provided with the 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 keystore, as well as for appropriate updates in the trust manager provider's truststore. Defaults to an alias of server-cert if a value is not specified.

    Note: If the key manager provider's keystore, or the trust manager provider's truststore, 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. However, 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.

The following example uses Interactive mode to replace the listener certificate chain. The output includes the non-interactive commands that are needed to perform the corresponding operations:

$ bin/replace-certificate
This tool can be used to replace the listener certificate or the
inter-server certificate for this Directory Server server instance
 
Which action would you like to perform?
 
1 - Replace a listener certificate that the server uses forTLS
    communication
2 - Replace the inter-server certificate that the server uses to
    authenticate to other instances in the topology
3 - Purge any retired listener certificates for this server from the
    topology registry
4 - Purge any retired inter-server certificates for this server from the
    topology registry
q - Quit without doing anything
 
Enter your choice: 1
 
 
 
Enter the DN of the account to use to authenticate to the server
[cn=Directory Manager]: cn=Directory Manager
Enter the password for that user: {password}
 
NOTE:  'JKS' is the only key manager provider that is suitable to be
updated with a new listener certificate.  Automatically selecting that
provider
 
 
Which trust manager provider do you wish to update with information needed
to trust the new listener certificate?
 
1 - JKS
d - Use the JVM-default trust manager provider to trust any certificate
    signed by an authority in the JVM's default set of trusted issuers
 
Enter your choice [1]: 1
 
 
 
How would you like to obtain the new listener certificate?
 
1 - Generate a new self-signed certificate
2 - Generate a request for a certificate to be signed by a certification
    authority
3 - Use a certificate in an existing key store
q - Quit without doing anything
 
Enter your choice: 2
 
Enter the subject DN that you would like to use for the new certificate.
The subject DN typically includes some or all of the following components:
 
* CN -- The common name for the certificate.  This is typically the
  fully-qualified name (not an IP address) that most clients will use to
  connect to the server (alternate names and IP addresses may be provided
  later).  We strongly recommend including a CN attribute in the
  certificate subject
* OU -- Typically the name of the department or organizational unit that
  manages the server
* O -- Typically the name of the company or organization that manages the
  server
* L -- Typically the name of the city or locality in which the server is
  located
* ST -- Typically the full name (NOT an abbreviation) of the state or
  province in which the server is located
* ST -- Typically the two-character ISO 3166 country code for the country
  in which the server is located
 
For example, a subject DN might look like 'CN=ds.example.com,OU=Directory
Services,O=Example Corp,L=Austin,ST=Texas,C=US'
 
Enter the desired subject DN: CN=ds1.example.com,O=Example Corp,C=US
 
Enter the complete set of resolvable names (not IP addresses) that clients
are expected to use to access the server.  These names will be included in
the certificate's subject alternative name extension
 
Specific host names are generally preferable, but you may use an asterisk
as a wildcard in the leftmost component that will match any host name in
that component.  For example, '*.example.com' indicates that the
certificate may be used in any server whose fully-qualified name consists of
exactly three components, and in which the last two components are
'example.com'
 
The current set of DNS names to include in the set of subject alternative
names is:
 
* ds1.example.com
* ip6-localhost
* localhost
 
What would you like to do?
 
1 - Use the current set of DNS names
2 - Add another DNS name
3 - Remove a specific DNS name
4 - Clear the current set of DNS names
5 - Do not include any subject alternative DNS names in the certificate
 
Enter your choice [1]: 2
 
Enter the new DNS name to include: ds.example.com
 
 
The current set of DNS names to include in the set of subject alternative
names is:
 
* ds.example.com
* ds1.example.com
* ip6-localhost
* localhost
 
What would you like to do?
 
1 - Use the current set of DNS names
2 - Add another DNS name
3 - Remove a specific DNS name
4 - Clear the current set of DNS names
5 - Do not include any subject alternative DNS names in the certificate
 
Enter your choice [1]: 1
 
Enter the complete set of IPv4 and IPv6 addresses that clients are
expected to use to access the server.  These addresses will be included in
the certificate's subject alternative name extension.  Wildcards are not
allowed
 
 
The current set of IP addresses to include in the set of subject
alternative names is:
 
* 0:0:0:0:0:0:0:1
* 10.5.1.133
* 10.5.3.99
* 127.0.0.1
* 127.0.1.1
* 172.30.12.185
* fe80:0:0:0:3957:af69:bd92:6c73
* fe80:0:0:0:ace8:231f:e348:db8d
* fe80:0:0:0:fc94:6eff:fe1d:811d
 
What would you like to do?
 
1 - Use the current set of IP addresses
2 - Add another IP address
3 - Remove a specific IP address
4 - Clear the current set of IP addresses
5 - Do not include any subject alternative IP addresses in the certificate
 
Enter your choice [1]: 1
 
Generating a certificate signing request with the following command:
 
manage-certificates \
   generate-certificate-signing-request \
   --output-file /ds/tmp/replace-certificate-certificate-signing-request-\
     6730986100632343057.pem \
   --output-format PEM \
   --keystore /d0s/tmp/replace-certificate-temporary-key-store- \
     281484917294163222.jks \
   --keystore-password-file '*****REDACTED*****' \
   --keystore-type JKS \
   --alias generated-certificate \
   --subject-dn "CN=ds1.example.com,O=Example Corp,C=US" \
   --key-algorithm RSA \
   --key-size-bits 2048 \
   --signature-algorithm SHA256withRSA \
   --key-usage digitalSignature \
   --key-usage keyEncipherment \
   --extended-key-usage server-auth \
   --extended-key-usage client-auth \
   --subject-alternative-name-dns ds.example.com \
   --subject-alternative-name-dns ds1.example.com \
   --subject-alternative-name-dns ip6-localhost \
   --subject-alternative-name-dns localhost \
   --subject-alternative-name-ip-address 0:0:0:0:0:0:0:1 \
   --subject-alternative-name-ip-address 10.5.1.133 \
   --subject-alternative-name-ip-address 10.5.3.99 \
   --subject-alternative-name-ip-address 127.0.0.1 \
   --subject-alternative-name-ip-address 127.0.1.1 \
   --subject-alternative-name-ip-address 172.30.12.185 \
   --subject-alternative-name-ip-address fe80:0:0:0:3957:af69:bd92:6c73 \
   --subject-alternative-name-ip-address fe80:0:0:0:ace8:231f:e348:db8d \
   --subject-alternative-name-ip-address fe80:0:0:0:fc94:6eff:fe1d:811d
 
Successfully generated the following certificate signing request, which
has also been written to file
   '/ds/tmp/replace-certificate-certificate-signing-request-
    6730986100632343057.pem':
 
-----BEGIN CERTIFICATE REQUEST-----
MIIDoTCCAosCAQAwPjELMAkGA1UEBgwCVVMxFTATBgNVBAoMDEV4YW1wbGUgQ29y
cDEYMBYGA1UEAwwPZHMxLmV4YW1wbGUuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOC
AQ8AMIIBCgKCAQEAgYFiIt72o1uHAbqyE3dnMUDvf/tBl6ItzzODkk8oUtF4bRFu
K+RZvz+NzkADVbwIkXOLIIbmRcQZdyPMCZ/gmhzLhwetyu3IeTbPZk682iEf8B5r
8Q/4FwrmoTRuRSrYJ4V9N6lPyrouK2i8G72GA8QiUCG6Cjil4aIhjkPjqbSD9lZF
Nv7BWmsizXaQ/j8I2yRly29JKxp84mO0h6N9npqCIQN/XqdFbFfNERO0h7oBOFpH
J+yepsmbOdQE2Ywbru4TqqizVgsokQSr7oGWSSsS5KwwSPUwjhmsNzIU20UBEjrV
Xa3XiXxBK6aKYWqXlN4N3rxaYZQWbxMJK5wWwQIDAQABoIIBHjCCARoGCSqGSIb3
DQEJDjGCAQswggEHMB0GA1UdDgQWBBT5FA1stRYO99mFHb3BzjMkyRLbBjCBuAYD
VR0RBIGwMIGtgg5kcy5leGFtcGxlLmNvbYIPZHMxLmV4YW1wbGUuY29tgg1pcDYt
bG9jYWxob3N0gglsb2NhbGhvc3SCCm5hdy1zZXJ2YWyHEAAAAAAAAAAAAAAAAAAA
AAGHBAoFAYWHBAoFA2OHBH8AAAGHBH8AAQGHBKweDLmHEP6AAAAAAAAAOVevab2S
bHOHEP6AAAAAAAAArOgjH+NI242HEP6AAAAAAAAA/JRu//4dgR0wDAYDVR0PBAUD
AwegADAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwCwYJKoZIhvcNAQEL
A4IBAQA0B/QipNqyj0nqJ8lz4xXbE3axtswdosJ140nIzDXNE5TRBpQZg8PgfhI/
argRATg7XuWe4xapgYpVpNBFZOLAKsknc1AjVvjakavprQkRYnhKqH6Delao2Lo+
1KsznomWn4oEoEWZ6+AHtuf50t2LeBc82tQTdijxhqlfIPhVd+spDxMhcdWehPOx
ZZoTyAtiCDfjUhMxh7ez+jAKHwLkiZXwgiPJvRbYdbz3/1Bs2XqIj7mfmYrU6zAr
Zr+Jo/utfw6ayDwp32+9JtIAROF9GqVGxrJeAam789rVnr+Bh3jK2VdccTNdvi4H
1nPfqr6v6lpMdrcW/chboRETOtl9
-----END CERTIFICATE REQUEST-----
 
 
How would you like to import the signed certificate into the key store?
 
1 - I expect to get the signed certificate back right away.  Walk me
    through the process of importing it into the key store
2 - I will manually import the signed certificate
 
Enter your choice [1]: 1
Enter the path to the file containing the signed certificate (and
optionally any necessary issuer certificates): /ca/server-cert.pem
 
 
NOTICE:  Certificate file '/ca/server-cert.pem' ends with certificate
'CN=ds1.example.com,O=Example Corp,C=US' that was signed by issuer
'CN=Example Intermediate CA,O=Example Corp,C=US', but that issuer
certificate could not be found in the JVM-default trust store
 
Enter the path to a file containing the
'CN=Example Intermediate CA,O=Example Corp,C=US' certificate (and
optionally its issuer chain): /ca/intermediate-ca-cert.pem
 
 
NOTICE:  Certificate file '/ca/intermediate-ca-cert.pem' ends with
certificate 'CN=Example Intermediate CA,O=Example Corp,C=US' that was
signed by issuer 'CN=Example Root CA,O=Example Corp,C=US', but that issuer
certificate could not be found in the JVM-default trust store
 
Enter the path to a file containing the 'CN=Example Root CA,O=Example
Corp,C=US' certificate (and optionally its issuer chain): /ca/root-ca-cert.pem
 
 
 
Would you like to request that the server reload any certificates
associated with HTTP connection handlers configured with support for HTTPS
so that they will start using the new certificate right away?  Note that
this may prevent clients from resuming TLS sessions created before the
reload
 
1 - Yes.  Reload the certificates associated with any HTTPS-enabled HTTP
    connection handlers
2 - No.  Do not reload the certificates.  HTTPS connection handlers will
    continue to use their current certificates until the server (or at
    least the connection handler) is restarted, or until the
    reload-http-connection-handler-certificates tool is run
q - Quit without doing anything else
 
Enter your choice [1]: 1
 
 
About to invoke the following command:
 
     replace-certificate \
          replace-listener-certificate \
          --bindDN "cn=Directory Manager" \
          --bindPassword '*****REDACTED*****' \
          --key-manager-provider JKS \
          --trust-manager-provider JKS \
          --source-key-store-file /ds/tmp/replace-certificate-temporary-key- \
            store-281484917294163222.jks \
          --source-key-store-password-file /ds/config/ads-truststore.pin \
          --source-certificate-alias generated-certificate \
          --reload-http-connection-handler-certificates
 
Do you want to invoke this command?
 
1 - Yes, run this replace-certificate command
2 - No.  Quit without doing anything else
 
Enter your choice [1]: 1
Successfully replaced the listener certificate

As part of its processing steps, the replace-certificate tool updates the server instance listener configuration object to include the new listener certificate. Instead of replacing any certificates that may already reside within the configuration object, the replace-certificate tool merges them with the new certificate. To remove earlier certificates from the server instance listener configuration, use the purge-retired-listener-certificates subcommand, which does not take arguments other than the ones that are required to authenticate to the server.

The following code provides an example:

$ bin/replace-certificate
This tool can be used to replace the listener certificate or the
inter-server certificate for this Directory Server server instance
 
Which action would you like to perform?
 
1 - Replace a listener certificate that the server uses for TLS
    communication
2 - Replace the inter-server certificate that the server uses to
    authenticate to other instances in the topology
3 - Purge any retired listener certificates for this server from the
    topology registry
4 - Purge any retired inter-server certificates for this server from the
    topology registry
q - Quit without doing anything
 
Enter your choice: 3
 
 
 
Enter the DN of the account to use to authenticate to the server
[cn=Directory Manager]: cn=Directory Manager
Enter the password for that user: {password}
 
 
About to invoke the following command:
 
     replace-certificate \
          purge-retired-listener-certificates \
          --bindDN "cn=Directory Manager" \
          --bindPassword '*****REDACTED*****'
 
Do you want to invoke this command?
 
1 - Yes, run this replace-certificate command
2 - No.  Quit without doing anything else
 
Enter your choice [1]: 1
 
NOTE:  Purging one non-active listener certificate from entry
'cn=ldap-listener-mirrored-config,cn=Server Instance Listeners,cn=ds1,cn=Server
Instances,cn=Topology,cn=config'
Successfully updated entry 'cn=ldap-listener-mirrored-config,cn=Server Instance
Listeners,cn=ds1,cn=Server Instances,cn=Topology,cn=config'
 
Successfully purged one retired listener certificate