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