How do I install a CA-signed certificate for use in DS 7.x?

Overview

The following process demonstrates how you can replace the default generated ssl-key-pair with your own CA-signed certificate. The actual process may vary according to your CA and whether intermediate certificates are involved in the certificate chain. For example, they may also issue an intermediate certificate, which will need importing into the keystore along with the root certificate.

This process uses the following example values; you should substitute your values accordingly:

• The CA-signed certificate alias is: my-tls-server-cert
• The CA's root certificate alias is: root-ca-cert with a corresponding certificate: root-ca-cert.cer
• The default keystore is being used, which contains the standard ca-cert, master-key and ssl-key-pair entries, for example:$ keytool -list -keystore keystore -storepass:env KEYSTORE_PASSWORD Keystore type: PKCS12 Keystore provider: SUN Your keystore contains 3 entries ca-cert, Oct 28, 2022, trustedCertEntry, Certificate fingerprint (SHA-256): 93:5C:BC:1E:23:47:DC:54:53:DA:4E:97:BB:4D:15:1D:FD:DF:61:2F:AC:21:00:7C:39:74:A4:ED:98:96:85:2D master-key, Oct 28, 2022, PrivateKeyEntry,  Certificate fingerprint (SHA-256): 74:63:F1:45:5E:22:02:83:21:82:F1:66:3A:AC:77:19:46:99:15:FF:A1:F3:4B:DC:B1:58:E5:F8:5D:1E:64:80 ssl-key-pair, Oct 28, 2022, PrivateKeyEntry,  Certificate fingerprint (SHA-256): E8:EC:B0:FF:DE:C7:0C:D2:FB:A6:DA:7C:E5:8F:B8:01:6F:FC:DC:29:1B:0E:C8:EC:F6:89:D8:03:11:9E:31:86

Generating a CA-signed certificate

1. Generate a new private key pair, for example:$ keytool -genkeypair -alias my-tls-server-cert -keyalg rsa -dname "CN=ds.example.com,O=Example Corp,C=FR" -keystore keystore -storepass:env KEYSTORE_PASSWORD -keypass:env KEYSTORE_PASSWORD
2. Generate the certificate signing request (CSR), for example:$ keytool -certreq -alias my-tls-server-cert -keystore keystore -storepass:env KEYSTORE_PASSWORD -keypass:env KEYSTORE_PASSWORD -file my-tls-server-cert.csrYou can check the generated file contains the CSR if required, for example:$ cat my-tls-server-cert.csr -----BEGIN NEW CERTIFICATE REQUEST----- MIIC9DCCAdwCAQAwfzELMAkGA1UEBhMCVVMxETAPBgNVBAgTCENvbG9yYWRvMRQw EgYDVQQHEwtXZXN0bWluc3RlcjEaMBgGA1UEChMRdGVjaG5pY2FsIHN1cHBvcnQx KzApBgNVBAMTIlZpbmNlbnRzLU1hY0Jvb2stUHJvLmZvcmdlcm9jay5jb20wggEi MA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCITnkmPsbI8MBOM+yd9ttveLSc vVVlbkkPnBg6UnpO7c/bY8OQpgCGv2WbZW7z+Ol2r1GspSfwLOz6UaiYWNek2/s0 3hmpFO9t/cOqZ0n93OQk3lAc6bYpYpP2hMpJqUfcI/X5m3D7esyDKY6j1rfL4gnE KJl7Q5ST+qdEdqM3k6eUvqts/Sb9Sc62DgNHhy+T13/EoqKe9GzumbQ8Xlx6Lkwy dReDWgblJS5w6tMd5qZFAsnZmvJ2TSygk+nKFu20SN1OQD5iFUUrlm6KLd1dOT8S oYjScMd4Bv9CXCPIedWoSkbpwwrqIyPeI9WcD+VS8UtgeVxchfwCt5QU/LJ5AgMB AAGgMDAuBgkqhkiG9w0BCQ4xITAfMB0GA1UdDgQWBBT5vDi1ASptV8VeByiAE/Nk 52sEwDANBgkqhkiG9w0BAQsFAAOCAQEAfK7c++26aI6KsDhEni70RuhyEKBAQ6nZ xnV2WPuAiiIauvHDr7C6iplzur+rTqN2bCXS+FxesCIEUIsiTQqTbuTNfBfVhEgo RgYE1pOeMeFRRBoitMeRzEADuvusQH3y2j21JQHmWLZ34XYb//HRfktcXj4tefmn 1whTturhSDEiqPKbs8Klwl56ESACIWZDOMCIOtqI5pbnHW+5xbxJhYEZqeJ7njUN lgXixBBKRduE4OcCmT+pQ6yc189a14pJ7vz+FZ254NwHv1jhYZ3LDiBwPJTMA7ea uVXwlmVbJiYogLv8zo/PtCHDGIyFMydwoJBTMrSnRNLiVysw470KXg== -----END NEW CERTIFICATE REQUEST-----
3. Submit the CSR to the CA for signing. They will issue a CA-signed server certificate.

Installing the CA-signed certificate

The following steps assume that the CA-signed server certificate was issued directly from the CA's root certificate. If there are intermediate certificates involved in the certificate chain, then these will also need to be installed and trusted in the keystore. Instructions for obtaining the CA root certificate and any intermediate certificates should be provided by the signing CA.

1. Import the CA's root certificate into the keystore, for example:$ keytool -importcert -alias root-ca-cert -file root-ca-cert.cer -keystore keystore -storepass:env KEYSTORE_PASSWORD
2. Import the CA-signed server certificate into the keystore, for example:$ keytool -importcert -alias my-tls-server-cert -file my-tls-server-cert.cer -keystore keystore -storepass:env KEYSTORE_PASSWORD
3. List the contents of your keystore to verify the new certificates have been added, for example:$ keytool -list -keystore keystore -storepass:env KEYSTORE_PASSWORD Keystore type: PKCS12 Keystore provider: SUN Your keystore contains 5 entries ca-cert, Oct 28, 2022, trustedCertEntry, Certificate fingerprint (SHA-256): 93:5C:BC:1E:23:47:DC:54:53:DA:4E:97:BB:4D:15:1D:FD:DF:61:2F:AC:21:00:7C:39:74:A4:ED:98:96:85:2D master-key, Oct 28, 2022, PrivateKeyEntry,  Certificate fingerprint (SHA-256): 74:63:F1:45:5E:22:02:83:21:82:F1:66:3A:AC:77:19:46:99:15:FF:A1:F3:4B:DC:B1:58:E5:F8:5D:1E:64:80 my-tls-server-cert, Oct 31, 2022, PrivateKeyEntry,  Certificate fingerprint (SHA-256): B0:EC:00:FF:B8:85:32:C6:60:6A:E4:B7:69:65:22:69:FB:65:92:E8:0F:23:0F:B4:23:58:AB:34:9F:73:F4:23 root-ca-cert, Oct 31, 2022, trustedCertEntry,  Certificate fingerprint (SHA-256): BA:A5:72:72:61:7A:34:67:45:13:EE:14:E4:10:6D:14:72:70:DC:98:4F:90:B4:A6:C6:2E:2A:0C:25:DB:D3:5D ssl-key-pair, Oct 28, 2022, PrivateKeyEntry,  Certificate fingerprint (SHA-256): E8:EC:B0:FF:DE:C7:0C:D2:FB:A6:DA:7C:E5:8F:B8:01:6F:FC:DC:29:1B:0E:C8:EC:F6:89:D8:03:11:9E:31:86
4. Restart DS to ensure the new keystore contents are reloaded correctly, for example:$ ./stop-ds $ ./start-ds

Using the CA-signed certificate

Your CA-signed certificate (my-tls-server-cert in this example) is now ready to use in DS. The following examples demonstrate using it for the LDAPS connection handler and replication port, but you can use it for other connection handlers as well.

LDAPS connection handler example

You can configure the LDAPS connection handler to use the new CA-signed certificate using dsconfig, for example:

• DS 7.1 and later: $ ./dsconfig set-connection-handler-prop --hostname ds.example.com --port 4444 --bindDN uid=admin --bindPassword password --handler-name LDAPS --set ssl-cert-nickname:my-tls-server-cert --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
• DS 7: $ ./dsconfig set-connection-handler-prop --hostname ds.example.com --port 4444 --bindDN uid=admin --bindPassword password --handler-name LDAPS --set ssl-cert-nickname:my-tls-server-cert --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt

You must disable and re-enable the handler to apply this change.

See LDAP Connection Handler for further information.

Replication port example

You can configure the replication port to use the new CA-signed certificate using dsconfig, for example:

• DS 7.1 and later: $ ./dsconfig set-synchronization-provider-prop --provider-name "Multimaster Synchronization" --hostname ds.example.com --port 4444 --bindDN uid=admin --bindPassword password --set ssl-cert-nickname:my-tls-server-cert --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
• DS 7: $ ./dsconfig set-synchronization-provider-prop --provider-name "Multimaster Synchronization" --hostname ds.example.com --port 4444 --bindDN uid=admin --bindPassword password --set ssl-cert-nickname:my-tls-server-cert --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt

You must restart DS to apply this change.

See Replication Synchronization Provider Properties for further information.

See Also

Key management

Generate a key pair (CA-signed certificate)

Trust a CA certificate

Cryptographic keys

Related Training

N/A

Related Issue Tracker IDs

N/A