Changing Server Certificates

This chapter covers how to replace OpenDJ key pairs and public key certificates. In this chapter you will learn to:

Replace a key pair for securing a connection handler
Replace a key pair used for replication
Install a server with a CA-signed certificate for replication
Use a CA-signed certificate for replication

OpenDJ uses keystores (for private keys) and truststores (for public, signed certificates). Up to three sets of keystores are used, as shown in the following illustration.

By default the keystores are located in the /path/to/opendj/config directory:

The keystore and truststore hold keys for securing connections with client applications.
The admin-keystore and admin-truststore hold keys for securing administrative connections, such as those used when connecting with the dsconfig command.
The ads-truststore holds keys for securing replication connections with other OpenDJ servers in the replication topology.

Each keystore has a specific purpose:

admin-keystore: This Java Keystore holds the private key and administrative certificate for the server, admin-cert. This key pair is used to protect communications on the administration port. The password, stored in admin-keystore.pin, is also the key password for admin-cert.
admin-truststore: This Java Keystore holds a copy of the administrative certificate, admin-cert. The password is the same as for the admin-keystore, in other words the string in admin-keystore.pin.
ads-truststore: This Java Keystore holds public key certificates of all servers replicating with the current server. It also includes the ads-certificate key pair of the current server. The password is stored in ads-truststore.pin.

Do not change this keystore directly, except to install a CA-signed certificate for replication as described in "To Use a CA-Signed Certificate for Replication". A server which is installed with the --useKeyStoreForReplication option of the setup command gets its CA-signed key pair at installation time instead, as described in "To Install a Server With a CA-Signed Replication Certificate".
keystore: This Java Keystore holds the private key and server certificate, server-cert, used to protect TLS/SSL communications with client applications. The password, stored in keystore.pin, is also the key password for server-cert.
truststore: This Java Keystore holds a copy of the server-cert certificate from the keystore. This is also where you import certificates of client applications if you want OpenDJ to recognize them. The password is the same as for the keystore, in other words the string in keystore.pin.

Examples in this chapter use self-signed certificates, but you can also use certificates signed by a Certificate Authority (CA).

When importing a certificate (keytool -import) signed by a well-known CA, use the -trustcacerts option to trust the CA certificates delivered with the Java runtime environment.

To Replace a Server Key Pair

This procedure shows how to replace a server key pair in the admin-keystore and copy of the administrative certificate in admin-truststore.

The examples also apply when replacing a key pair in the keystore and copy of the server certificate in truststore. Just adapt the commands to use the correct keystore, truststore, and PIN file names.

This procedure does not apply for replication key pairs. Instead, see "To Replace the Key Pair Used for Replication".

Check the alias of the key pair and certificate copy to replace:

$ cd /path/to/opendj/config
$ keytool -list -keystore admin-keystore -storepass `cat admin-keystore.pin`

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

admin-cert, May 20, 2015, PrivateKeyEntry,
Certificate fingerprint (SHA1): 21:9F:F0:E8:A3:22:A3:62:1D:C7:04:BD:12:44:A6:FA:0C:3F:3A:35
$ keytool -list -keystore admin-truststore -storepass `cat admin-keystore.pin`

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

admin-cert, May 20, 2015, trustedCertEntry,
Certificate fingerprint (SHA1): 21:9F:F0:E8:A3:22:A3:62:1D:C7:04:BD:12:44:A6:FA:0C:3F:3A:35

This alias is also stored in the server configuration.

Remove the key pair and certificate copy to replace:

$ keytool \
 -delete \
 -alias admin-cert \
 -keystore admin-keystore \
 -storepass `cat admin-keystore.pin`

$ keytool \
 -delete \
 -alias admin-cert \
 -keystore admin-truststore \
 -storepass `cat admin-keystore.pin`

Generate a new key pair in the keystore:
```
$ keytool \
 -genkey \
 -alias admin-cert \
 -keyalg RSA \
 -validity 7300 \
 -keysize 2048 \
 -ext "san=dns:opendj.example.com" \
 -dname "CN=opendj.example.com, O=Administration Connector Self-Signed Certificate" \
 -keystore admin-keystore \
 -storepass `cat admin-keystore.pin` \
 -keypass `cat admin-keystore.pin`
```
Notice that the -alias option takes the same alias as before. This is because the ssl-cert-nickname for the Administration Connector is configured as admin-cert. Also, the -dname option has a CN value corresponding to the fully qualified domain name of the host where OpenDJ directory server is running.
Get the new key pair’s certificate signed, using one of the following alternatives:
- Self-sign the certificate:
  $ keytool \ -selfcert \ -alias admin-cert \ -validity 7300 \ -keystore admin-keystore \ -storepass `cat admin-keystore.pin`
- Create a certificate signing request, have it signed by a CA, and import the signed certificate from the CA reply.
  
  For examples of the keytool commands to use, see "To Request and Install a CA-Signed Certificate".

Export a copy of the certificate from the keystore:

$ keytool \
 -export \
 -alias admin-cert \
 -keystore admin-keystore \
 -storepass `cat admin-keystore.pin` \
 -file admin-cert.crt
Certificate stored in file <admin-cert.crt>

Import the copy of the certificate into the truststore:

$ keytool \
 -import \
 -alias admin-cert \
 -keystore admin-truststore \
 -storepass `cat admin-keystore.pin` \
 -file admin-cert.crt
Owner: CN=opendj.example.com, O=Administration Connector Self-Signed Certificate
Issuer: CN=opendj.example.com, O=Administration Connector Self-Signed Certificate
Serial number: 4cdd42a
Valid from: Thu May 28 11:32:05 CEST 2015 until: Wed May 23 11:32:05 CEST 2035
Certificate fingerprints:
  MD5:  40:38:24:5D:DD:BE:EC:D6:07:56:08:25:95:D9:61:FE
  SHA1: BC:3D:A9:26:CD:4E:71:04:44:16:1E:A5:79:DA:43:2A:65:E8:85:85
  SHA256: D3:41:EE:44:5A:54:74:11:5A:...:9F:8F:08:13:09:DD:71:52:7E:35:66:7E
  Signature algorithm name: SHA256withRSA
  Version: 3

Extensions:

#1: ObjectId: 2.5.29.17 Criticality=false
SubjectAlternativeName [
  DNSName: opendj.example.com
]

#2: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 08 E3 D3 62 AA 68 E6 02   52 25 F8 22 C4 43 82 2D  ...b.h..R%.".C.-
0010: 20 C1 39 99                                         .9.
]
]

Trust this certificate? [no]:  yes
Certificate was added to keystore

Restart OpenDJ to make sure it reloads the keystores:
```
$ cd /path/to/opendj/bin
$ stop-ds --restart
```
If you have client applications trusting the self-signed certificate, have them import the new one (admin-cert.crt in this example).

To Replace the Key Pair Used for Replication

Follow these steps to replace the key pair that is used to secure replication connections.

Generate a new key pair for the server.

The changes you perform are replicated across the topology.

OpenDJ has an ads-certificate and private key, which is a local copy of the key pair used to secure replication connections.

To generate the new key pair, you remove the ads-certificate key pair, prompt OpenDJ to generate a new ads-certificate key pair, and then add a copy to the administrative data using the MD5 fingerprint of the certificate to define the RDN.

Delete the ads-certificate entry:

$ ldapmodify \
 --port 1389 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password
dn: ds-cfg-key-id=ads-certificate,cn=ads-truststore
changetype: delete

Processing DELETE request for ds-cfg-key-id=ads-certificate,cn=ads-truststore
DELETE operation successful for DN ds-cfg-key-id=ads-certificate,
 cn=ads-truststore

Prompt OpenDJ to generate a new, self-signed ads-certificate key pair.

You do this by adding an ads-certificate entry with object class ds-cfg-self-signed-cert-request:

$ ldapmodify \
 --port 1389 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password
dn: ds-cfg-key-id=ads-certificate,cn=ads-truststore
changetype: add
objectclass: ds-cfg-self-signed-cert-request

Processing ADD request for ds-cfg-key-id=ads-certificate,cn=ads-truststore
ADD operation successful for DN ds-cfg-key-id=ads-certificate,cn=ads-truststore

Retrieve the ads-certificate entry:

$ ldapsearch \
 --port 1389 \
 --hostname opendj.example.com \
 --baseDN cn=ads-truststore \
 "(ds-cfg-key-id=ads-certificate)"
dn: ds-cfg-key-id=ads-certificate,cn=ads-truststore
ds-cfg-key-id: ads-certificate
ds-cfg-public-key-certificate;binary:: MIIB6zCCAVSgAwIBAgIEDKSUFjANBgkqhkiG9w0BA
 QUFADA6MRswGQYDVQQKExJPcGVuREogQ2VydGlmaWNhdGUxGzAZBgNVBAMTEm9wZW5hbS5leGFtcGxl
 LmNvbTAeFw0xMzAyMDcxMDMwMzNaFw0zMzAyMDIxMDMwMzNaMDoxGzAZBgNVBAoTEk9wZW5ESiBDZXJ
 0aWZpY2F0ZTEbMBkGA1UEAxMSb3BlbmFtLmV4YW1wbGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNAD
 CBiQKBgQCfGLAiUOz4sC8CM9T5DPTk9V9ErNC8N59XwBt1aN7UjhQl4/JZZsetubtUrZBLS9cRrnYdZ
 cpFgLQNEmXifS+PdZ0DJkaLNFmd8ZX0spX8++fb4SkkggkmNRmi1fccDQ/DHMlwl7kk884lXummrzcD
 GbZ7p4vnY7y7GmD1vZSP+wIDAQABMA0GCSqGSIb3DQEBBQUAA4GBAJciUzUP8T8A9VV6dQB0SYCNG1o
 7IvpE7jGVZh6KvM0m5sBNX3wPbTVJQNij3TDm8nx6yhi6DUkpiAZfz/OBL5k+WSw80TjpIZ2+klhP1s
 srsST4Um4fHzDZXOXHR6NM83XxZBsR6MazYecL8CiGwnYW2AeBapzbAnGn1J831q1q
objectClass: top
objectClass: ds-cfg-instance-key

Retrieve the MD5 fingerprint of the ads-certificate.

In this example, the MD5 fingerprint is 07:35:80:D8:F3:CE:E1:39:9C:D0:73:DB:6C:FA:CC:1C:

$ keytool \
 -list \
 -v \
 -alias ads-certificate \
 -keystore /path/to/opendj/config/ads-truststore \
 -storepass `cat /path/to/opendj/config/ads-truststore.pin`
Alias name: ads-certificate
Creation date: Feb 7, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=opendj.example.com, O=OpenDJ Certificate
Issuer: CN=opendj.example.com, O=OpenDJ Certificate
Serial number: ca49416
Valid from: Thu Feb 07 11:30:33 CET 2013 until: Wed Feb 02 11:30:33 CET 2033
Certificate fingerprints:
  MD5:  07:35:80:D8:F3:CE:E1:39:9C:D0:73:DB:6C:FA:CC:1C
  SHA1: 56:30:F6:79:AA:C0:BD:61:88:3E:FB:38:38:9D:84:70:0B:E4:43:57
  SHA256: A8:4B:81:EE:30:2A:0C:09:2E:...:C1:41:F5:AB:19:C6:EE:AB:50:64
  Signature algorithm name: SHA1withRSA
  Version: 3

Using the MD5 fingerprint and the certificate entry, prepare LDIF to update cn=admin data with the new server certificate:

$ cat /path/to/update-server-cert.ldif
dn: ds-cfg-key-id=073580D8F3CEE1399CD073DB6CFACC1C,cn=instance keys,
 cn=admin data
changetype: add
ds-cfg-key-id: 073580D8F3CEE1399CD073DB6CFACC1C
ds-cfg-public-key-certificate;binary:: MIIB6zCCAVSgAwIBAgIEDKSUFjANBgkqhkiG9w0BA
 QUFADA6MRswGQYDVQQKExJPcGVuREogQ2VydGlmaWNhdGUxGzAZBgNVBAMTEm9wZW5hbS5leGFtcGxl
 LmNvbTAeFw0xMzAyMDcxMDMwMzNaFw0zMzAyMDIxMDMwMzNaMDoxGzAZBgNVBAoTEk9wZW5ESiBDZXJ
 0aWZpY2F0ZTEbMBkGA1UEAxMSb3BlbmFtLmV4YW1wbGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNAD
 CBiQKBgQCfGLAiUOz4sC8CM9T5DPTk9V9ErNC8N59XwBt1aN7UjhQl4/JZZsetubtUrZBLS9cRrnYdZ
 cpFgLQNEmXifS+PdZ0DJkaLNFmd8ZX0spX8++fb4SkkggkmNRmi1fccDQ/DHMlwl7kk884lXummrzcD
 GbZ7p4vnY7y7GmD1vZSP+wIDAQABMA0GCSqGSIb3DQEBBQUAA4GBAJciUzUP8T8A9VV6dQB0SYCNG1o
 7IvpE7jGVZh6KvM0m5sBNX3wPbTVJQNij3TDm8nx6yhi6DUkpiAZfz/OBL5k+WSw80TjpIZ2+klhP1s
 srsST4Um4fHzDZXOXHR6NM83XxZBsR6MazYecL8CiGwnYW2AeBapzbAnGn1J831q1q
objectClass: top
objectClass: ds-cfg-instance-key

dn: cn=opendj.example.com:4444,cn=Servers,cn=admin data
changetype: modify
replace: ds-cfg-key-id
ds-cfg-key-id: 073580D8F3CEE1399CD073DB6CFACC1C

Update the administrative data, causing OpenDJ to create a copy of the new ads-certificate with its MD5 signature as the alias in the ads-truststore:

$ ldapmodify \
 --port 1389 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --filename /path/to/update-server-cert.ldif
Processing ADD request for ds-cfg-key-id=073580D8F3CEE1399CD073DB6CFACC1C,
 cn=instance keys,cn=admin data
ADD operation successful for DN ds-cfg-key-id=073580D8F3CEE1399CD073DB6CFACC1C,
 cn=instance keys,cn=admin data
Processing MODIFY request for cn=opendj.example.com:4444,cn=Servers,
 cn=admin data
MODIFY operation successful for DN cn=opendj.example.com:4444,cn=Servers,
 cn=admin data

Force OpenDJ to reopen replication connections using the new key pair.

Stop replication temporarily and then start it again as described in "Configuring Replication":

$ dsconfig \
 set-synchronization-provider-prop \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --provider-name "Multimaster Synchronization" \
 --set enabled:false \
 --no-prompt

$ dsconfig \
 set-synchronization-provider-prop \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --provider-name "Multimaster Synchronization" \
 --set enabled:true \
 --no-prompt

To Install a Server With a CA-Signed Replication Certificate

The setup command can provision the ads-truststore from the key store you already hold, so that a server presents a certificate signed by your own Certificate Authority (CA) on the replication port from its first start. Use this when installing a server which is to join a topology secured with your CA: it replaces the manual procedure of "To Use a CA-Signed Certificate for Replication", which otherwise has to be repeated on every server that joins.

Install the server with the key store holding your CA-signed key pair, adding the --useKeyStoreForReplication option:
```
$ /path/to/opendj/setup \
 --cli \
 --no-prompt \
 --hostname opendj.example.com \
 --ldapPort 1389 \
 --adminConnectorPort 4444 \
 --rootUserDN "cn=Directory Manager" \
 --rootUserPassword password \
 --baseDN dc=example,dc=com \
 --usePkcs12keyStore /path/to/server.p12 \
 --keyStorePasswordFile /path/to/keystore.pin \
 --certNickname server-cert \
 --enableStartTLS \
 --ldapsPort 1636 \
 --useKeyStoreForReplication
```
The server-cert key pair is copied into the ads-truststore, the certificates which issued it are trusted there, and the ssl-cert-nickname property of the crypto manager is set to server-cert. The same applies to the --useJavaKeystore, --useJCEKS and --useBcfksKeystore options. The key store is the one given for LDAPS or StartTLS, so the command has to enable one of them, with --ldapsPort or --enableStartTLS. A certificate generated by the installer and a key held in a PKCS#11 token cannot be used, the first because it would be self-signed like the one it replaces, the second because its private key cannot be exported.
If your key store holds the issued certificate on its own, rather than its whole chain, add the certificates to trust to the same command:
```
 --replicationCaCertFile /path/to/ca.crt
```
Every certificate held in the file is trusted, so a file holding a chain of authorities is given once; repeat the option for certificates held in separate files. The certificate of a key pair is not a trust anchor on its own: the trust managers read the certificate a key belongs to and none of its issuers, so a server whose trust store holds no certificate to trust would trust no peer. Rather than install such a server, the setup command stops and says so.

Once the server has started for the first time, check what the trust store holds:

$ cd /path/to/opendj/config
$ keytool -list -keystore ads-truststore -storepass `cat ads-truststore.pin`

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 3 entries

ads-ca-1, Sep 8, 2026, trustedCertEntry,
Certificate fingerprint (SHA-256): 21:9F:...
server-cert, Sep 8, 2026, PrivateKeyEntry,
Certificate fingerprint (SHA-256): 8D:22:...
ads-certificate, Sep 8, 2026, PrivateKeyEntry,
Certificate fingerprint (SHA-256): 3B:F0:...

The certificates to trust are imported under the ads-ca-1, ads-ca-2… aliases. The ads-certificate key pair is generated by the server when it first starts and stays in the store: it is the crypto manager instance key, published to the topology under cn=instance keys,cn=admin data. It is simply no longer the key pair presented on the replication port.

Every server of a topology has to trust your CA before any of them presents a certificate it signed. Servers installed this way trust it from the start. Servers which are already running do not, and are updated with the procedure below, on all of them, before the first server installed this way joins.

Trusting your CA on the replication port means trusting every certificate it issues, as the certificate is the only credential a peer presents and its subject is not checked. Use a CA dedicated to the replication topology, or one whose issuance you constrain, rather than a corporate CA which also signs certificates for unrelated hosts.

To Use a CA-Signed Certificate for Replication

Replication connections use neither the keystore nor the admin-keystore. Both the key pair presented on the replication port and the certificates trusted on that port are read from the ads-truststore, and the alias to present is the ssl-cert-nickname property of the crypto manager, ads-certificate by default. To secure replication with certificates signed by your own Certificate Authority (CA), install the CA-signed key pair in the ads-truststore of every server.

This procedure applies to servers which are already installed. A server yet to be installed gets the same result from the setup command, as described in "To Install a Server With a CA-Signed Replication Certificate".

Servers authenticate each other on the replication port, so import the CA certificate everywhere first, in a separate pass. A server whose certificate changes before the other servers trust your CA can no longer connect to the topology.

Each keytool command applies to a single server, and is run while that server is stopped. A running server writes the whole ads-truststore back to disk when it adds the certificate of another server to it, which would discard the changes made meanwhile by keytool.

Take each server in turn and add your CA certificate and your CA-signed key pair to its ads-truststore. Replication continues to work during this pass, as the certificates presented by the servers do not change yet.
1. Stop the server:
  $ /path/to/opendj/bin/stop-ds
2. Import the CA certificate, and any intermediate certificates, as trusted certificates:
  $ cd /path/to/opendj/config $ keytool \ -importcert \ -noprompt \ -trustcacerts \ -alias ca-cert \ -file ca-cert.pem \ -keystore ads-truststore \ -storepass `cat ads-truststore.pin` Certificate was added to keystore
  Without -noprompt, keytool asks whether to trust the certificate. When the answer cannot be read, as in a script, it leaves the keystore untouched, prints Certificate was not added to keystore, and still exits with status 0.
3. Import the CA-signed key pair, with its full certificate chain, under a new alias.
  
  Leave the ads-certificate key pair in place. It is also the instance key that the crypto manager uses to unwrap the symmetric keys shared with the topology, and its fingerprint is published under cn=instance keys,cn=admin data.
  
  The key password must be identical to the keystore password, as the server unlocks the private key with the PIN of the ads-truststore:
  $ keytool \ -importkeystore \ -noprompt \ -srckeystore server-cert.p12 \ -srcstoretype PKCS12 \ -srcalias server-cert \ -srcstorepass password \ -destkeystore ads-truststore \ -destalias repl-cert \ -deststorepass `cat ads-truststore.pin` \ -destkeypass `cat ads-truststore.pin`
4. Check that the alias holds a private key entry and that the whole chain was imported.
  
  Use -v: without it, keytool prints the same two lines whether the alias holds the full chain or the server certificate alone. A chain which stops at the server certificate is only rejected by the peers, once this server presents it:
  $ keytool \ -list \ -v \ -alias repl-cert \ -keystore ads-truststore \ -storepass `cat ads-truststore.pin` Alias name: repl-cert Creation date: Sep 1, 2026 Entry type: PrivateKeyEntry Certificate chain length: 2 Certificate[1]: Owner: CN=opendj.example.com Issuer: CN=Example CA ... Certificate[2]: Owner: CN=Example CA Issuer: CN=Example CA ...
  The chain must end with the CA certificate imported in the previous step, Certificate chain length counting the server certificate and every certificate up to your root CA.
5. Start the server:
  $ /path/to/opendj/bin/start-ds

When every server holds the CA certificate and its own CA-signed key pair, take each server in turn and switch it to the new alias.

Configure the crypto manager to present the new certificate.

ssl-cert-nickname is multi-valued, and --set replaces every value it holds. The ads-certificate key pair stays in the ads-truststore, but its alias no longer has to be listed here, as the crypto manager reads its instance key from the ads-certificate alias directly. Where several nicknames are configured, to run certificates with different public key algorithms in parallel, list them all in a single --set:
```
$ dsconfig \
 set-crypto-manager-prop \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --set ssl-cert-nickname:repl-cert \
 --no-prompt
```
The property is declared as requiring a server restart, which dsconfig list-properties shows, and the server writes the change to logs/errors saying that the new value is stored but not in force. That warning also names a nickname the ads-truststore does not hold, so a mistyped alias is caught while the server is still presenting the certificate it started with; if the ads-truststore cannot be read, the warning says so in place of the nicknames it would have named. The warning is repeated on every later change to the crypto manager until the server is restarted, as the value it compares against is the one the server started with.
Restart the server for the change to take effect.

The crypto manager reads ssl-cert-nickname when it starts, and replication keeps the value it read, so the property only takes effect on restart:
```
$ /path/to/opendj/bin/stop-ds --restart
```
Check that replication still works, and that logs/errors shows no SSL handshake failure on the replication port:
```
$ dsreplication \
 status \
 --port 4444 \
 --hostname opendj.example.com \
 --adminUID admin \
 --adminPassword password \
 --no-prompt
```
Move on to the next server only once this one has rejoined the topology. Should it fail to, set ssl-cert-nickname back to the alias it used to present, ads-certificate by default, and restart the server again. The administration connector does not use the ads-truststore, so it stays reachable for dsconfig while the replication port does not work.

The server does not check the host name presented in the replication certificate, so a certificate whose subject does not match the host name of the server is accepted. Expiration dates are enforced, however. Unlike the self-signed ads-certificate, which is generated with a 20 year validity, CA-signed certificates usually have to be renewed: repeat this procedure before they expire.