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.