PingDirectory

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:

  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.

Steps

  • To replace a listener certificate, run the replace-listener-certificate subcommand of the replace-certificate tool.

    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 PingDataSync, such as --bindDN and --bindPasswordFile

    • Details about the key store, PEM, or DER file 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-certificate-file <path>

    The path to the PEM or DER file that contains the new certificate chain. Either this argument or --source-key-store-file <path> must be provided.

    If you are providing a certificate chain with multiple certificates, order the chain with the server certificate first. Each subsequent certificate should be the issuer for the previous certificate.

    You can provide --source-certificate-file multiple times if the certificates in the chain are in separate files rather than one file.

    --source-private-key-file <path>

    The path to the PEM or DER file that contains the private key that correlates to the new PEM or DER server certificate. This argument must be provided when including --source-certificate-file <path>.

    --source-key-store-file <path>

    The path to the Java KeyStore (JKS) or PKCS #12 file that contains the private key entry with the new certificate chain. Either this argument or --source-certificate-file <path> must be provided.

    --source-key-store-password <password>

    The clear-text password needed to access the contents of the source key store.

    --source-key-store-password-file <path>

    The path to a file containing the password needed to access the contents of the source key store. The file can contain the password in the clear, or it can be encrypted with a definition from the server’s encryption settings database.

    --source-certificate-alias <alias>

    The alias of the private key entry in the source key store that contains the certificate chain for the new listener certificate. If the source key store has more than one private key entry, then this argument must be provided to indicate which one to use.

    --source-private-key-password <password>

    The password needed to access the appropriate private key in the source key store, PEM, or DER file. If neither the --source-private-key-password nor the --source-private-key-password-file argument is provided, then the key store password is also used as the private key password.

    --source-private-key-password-file <path>

    The path to a file containing the password needed to access the appropriate private key in the source key store, PEM, or DER file. The file can contain the password in the clear, or it 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, then the key store password is also used as the private key password.

    --key-manager-provider <name>

    The name of the key manager provider that will be updated to use the new certificate chain. It must be a file-based key manager provider, and it must be enabled. If this argument is not provided, a default value of “JKS” is assumed.

    --trust-manager-provider <name>

    The name of the trust manager provider that will be updated with the information needed to trust the new certificate chain. It must be 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, then the tool assumes that the trust manager provider has the same name as the key manager provider, though these providers remain separate and distinct.

    --use-jvm-default-trust-manager-provider

    Indicates that the server should be configured to use the JVM-default trust manager provider, which trusts certificates signed by issuers in the cacerts trust store provided with the JVM, rather than updating an existing trust manager provider.

    --target-certificate-alias <alias>

    The alias to use for the new certificate in the key manager provider’s key store and also for any appropriate updates in the trust manager provider’s trust store. If this is not provided, a default alias of “server-cert” is used.

    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 will be renamed.

    --reload-http-connection-handler-certificates

    Indicates that the tool should request that the server cause any HTTPS-based connection handlers to reload their certificates so that they will start using the updated certificate. LDAP connection handlers reacts to the change right away and start presenting the new certificate chain during any subsequent TLS negotiations, but HTTPS connection handlers will continue using the former certificate until the connection handler is restarted or until it is specifically asked to reload its certificates.

    Using this option can prevent clients with existing TLS sessions negotiated with the former certificate from being resumed.

    The following example illustrates what you see when you run the replace-certificate replace-listener-certificate command with the --help argument:

    replace-certificate replace-listener-certificate \
     --bindDN uid=admin,dc=example,dc=com \
     --bindPasswordFile admin-password.txt \
     --source-key-store-file new-listener-certificate-keystore.jks \
     --source-key-store-type JKS \
     --source-key-store-password-file new-listener-certificate-keystore.pin \
     --source-certificate-alias new-listener-cert \
     --key-manager-provider JKS \
     --trust-manager-provider JKS \
     --target-certificate-alias server-cert

    The following example illustrates replacing a PEM-encoded listener certificate:

    replace-certificate replace-listener-certificate \
     --bindDN cn=Directory Manager \
     --bindPasswordFile admin-password.txt \
     --source-certificate-file new-listener-certificate-chain.pem \
     --source-private-key-file new-private-key.pem \
     --source-private-key-password-file encrypted-private-key-password.txt \
     --key-manager-provider JKS \
     --trust-manager-provider JKS \
     --target-certificate-alias server-cert

  • The following example demonstrates using the replace-certificate tool in interactive mode to replace the listener certificate chain. The output also includes the non-interactive commands 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 /ds/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

  • 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.