4.2. Preparing For Secure Communications

One common way to protect connections between OpenDJ and client applications involves using StartTLS for LDAP or LDAPS to secure connections. OpenDJ and client applications use X.509 digital certificates to set up secure connections.

Both OpenDJ and client applications check that certificates are signed by a trusted party before accepting them. Merely setting up a secure connection therefore involves a sort of authentication using certificates. If either OpenDJ or the client application cannot trust the peer certificate, then the attempt to set up a secure connection must fail.

By default OpenDJ client tools prompt you if they do not recognize the server certificate. Other clients might not prompt you. OpenDJ server has no one to prompt when a client presents a certificate that cannot be trusted, so it must simply refuse to set up the connection.[1] In other words, it is important for both OpenDJ and client applications to be able to verify that peer certificates exchanged have been signed by a trusted party.

In practice this means that both OpenDJ and client applications must put the certificates that were used to sign each others' certificates in their respective trust stores. Conventionally, certificates are therefore signed by a Certificate Authority (CA). A CA is trusted to sign other certificates. The Java runtime environment for example comes with a trust store holding certificates from many well-known CAs.[2] If your client uses a valid certificate signed by one of these CAs, then OpenDJ can verify the certificate without additional configuration, because OpenDJ can find the CA certificate in the Java CA certificate trust store. Likewise if you set up StartTLS or LDAPS in OpenDJ using a valid certificate signed by one of these CAs, then many client applications can verify the OpenDJ server certificate without further configuration.

In summary, if you need a certificate to be recognized automatically, get the certificate signed by a well-known CA.

You can, however, choose to have your certificates signed some other way. You can set up your own CA. You can use a CA whose signing certificate is not widely distributed. You can also use self-signed certificates. In each case, you must add the signing certificates into the trust store of each peer making secure connections.

For OpenDJ directory server, you can choose to import your own CA-signed certificate as part of the installation process, or later using command-line tools. Alternatively, you can let the OpenDJ installation program create a self-signed certificate as part of the OpenDJ installation process. In addition, you can add a signing certificate to the OpenDJ trust store using the Java keytool command.

The following example shows the keytool command to add a client application's binary format, self-signed certificate to the OpenDJ trust store (assuming OpenDJ is already configured to use secure connections). This enables OpenDJ to recognize the self-signed client application certificate. (By definition a self-signed certificate is itself the signing certificate. Notice that the Owner and the Issuer are the same.) 

$ keytool
 -import
 -alias myapp-cert
 -file myapp-cert.crt
 -keystore /path/to/opendj/config/truststore
 -storepass `cat /path/to/opendj/config/keystore.pin`
Owner: CN=My App, OU=Apps, DC=example, DC=com
Issuer: CN=My App, OU=Apps, DC=example, DC=com
Serial number: 5ae2277
Valid from: Fri Jan 18 18:27:09 CET 2013 until: Thu Jan 13 18:27:09 CET 2033
Certificate fingerprints:
	 MD5:  48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37
	 SHA1: F9:61:54:37:AA:C1:BC:92:45:07:64:4B:23:6C:BC:C9:CD:1D:44:0F
	 SHA256: 2D:B1:58:CD:33:40:E9:ED:...:EA:C9:FF:6A:19:93:FE:E4:84:E3
	 Signature algorithm name: SHA256withRSA
	 Version: 3

Extensions:

#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 54 C0 C5 9C 73 37 85 4B   F2 3B D3 37 FD 45 0A AB  T...s7.K.;.7.E..
0010: C9 6B 32 95                                        .k2.
]
]

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

When working with a certificate in printable encoding format (.pem) rather than binary format, use the -rfc option, too.

Restart OpenDJ after adding certificates to the trust store to make sure that OpenDJ reads the updated trust store file.

On the client side, if your applications are also Java applications, then you can also import the OpenDJ signing certificate into the trust store for the applications using the keytool command.

The following example shows the keytool command to export the OpenDJ self-signed certificate in binary format. 

$ keytool
 -export
 -alias server-cert
 -file server-cert.crt
 -keystore /path/to/opendj/config/keystore
 -storepass `cat /path/to/opendj/config/keystore.pin`
Certificate stored in file <server-cert.crt>

Importing the server certificate is similar to importing the client certificate, as shown above.

The following sections describe how to get and install certificates for OpenDJ directory server on the command line, for use when setting up StartTLS or LDAPS.

Procedure 4.2. To Request and Install a CA-Signed Certificate

First you create a server certificate in a Java Key Store. Next you issue a signing request to the CA, and get the CA-signed certificate as a reply. Then you set up the Key Manager Provider and Trust Manager Provider to rely on your new server certificate stored in the OpenDJ key store.

  1. Generate the server certificate by using the Java keytool command.

    The CN attribute value is the FQDN for OpenDJ directory server, which you can see under Server Details in the OpenDJ Control Panel. 

    $ keytool
 -genkey
 -alias server-cert
 -keyalg rsa
 -dname "CN=opendj.example.com,O=Example Corp,C=FR"
 -keystore /path/to/opendj/config/keystore
 -storepass changeit
 -keypass changeit
    [Note] Note

    Notice that the -storepass and -keypass options take identical password arguments. OpenDJ requires that you use the same password to protect both the keystore and also the private key.

  2. Create a certificate signing request file for the certificate you generated. 

    $ keytool
 -certreq
 -alias server-cert
 -keystore /path/to/opendj/config/keystore
 -storepass changeit
 -file server-cert.csr

  3. Have the CA sign the request (server-cert.csr).

    See the instructions from your CA on how to provide the request.

    The CA returns the signed certificate.

  4. If you have set up your own CA and signed the certificate, or are using a CA whose signing certificate is not included in the Java runtime environment, import the CA certificate into the key store so that it can be trusted.

    Otherwise, when you import the signed certificate in the reply from the (unknown) CA, keytool fails to import the signed certificate with the message keytool error: java.lang.Exception: Failed to establish chain from reply.

    The following example illustrates import of a CA certificate created with the openssl command. See the openssl documentation for instructions on creating CAs and on signing other certificates with the CA you created. 

    $ keytool
 -import
 -keystore /path/to/opendj/config/keystore
 -file ca.crt
 -alias ca-cert
 -storepass changeit
Owner: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR
Issuer: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR
Serial number: d4586ea05c878b0c
Valid from: Tue Jan 29 09:30:31 CET 2013 until: Mon Jan 24 09:30:31 CET 2033
Certificate fingerprints:
	 MD5:  8A:83:61:9B:E7:18:A2:21:CE:92:94:96:59:68:60:FA
	 SHA1: 01:99:18:38:3A:57:D7:92:7B:D6:03:8C:7B:E4:1D:37:45:0E:29:DA
	 SHA256: 5D:20:F1:86:CC:CD:64:50:...:DF:15:43:07:69:44:00:FB:36:CF
	 Signature algorithm name: SHA1withRSA
	 Version: 3

Extensions:

#1: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
KeyIdentifier [
0000: 30 07 67 7D 1F 09 B6 E6   90 85 95 58 94 37 FD 31  0.g........X.7.1
0010: 03 D4 56 7B                                        ..V.
]
[EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR]
SerialNumber: [    d4586ea0 5c878b0c]
]

#2: ObjectId: 2.5.29.19 Criticality=false
BasicConstraints:[
  CA:true
  PathLen:2147483647
]

#3: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 30 07 67 7D 1F 09 B6 E6   90 85 95 58 94 37 FD 31  0.g........X.7.1
0010: 03 D4 56 7B                                        ..V.
]
]

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

  5. Import the signed certificate from the CA reply into the keystore where you generated the server certificate.

    In this example the certificate from the reply is ~/Downloads/server-cert.crt. 

    $ keytool
 -import
 -trustcacerts
 -alias server-cert
 -file ~/Downloads/server-cert.crt
 -keystore /path/to/opendj/config/keystore
 -storepass changeit
 -keypass changeit
Certificate reply was installed in keystore

  6. Configure the File Based Key Manager Provider for JKS to use the file name and key store PIN that you set up with the keytool command. 

    $ dsconfig
 set-key-manager-provider-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --provider-name JKS
 --set enabled:true
 --set key-store-pin:changeit
 --remove key-store-pin-file:config/keystore.pin
 --trustAll
 --no-prompt

  7. Configure the File Based Trust Manager Provider for JKS to use the key store and PIN as well. 

    $ dsconfig
 set-trust-manager-provider-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --provider-name JKS
 --set enabled:true
 --set trust-store-file:config/keystore
 --set trust-store-pin:changeit
 --trustAll
 --no-prompt

    At this point, OpenDJ directory server can use your new CA-signed certificate, for example for StartTLS and LDAPS connection handlers.

  8. If you use a CA certificate that is not known to clients, such as a CA that you set up yourself rather than a well-known CA whose certificate is included with the client system, import the CA certificate into the client application trust store. Otherwise the client application cannot trust the signature on the OpenDJ CA-signed server certificate.

Procedure 4.3. To Create & Install a Self-Signed Certificate

If you choose to configure LDAP Secure Access when setting up OpenDJ directory server, the setup program generates a key pair in the Java Key Store /path/to/opendj/config/keystore, and self-signs the public key certificate, which has the alias server-cert. The password for the key store and the private key is stored in clear text in the file /path/to/opendj/config/keystore.pin.

If you want to secure communications, but chose not to configure LDAP Secure Access at setup time, this procedure can help. The following steps explain how to create and install a key pair with a self-signed certificate in preparation to configure LDAPS or HTTPS. First you create a key pair in a new Java Key Store, and then self-sign the certificate. Next, you set up the Key Manager Provider and Trust Manager Provider to access the new server certificate in the new key store.

If instead you want to replace the existing server key pair with self-signed certificate, then first use keytool -delete -alias server-cert to delete the existing keys before you generate a new key pair with the same alias. You can also either reuse the existing password in keystore.pin, or use a new password as shown in the steps below.

  1. Generate the server certificate using the Java keytool command. 

    $ keytool
 -genkey
 -alias server-cert
 -keyalg rsa
 -dname "CN=opendj.example.com,O=Example Corp,C=FR"
 -keystore /path/to/opendj/config/keystore
 -storepass changeit
 -keypass changeit

    In this example, OpenDJ is running on a system with fully qualified host name opendj.example.com. The Java Key Store (JKS) is created in the config directory where OpenDJ is installed, which is the default value for JKS.

    [Note] Note

    Notice that the -storepass and -keypass options take identical password arguments. OpenDJ requires that you use the same password to protect both the key store and also the private key.

    Keep track of the password provided to the -storepass and -keypass options.

  2. Self-sign the server certificate.

    $ keytool
 -selfcert
 -alias server-cert
 -keystore /path/to/opendj/config/keystore
 -storepass changeit

  3. Configure the File Based Key Manager Provider for JKS to access the Java Key Store with key store/private key password.

    In this example, the alias is server-cert and the password is changeit.

    If you are replacing a key pair with a self-signed certificate, reusing the server-cert alias and password stored in keystore.pin, then you can skip this step. 

    $ echo changeit > /path/to/opendj/config/keystore.pin
$ chmod 600 /path/to/opendj/config/keystore.pin
$ dsconfig
 set-key-manager-provider-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --provider-name JKS
 --set enabled:true
 --set key-store-file:config/keystore
 --set key-store-pin-file:config/keystore.pin
 --trustAll
 --no-prompt

  4. Configure the File Based Trust Manager Provider for JKS to use the key store and PIN as well.

    If you skipped the previous step, you can also skip this step.

    $ dsconfig
 set-trust-manager-provider-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --provider-name JKS
 --set enabled:true
 --set trust-store-file:config/keystore
 --set trust-store-pin-file:config/keystore.pin
 --trustAll
 --no-prompt

    At this point, OpenDJ directory server can use your new self-signed certificate, for example for StartTLS and LDAPS or HTTPS connection handlers.


[1] Unless you use the Blind Trust Manager Provider, which is recommended only for test purposes.

[2] $JAVA_HOME/jre/lib/security/cacerts holds the CA certificates. To read the full list, use the following command. 

$ keytool
 -list
 -v
 -keystore $JAVA_HOME/jre/lib/security/cacerts
 -storepass changeit