PingDirectory

Replacing the inter-server certificate

The inter-server certificate is only intended for use between instances within the same topology.

It is not exposed to normal clients, so it doesn’t need to be trusted. It is generated at install time with along life span, so it should not need to be replaced under normal circumstances. In fact, we discourage replacing the inter-server certificate unless you have reason to suspect that its private key has been compromised.

If you do need to replace the inter-server certificate, the replace-certificate replace-inter-server-certificate command can be used to accomplish this. As when replacing a listener certificate, it takes the new inter-server certificate from a provided Java KeyStore (JKS) or PKCS #12 key store, and it makes the necessary updates to the appropriate server key store, and in the case of the inter-server certificate, that is the one in the config/ads-truststore file. It also updates the server instance configuration object to include the new inter-server certificate.

The server currently requires the inter-server certificate to use an RSA key pair, and the key size must be between 2048 bits and 3072 bits. Certificates with an elliptic curve key pair are not allowed, nor are certificates with an RSA key smaller than 2048 bits or larger than 3072 bits.

Use a self-signed certificate with a long life span so that it does not need to be replaced on a regular basis. Each instance should have its own unique inter-server certificate.

The replace-inter-server-certificate subcommand takes a subset of the arguments used in conjunction with the replace-listener-certificate subcommand. The available arguments include:

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

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

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

  • --source-certificate-alias <alias>

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

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

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

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

The following example demonstrates the process for replacing the inter-server certificate in interactive mode, but includes the non-interactive command needed to achieve the same result.

$ 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: 2

WARNING:  The inter-server certificate is used only for the purpose of
authenticating this server instance to other servers in the topology, and
to encrypt some legacy secrets.  It is NOT used to encrypt communication
(listener certificates are used for that purpose), and the trust mechanism
that we use for authenticating inter-server certificates is stronger when
using self-signed certificates than when using certificates signed by a
publicly trusted authority

We strongly discourage replacing the inter-server certificate unless you
believe that the key has been compromised.  Any errors in the process of
replacing the certificate could render the server unable to authenticate
to other instances in the topology, and may interfere with replication or
other forms of inter-server communication, and also the server's ability
to perform certain types of encryption and digital signing

Are you sure you want to replace the inter-server certificate?

1 - No.  Do not replace the inter-server certificate
2 - Yes.  Proceed with replacing the inter-server certificate

Enter your choice [1]: 2

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}

How would you like to obtain the new inter-server 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.  Note that each server
	instance must have a unique inter-server certificate, and we do not
	recommend using the same certificate as both a listener certificate
	and an inter-server certificate
q - Quit without doing anything

Enter your choice: 1

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,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]: 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 self-signed certificate with the following command:

     manage-certificates \
          generate-self-signed-certificate \
          --keystore /ds/tmp/replace-certificate-temporary-key-store-12068302381295037387.jks \
          --keystore-password-file 'REDACTED' \
          --keystore-type JKS \
          --alias generated-certificate \
          --subject-dn "CN=ds1,O=Example Corp,C=US" \
          --validity-start-time 20191111120632 \
          --days-valid 7300 \
          --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 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 self-signed certificate


About to invoke the following command:

     replace-certificate \
          replace-inter-server-certificate \
          --bindDN "cn=Directory Manager" \
          --bindPassword 'REDACTED*' \
          --source-key-store-file /ds/tmp/replace-certificate-temporary-key-store-12068302381295037387.jks \
          --source-key-store-password-file /ds/config/ads-truststore.pin \
          --source-certificate-alias generated-certificate

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 inter-server certificate

The new inter-server certificate is merged with any existing values in the server instance configuration entry. You can use the purge-retired-inter-server-certificates subcommand to remove any older values once you are confident that they are no longer needed, as in the following 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: 4



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-inter-server-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
# Initializing the server's encryption framework...
Successfully purged one retired inter-server certificate from the topology
registry