Secure Connections

Securing connections depends on PKI and asymmetric, public/private key pairs. For details, see Cryptographic Keys.

About Secure Connections

Incoming connections are from clients to the directory. To match port numbers with protocols, see Administrative Access.

Outgoing connections are from the directory to another service.

Recommendations For Incoming Connections
Protocol Recommendations

Administration

DS servers use an Administration Connector for connections from administration tools.

Leave the Administration Connector configured to use SSL/TLS unless you are certain the connections are already secured by some other means.

DSML

DSML support is available through the DS DSML gateway.

Use HTTPS to protect client connections.

HTTP

HTTP connections that are not protected by SSL/TLS use cleartext messages. When you permit insecure connections, you cannot prevent client applications from sending sensitive data. For example, a client could send unprotected credentials in an HTTP Authorization header. Even if the server were to reject the request, the credentials would already be leaked to any eavesdroppers.

HTTP could be allowed instead of HTTPS with anonymous connections if only public information is exposed, and no client applications send credentials or other sensitive information. Configure the HTTP connection handler to use only the default HTTP Anonymous authorization mechanism.

HTTPS

Prefer HTTPS for secure connections over HTTP.

When using an HTTP connection handler, use HTTPS to protect client connections.

Some client applications require a higher level of trust, such as clients with additional privileges or access. Client application deployers might find it easier to manage public keys as credentials than to manage user name/password credentials. Client applications can use SSL client authentication.

When using DS REST to LDAP gateway, use HTTPS to protect client connections.

JMX

Secure JMX access with the SSL/TLS-related properties, such as use-ssl and others.

LDAP

LDAP connections that are not protected by SSL/TLS use cleartext messages. When you permit insecure connections, you cannot prevent client applications from sending sensitive data. For example, a client could send unprotected credentials in an LDAP simple bind request. Even if the server were to reject the request, the credentials would already be leaked to any eavesdroppers.

If all the LDAP applications are under your control, make sure that the only "insecure" requests are anonymous binds, SASL binds, or StartTLS requests.

LDAPS

Prefer LDAPS for secure connections, or make sure that applications use StartTLS after establishing an insecure LDAP connection and before performing other operations.

Some client applications require a higher level of trust, such as clients with additional privileges or access. Client application deployers might find it easier to manage public keys as credentials than to manage user name/password credentials. Client applications can use SSL client authentication. See Certificate-Based Authentication.

Replication

Replication is required in all but a few deployments.

If any of the following are true, replication is required:

  • Client applications require highly available access to critical services, such as authentication and updates.

  • Client applications have specific quality of service requirements.

  • Client applications use the directory service to share common data.

  • Directory service downtime, either planned or unplanned, can lead to lost organizational or business opportunities.

  • Backup operations must be performed while the service is online.

  • Update and upgrade operations must be performed while the service is online.

  • Load sometimes exceeds the service that a single server can provide.

  • Global directory services must be available at more than one location.

Configure replication to use secure connections.

SNMP

Secure SNMP access with settings for security-level and related properties.

SSH

DS administration tools can connect securely.

If the firewall is configured to prevent remote access to the administration connector port, then use a secure third-party tool to access the system remotely. A recommended choice for UNIX and Linux systems is Secure Shell (SSH).

The user account for running directory services should not be the same user account for connecting remotely. Instead, connect as a another user who can then assume the role of the directory services account. The following example demonstrates this approach:

# Log in to ds.example.com:
me@my-laptop $ ssh user@ds.example.com

user@ds.example.com's password:

# Logged in to ds.example.com as user.
Last login: ... from ...

# Run dsconfig interactively as opendj:
user@ds.example.com $ sudo -i -u opendj dsconfig

Secure Copy (SCP) uses SSH to transfer files securely. SCP is an appropriate protocol for copying backup data, for example.

Recommendations For Outgoing Connections
Client Recommendations

Common Audit event handlers

Configure ForgeRock Common Audit event handlers to use HTTPS or TLS when connecting to external log services.

DSML gateway

The DS DSML gateway connects to remote LDAP directory servers. Use LDAP and StartTLS or LDAPS to protect the connections.

OAuth 2.0-based HTTP authorization mechanisms

HTTP authorization can be based on OAuth 2.0, where DS servers act as resource servers, and make requests to resolve OAuth 2.0 tokens.

Use HTTPS to protect the connections to OAuth 2.0 authorization servers.

Pass-Through Authentication

When DS servers use pass-through authentication, they connect to remote LDAP directory servers for authentication.

Use LDAP with StartTLS or LDAPS to protect the connections.

Proxy Requests

A DS directory proxy server can connect to remote directory servers with a bind DN and bind password.

Use LDAP with StartTLS or LDAPS to protect requests to remote directory servers.

Replication

Configure replication to use secure connections.

REST to LDAP gateway

The DS REST to LDAP gateway connects to remote LDAP directory servers. Use LDAP with StartTLS or LDAPS to protect the connections.

SMTP account notification and alert handlers

DS servers can send email account notifications and alerts. Use TLS to protect the connections.

Require HTTPS

You can configure an HTTPS port, and no HTTP port, at setup time, or later, as described below. For details on configuring the DS gateway applications to use HTTPS, see your web container documentation.

Set the HTTPS Port

At setup time use the --httpsPort option.

Later, follow these steps to set up an HTTPS port:

  1. Create an HTTPS connection handler.

    The following example sets the port to 8443 and uses the default server certificate:

    $ dsconfig \
     create-connection-handler \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --handler-name HTTPS \
     --type http \
     --set enabled:true \
     --set listen-port:8443 \
     --set use-ssl:true \
     --set key-manager-provider:PKCS12 \
     --set trust-manager-provider:"JVM Trust Manager" \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt
  2. Enable the HTTP access log.

    1. The following command enables JSON-based HTTP access logging:

      $ dsconfig \
       set-log-publisher-prop \
       --hostname localhost \
       --port 4444 \
       --bindDN uid=admin \
       --bindPassword password \
       --publisher-name "Json File-Based HTTP Access Logger" \
       --set enabled:true \
       --no-prompt \
       --usePkcs12TrustStore /path/to/opendj/config/keystore \
       --trustStorePassword:file /path/to/opendj/config/keystore.pin
    2. The following command enables HTTP access logging:

      $ dsconfig \
       set-log-publisher-prop \
       --hostname localhost \
       --port 4444 \
       --bindDN uid=admin \
       --bindPassword password \
       --publisher-name "File-Based HTTP Access Logger" \
       --set enabled:true \
       --no-prompt \
       --usePkcs12TrustStore /path/to/opendj/config/keystore \
       --trustStorePassword:file /path/to/opendj/config/keystore.pin
  3. If the deployment requires SSL client authentication, set the properties ssl-client-auth-policy and trust-manager-provider appropriately.

  4. After you set up an HTTPS port, enable an HTTP endpoint.

Require LDAPS

You can configure an LDAPS port, and no LDAP port, at setup time, or later, as described below.

Set the LDAPS port

At setup time use the --ldappsPort option.

Later, follow these steps to set up an LDAPS port:

  1. Configure the server to activate LDAPS access:

    $ dsconfig \
     set-connection-handler-prop \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --handler-name LDAPS \
     --set enabled:true \
     --set listen-port:1636 \
     --set use-ssl:true \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt
  2. If the deployment requires SSL client authentication, set the ssl-client-auth-policy and trust-manager-provider properties appropriately.

Disable LDAP

Configure the server to disable insecure LDAP access:

$ dsconfig \
 set-connection-handler-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --handler-name LDAP \
 --set enabled:false \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

Message-Level Security

Server protocols like LDAP, HTTP, JMX, and replication rely on transport layer security to protect connections. Configure connection handlers for TLS or StartTLS, and use access control to enforce secure communications.

  • For directory servers, see ssf in ACI Subjects. Set the security strength factor to achieve a balance; for example, with 128 or 256. If set too low, the server and client can negotiate a connection that is not secure. If set too high, some clients might not be able to connect.

  • For directory proxy servers, use a connection-minimum-ssf setting that enforces use of transport layer security, such as 128 or 256.

When negotiating connection security, the server and client must use a common security protocol and cipher suite. To update the security protocols and cipher suites, see TLS Settings.

Transport Layer Security

When a client and server set up an HTTPS or LDAPS connection, they use a protocol to establish the security. They then encapsulate HTTP or LDAP messages in the secure protocol. The process depends on digital certificates. The process uses client certificates differently for mutual authentication and for SASL EXTERNAL binds.

A connection that uses TLS, a protocol based on the SSL protocol, is a connection that is private and reliable. Communications on the connection are kept private by being encrypted with a symmetric key for the session that only the client and server know. Communications are reliable because their integrity is checked with a message authentication code (MAC).

The TLS protocol is independent of the application protocol. TLS encapsulates application level protocols like HTTP and LDAP. The client and server negotiate the secure connection before any messages are sent using the application protocol.

When a client and server set up a secure connection, they negotiate a session with the TLS handshake protocol. During the handshake the server and client use asymmetric keys, their public key certificates and associated private keys, to authenticate (prove their identities).

The default configuration for DS servers sends the server certificate during the handshake. The client is not required to send its certificate. This lets the client authenticate the server when negotiating security. It does not let the server authenticate the client at this stage. This avoids requiring clients, such as browsers, to manage keys and certificate signatures.

For client applications that are part of the software infrastructure, rather than end user applications, managing keys and certificate signatures can be a better choice than managing passwords. Such clients present their certificates during the handshake, letting the server authenticate the client. When both the server and client present certificates during the handshake, this is known as mutual authentication.

In TLS v1.2, for example, a successful initial handshake has the client and server do the following:

  1. Exchange supported algorithms and random values.

  2. Exchange cryptographic information to agree on an initial secret.

  3. Exchange certificates and cryptographic information to permit authentication.

  4. Generate a symmetric key for the sessions with the initial secret and the random values exchanged.

  5. Set the security parameters for the session.

  6. Verify that each party uses the same security parameters, and that the handshake was not tampered with.

The handshake completes before any HTTP or LDAP messages are sent over the connection. HTTP authentications and LDAP binds happen after the secure connection has been established.

DS support for TLS relies on the Java implementation. DS support for LDAP authentication is part of the DS server. This is an important distinction:

  • When a client application presents its certificate for TLS mutual authentication, the JVM checks the certificate independently of the client application’s directory entry.

    When securing the transport layer with mutual authentication, the client certificate must be trusted.

  • When the client application binds to the DS server with its certificate, the server checks that the certificate presented matches the certificate stored in the client’s directory entry. A certificate mapper finds the directory entry based on the client certificate.

Client Certificate Validation

A first step in establishing a secure connection involves validating the certificate presented by the other party. Part of this is trusting the certificate. The certificate identifies the client or server and the signing certificate. The validating party checks that the other party corresponds to the one identified by the certificate, and checks that the signature can be trusted. If the signature is valid, and the signing certificate is trusted, then the certificate can be trusted.

Certificates can be revoked after they are signed. Therefore, the validation process can involve checking whether the certificate is still valid. This can be done with the Online Certificate Status Protocol (OCSP) or Certificate Revocation Lists (CRLs). OCSP is a newer solution that provides an online service to handle the revocation check for a specific certificate. CRLs are potentially large lists of user certificates that are no longer valid or that are on hold. A CRL is signed by the CA. The validating party obtains the CRL and checks that the certificate being validated is not listed. For a brief comparison, see OCSP: Comparison to CRLs. A certificate can include links to contact the OCSP responder or to the CRL distribution point. The validating party can use these links to check whether the certificate is still valid.

In both cases, the CA who signed the certificate acts as the OCSP responder or publishes the CRLs. When establishing a secure connection with a client application, the server relies on the CA for OCSP and CRLs. This is the case even when the DS server is the repository for the CRLs.

DS directory services are logical repositories for certificates and CRLs. For example, DS servers can store CRLs in a certificateRevocationList attribute:

dn: cn=My CA,dc=example,dc=com
objectClass: top
objectClass: applicationProcess
objectClass: certificationAuthority
cn: My CA
authorityRevocationList;binary: Base64-encoded ARL
cACertificate;binary:: Base64-encoded CA certificate
certificateRevocationList;binary:: Base64-encoded CRL

Replicate the CRL for high availability. (The ARL in the entry is like a CRL, but for CA certificates.)

Despite being a repository for CRLs, the DS server does check client certificates with its CRLs directly. Instead, when negotiating a secure connection, the server depends on the JVM security configuration. The JVM configuration governs whether validation uses OCSP, CRLs, or both. The JVM relies on system properties that define whether to use the CRL distribution points defined in certificates, and how to handle OCSP requests. These system properties can be set system-wide in $JAVA_HOME/lib/security/java.security. The JVM handles revocation checking without the DS server’s involvement. For details, see Support for the CRL Distribution Points Extension, and Appendix C: On-Line Certificate Status Protocol (OCSP) Support in the Java PKI Programmer’s Guide.

After a connection is negotiated, the client can bind with its certificate using SASL EXTERNAL authentication. For details, see Certificate-Based Authentication.

OCSP and obtaining CRLs depend on network access to the CA. If DS servers or the DSML or REST to LDAP gateways run on a network where the CA is not accessible, and the deployment requires OSCP or checking CRLs for client application certificates, then you must provide some alternative means to handle OCSP or CRL requests. Configure the JVM to use a locally available OCSP responder, for example. If the solution depends on CRLs, regularly update the CRLs in the directory with downloaded copies of the CA CRLs.

Restrict Client Access

Use a server’s global configuration properties, to restrict how clients access the server. These global configuration settings are per server, and are not replicated:

bind-with-dn-requires-password

Whether the server rejects simple bind requests containing a DN but no password.

Default: true

To change this setting use the following command:

$ dsconfig \
 set-global-configuration-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --set bind-with-dn-requires-password:false \
 --no-prompt \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin
max-allowed-client-connections

Restricts the number of concurrent client connections to this server.

Default: 0, meaning no limit is set.

To set a limit of 64K use the following command:

$ dsconfig \
 set-global-configuration-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --set max-allowed-client-connections:65536 \
 --no-prompt \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin
allowed-client

Restrict which clients can connect to the server.

restricted-client

Restrict the number of concurrent connections per client.

unauthenticated-requests-policy

This setting can take the following values:

reject

Reject requests (other than bind or StartTLS requests) received from a client:

  • Who has not yet authenticated.

  • Whose last authentication was unsuccessful.

  • Whose last authentication attempt used anonymous authentication.

allow-discovery

Like reject, but allows unauthenticated base object searches of the root DSE.

This setting supports applications that read the root DSE to discover server capabilities, and applications that target the root DSE for keep-alive heartbeats.

allow (default)

Allow all unauthenticated requests, subject to privileges and access control.

Although this is the default setting, all setup profiles except ds-evaluation use allow-discovery.

To allow anonymous binds, use the following command:

$ dsconfig \
 set-global-configuration-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --set unauthenticated-requests-policy:allow \
 --no-prompt \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin
return-bind-error-messages

Does not restrict access, but prevents a server from returning extra information about why a bind failed, as that information could be used by an attacker. Instead, the information is written to the server errors log.

Default: false.

To have the server return additional information about why a bind failed, use the following command:

$ dsconfig \
 set-global-configuration-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --set return-bind-error-messages:true \
 --no-prompt \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin

TLS Settings

To negotiate a secure connection, the server and client must agree on a common protocol and cipher suite. Otherwise, they fail to establish a secure connection.

By default, DS servers use only security protocols and cipher suites considered secure at the time of release. DS servers do, however, support all the security protocols and cipher suites provided by the JVM. For details, see the documentation for the JVM, such as the JDK Providers Documentation for the The SunJSSE Provider.

Researchers continue to find vulnerabilities in protocols and cipher suites. If a server supports vulnerable protocols or cipher suites, clients can use them. Attackers can then exploit the vulnerabilities. You might therefore need to restrict the list of accepted protocols and cipher suites at any time.

List Protocols and Cipher Suites

  1. To list the protocols and cipher suites that DS servers accept, read the root DSE attributes, supportedTLSProtocols and supportedTLSCiphers:

    $ ldapsearch \
     --hostname localhost \
     --port 1636 \
     --useSsl \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --baseDN "" \
     --searchScope base \
     "(objectclass=*)" \
     supportedTLSCiphers supportedTLSProtocols

    A supportedTLSCiphers name, such as TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 for use with TLSv1.2, identifies the key attributes of the cipher suite:

    TLS

    Specifies the protocol, in this case TLS.

    ECDHE_RSA

    Specifies the key exchange algorithm used to determine how the client and server authenticate during the handshake phase.

    The algorithm in this example uses an elliptic curve variant of the Diffie-Hellman key exchange. In ECDHE_RSA, the server signs the ephemeral ECDH public key in the ServerKeyExchange message with its RSA private key.

    Ideally the server certificate would have a KeyUsage extension with only the digitalSignature bit set to prevent it being used for encryption.

    WITH_AES_256_GCM

    Specifies the bulk encryption algorithm, including the key size or initialization vectors.

    This example specifies the Advanced Encryption Standard (AES) with 256-bit key size and Galois/Counter Mode (GCM) block cipher mode.

    SHA384

    Specifies the message authentication code algorithm used to create the message digest, which is a cryptographic hash of each block in the message stream.

    In this example, the SHA-2 hash function, SHA-384, is used.

    A supportedTLSProtocols name identifies the protocol and version, such as TLSv1.2 or TLSv1.3.

Cipher suites compatible with TLSv1.3 do not include the key exchange algorithm. In TLSv1.3, the signature algorithm and key exchange are negotiated separately.

Restrict Protocols and Cipher Suites

You can limit the protocols and cipher suites that DS servers accept by setting the properties, ssl-protocol and ssl-cipher-suite on the appropriate components.

This following settings derive from the server-side TLS recommendations published by the Mozilla Operations Security team at the time of this writing. Recommendations evolve. Make sure you use current recommendations when configuring security settings:

  1. For each cipher suite key algorithm to support, create a key pair using the supported key algorithm.

    The following example adds a key pair to the default PKCS#12 keystore:

    $ keytool \
     -genkeypair \
     -alias ssl-key-pair-ec \
     -keyalg EC \
     -ext "san=dns:ds.example.com" \
     -dname "CN=ds.example.com,O=Example Corp,C=FR" \
     -keystore /path/to/opendj/config/keystore \
     -storetype PKCS12 \
     -storepass:file /path/to/opendj/config/keystore.pin \
     -keypass:file /path/to/opendj/config/keystore.pin
  2. On the components you use, explicitly set the supported protocols and cipher suites.

    The following example adjusts settings for the LDAP and LDAPS connection handlers:

    $ dsconfig \
     set-connection-handler-prop \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --handler-name LDAP \
     --add ssl-protocol:TLSv1.3 \
     --add ssl-cipher-suite:TLS_AES_128_GCM_SHA256 \
     --add ssl-cipher-suite:TLS_AES_256_GCM_SHA384 \
     --no-prompt \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin
    
    $ dsconfig \
     set-connection-handler-prop \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --handler-name LDAPS \
     --add ssl-protocol:TLSv1.3 \
     --add ssl-cipher-suite:TLS_AES_128_GCM_SHA256 \
     --add ssl-cipher-suite:TLS_AES_256_GCM_SHA384 \
     --no-prompt \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin
  3. Use the appropriate settings for your connection handlers:

    $ dsconfig \
     set-connection-handler-prop \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --handler-name LDAP \
     --set enabled:true \
     --set listen-port:1389 \
     --set allow-start-tls:true \
     --set key-manager-provider:PKCS12 \
     --set trust-manager-provider:PKCS12 \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt
    
    $ dsconfig \
     set-connection-handler-prop \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --handler-name LDAPS \
     --set listen-port:1636 \
     --set enabled:true \
     --set use-ssl:true \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt

Restrict Protocols For Command-Line Tools

You can specify which protocol versions to allow when command-line tools negotiate secure connections with LDAP servers.

The command-line tools depend on a system property, org.opends.ldaps.protocols. This property takes a comma-separated list of protocols. The default is constructed from the list of all protocols the JVM supports, removing protocol names starting with SSL. For example, if support is enabled in the JVM for versions 1.0, 1.1, and 1.2 of the TLS protocol, then the default is "TLSv1,TLSv1.1,TLSv1.2".

  1. Restrict the protocols to use by setting the property in one of the following ways:

    1. Set the property by editing the java-args for the command in config/java.properties .

      For example, to restrict the protocol to TLS v1.2 when the status command negotiates a secure administrative connection, edit the corresponding line in config/java.properties:

      status.java-args=-Xms8m -client -Dorg.opends.ldaps.protocols=TLSv1.2
    2. Set the property at runtime when running the command.

      The following example restricts the protocol to TLS v1.2 when the status command negotiates a secure administrative connection:

      $ export OPENDJ_JAVA_ARGS="-Dorg.opends.ldaps.protocols=TLSv1.2"
      
      $ status \
       --bindDn uid=admin \
       --bindPassword password \
       --hostname localhost \
       --port 4444 \
       --usePkcs12TrustStore /path/to/opendj/config/keystore \
       --trustStorePassword:file /path/to/opendj/config/keystore.pin