Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle Unified Directory
11g Release 2 (11.1.2)

Part Number E22648-05
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

20 Configuring Security Between Clients and Servers

Oracle Unified Directory provides several mechanisms to secure traffic between the client and the server. The topics in this section describe these mechanisms, and how to configure them.

For information about securing access to directory data, see Chapter 22, "Controlling Access To Data".

For information about configuring security between the proxy and the directory server or data source, see Chapter 21, "Configuring Security Between the Proxy and the Data Source".

This chapter covers the following topics:

20.1 Getting SSL Up and Running Quickly

Oracle Unified Directory provides a number of options for configuring and using SSL and StartTLS. The numerous possibilities for configuration might be daunting for those who are unfamiliar with the technology or who just want to get up and running as quickly as possible for testing purposes.

This section provides a list of the steps that must be performed to allow Oracle Unified Directory to accept SSL-based connections using a self-signed certificate.

The procedures in this section assume a knowledge of truststores and keystores. For detailed information about keystores, see Section 20.2, "Configuring Key Manager Providers". For detailed information about truststores, see Section 20.3, "Configuring Trust Manager Providers".

Note:

Using a self-signed certificate is not recommended for production purposes. To install a certificate for production purposes, follow the instructions in Section 20.2, "Configuring Key Manager Providers".

20.1.1 To Accept SSL-Based Connections Using a Self-Signed Certificate

This procedure assumes the following:

  • Oracle Unified Directory is installed on the system on which you are working.

  • The Java keytool utility is in your path. If it is not, either add it to your path or provide the complete path to it when invoking the commands. The keytool utility is provided with the Java Runtime Environment (JRE).

  • The administration connector is listening on the default port (4444) and the dsconfig command is accessing the server running on the local host. If this is not the case, the --port and --hostname options must be specified.

  1. Generate a private key for the certificate, using the keytool command with the -genkeypair option.

    For example:

    $ keytool -genkeypair -alias server-cert -keyalg rsa \
      -dname "CN=myhost.example.com,O=Example Company,C=US" \ 
      -keystore config/keystore -storetype JKS
    
    • -alias alias. Specifies the name that should be used to refer to the certificate in the keystore. The default name used by the server is server-cert.

    • -keyalg algorithm. Specifies the algorithm that should be used to generate the private key. This should almost always be rsa.

    • -dname subject. Specifies the subject to use for the certificate.

      Change the value of the -dname argument so that it is suitable for your environment:

      The value of the CN attribute should be the fully-qualified name of the system on which the certificate is being installed.

      The value of the O attribute should be the name of your company or organization.

      The value of the C attribute should be the two-character abbreviation for your country.

    • -keystore path. Specifies the path to the keystore file. The file will be created if it does not already exist. The default keystore path used by the server is config/keystore.

    • -keypass password. Specifies the password that should be used to protect the private key in the keystore. If the password is not provided, you will be prompted for it.

    • -storepass password. Specifies the password that should be used to protect the contents of the keystore. If the password is not provided, you will be prompted for it. The server expects the password used for the -keypass and -storepass options to be the same.

    • -storetype type. Specifies the keystore type that should be used. For the JKS keystore, for example, the value should always be JKS.

    You are prompted for a password to protect the contents of the keystore and for a password to protect the private key.

  2. Generate a self-signed certificate for the key.

    For example:

    $ keytool -selfcert -alias server-cert -validity 1825 \ 
       -keystore config/keystore -storetype JKS
    
    • -alias alias. Specifies the name that should be used to refer to the certificate in the keystore. This name should be the same as the value used when creating the private key with the -genkeypair option.

    • -validity days. Specifies the length of time in days that the certificate should be valid. The default validity is 90 days.

    • -keystore path. Specifies the path to the keystore file. The file will be created if it does not already exist.

    • -keypass password. Specifies the password that should be used to protect the private key in the keystore. If this is not provided, then you will be interactively prompted for it.

    • -storepass password. Specifies the password that should be used to protect the contents of the keystore. If this is not provided, then you will be interactively prompted for it.

    • -storetype type. Specifies the keystore type that should be used. For the JKS keystore, the value should always be JKS.

    When you are prompted for the keystore password, enter the same password that you provided in the previous step.

  3. Create a text file named config/keystore.pin.

    The file must contain the password that you chose to protect the contents of the keystore. If you change this file, remember that it must match the keystore manager configuration. If you decide to create a file with a different name, for example, the corresponding keystore manager's key-store-file property for JKS must match the path and file name.

  4. Export the public key for the certificate that you created.

    For example:

    $ keytool -exportcert -alias server-cert -file config/server-cert.txt -rfc \
       -keystore config/keystore -storetype JKS
    
  5. Create a new trust store and import the server certificate into that trust store.

    For example:

    $ keytool -importcert -alias server-cert -file config/server-cert.txt \
      -keystore config/truststore -storetype JKS
    
  6. Type yes when you are prompted to trust the certificate.

    This step is required only if the SSL and StartTLS settings were not specified during installation, or if you want to change those settings.

  7. Use the dsconfig command to enable the key manager provider, trust manager provider, and connection handler.

    For example:

    $ dsconfig -D "cn=directory manager" -j pwd-file -X -n \
      set-key-manager-provider-prop --provider-name JKS --set enabled:true
    $ dsconfig -D "cn=directory manager" -j pwd-file -X -n \
      set-trust-manager-provider-prop --provider-name "Blind Trust" \
      --set enabled:true
    $ dsconfig -D "cn=directory manager" -j pwd-file -X -n \
      set-connection-handler-prop --handler-name "LDAPS Connection Handler" \
      --set "trust-manager-provider:Blind Trust" --set key-manager-provider:JKS \ 
      --set listen-port:1636 --set enabled:true
    

    Port 1636 is the standard LDAPS port, but you might not be able to use this port if it is already taken or if you are a regular user. If you need to accept SSL-based connections on a port other than 1636, change the listen-port property in the last command to the port number being used.

    If, in step 3, you created a text file with a location and name other than config/keystore.pin, for example a text file called config/mykeystore.pin, specify that information as follows:

    $ dsconfig -D "cn=directory manager" -j pwd-file -X -n \
      set-key-manager-provider-prop --provider-name JKS --set enabled:true \
      --set keystore-pin-file:/config/mykeystore.pin
    

    For detailed information about keystores, see Section 20.2, "Configuring Key Manager Providers". For detailed information about truststores, see Section 20.3, "Configuring Trust Manager Providers".

  8. The server should now have a second listener that accepts SSL-based client connections. Test the configuration with the ldapsearch command, for example:

    $ ldapsearch --port 1636 --useSSL --baseDN "" --searchScope base "(objectClass=*)"
    

    You are prompted to trust the server's certificate. On typing yes, the root DSE entry should be returned.

20.2 Configuring Key Manager Providers

Key manager providers provide access to the certificate that should be used by the directory server when performing SSL or StartTLS negotiation.

This section covers the following topics:

For more information, see "Key Manager Provider Configuration" in the Configuration Reference for Oracle Unified Directory.

20.2.1 Key Manager Provider Overview

Oracle Unified Directory supports keystore formats for the following key manager providers:

  • JKS keystore, which is the default keystore format used by Java Secure Socket Extension (JSSE)

  • PKCS #12 file

  • PKCS #11 device, such as a hardware security module or cryptographic accelerator

    Note:

    PKCS #11 is not supported for use with a proxy server instance.

The process for configuring Oracle Unified Directory to use these key manager providers is described in detail in the following sections.

The administration connector is an LDAPS connector. As with all SSL-based connectors, the administration connector requires a key manager. Oracle Unified Directory provides a dedicated key manager for the administration connector, that is enabled by default. For more information, see Section 14.3, "Managing Administration Traffic to the Server".

20.2.2 Using the JKS Key Manager Provider

The JKS keystore is the default keystore used by most JSSE implementations, and is the preferred keystore type in many environments. To configure the server to use this keystore type, you must first obtain a JKS keystore that contains a valid certificate. To do this, you can either generate a self-signed certificate or issue a certificate signing request to an existing Certificate Authority (CA) and import the signed certificate.

All of the steps described here require the use of the keytool utility, which is provided with the Java runtime environment. This utility is typically found in the bin directory below the root of the Java installation. For more information about using the keytool utility, see the official Java documentation (http://download.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html).

Using the JKS key manager provider involves the following:

  1. Generating the private key

  2. Self-signing the certificate, or using an external certificate authority to sign the certificate

  3. Configuring the JKS key manager provider

20.2.2.1 To Generate the Private Key

Whether you use a self-signed certificate or generate a certificate signing request, you must first generate a private key. You can do this using the keytool utility with the -genkeypair option. The following arguments can be used with this option:

  • -alias alias. Specifies the name that should be used to refer to the certificate in the keystore. The default name used by server is server-cert.

  • -keyalg algorithm. Specifies the algorithm that should be used to generate the private key. This should almost always be rsa.

  • -dname subject. Specifies the subject to use for the certificate. The subject typically contains at least a CN attribute, which is the fully-qualified name of the system on which the certificate will be installed, an O attribute that specifies the name of the organization (or company), and a C attribute that specifies the country in which the certificate will be used.

  • -keystore path. Specifies the path to the keystore file. The file will be created if it does not already exist. The default keystore path used by the directory server is config/keystore.

  • -keypass password. Specifies the password that should be used to protect the private key in the keystore. If the password is not provided, you will be prompted for it.

  • -storepass password. Specifies the password that should be used to protect the contents of the keystore. If the password is not provided, you will be prompted for it. The directory server expects the password used for the -keypass and -storepass options to be the same.

  • -storetype type. Specifies the keystore type that should be used. For the JKS keystore, the value should always be JKS.

Use the keytool -genkeypair command to create a private key, as follows:

$ keytool -genkeypair -alias server-cert -keyalg rsa \
  -dname "CN=server.example.com,O=example.com,C=US" \
  -keystore config/keystore -keypass password \
  -storetype JKS -storepass password

20.2.2.2 To Self-Sign the Certificate

If the certificate is to be self-signed, use the -selfcert option. The most important arguments for use with this option include:

  • -alias alias. Specifies the name that should be used to refer to the certificate in the keystore. This name should be the same as the value used when creating the private key with the -genkeypair option.

  • -validity days. Specifies the length of time in days that the certificate should be valid. The default validity is 90 days.

  • -keystore path. Specifies the path to the keystore file. The file will be created if it does not already exist.

  • -keypass password. Specifies the password that should be used to protect the private key in the keystore. If this is not provided, then you will be interactively prompted for it.

  • -storepass password. Specifies the password that should be used to protect the contents of the keystore. If this is not provided, then you will be interactively prompted for it.

  • -storetype type. Specifies the keystore type that should be used. For the JKS keystore, the value should always be JKS.

Use the keytool -selfcert command to generate a self-signed certificate, as follows:

$ keytool -selfcert -alias server-cert -validity 1825 \
  -keystore config/keystore -keypass password -storetype JKS \
  -storepass password

20.2.2.3 To Sign the Certificate by Using an External Certificate Authority

If the certificate is to be signed by an external certificate authority, you must first generate a certificate signing request (CSR) using the -certreq option. The CSR can be submitted to a certificate authority to be signed. The method for doing this, and the method for obtaining the signed certificate, might vary from one certificate authority to another.

When you receive the signed certificate from the Certificate Authority, import it into the keystore with the -importcert option.

  1. Use the -certreq option to obtain a certificate signing request.

    $ keytool -certreq -alias server-cert -file /tmp/server-cert.csr \
      -keystore config/keystore -keypass password -storetype JKS \
      -storepass password
    

    The arguments used with this command are as follows:

    • -alias alias. Specifies the name that should be used to refer to the certificate in the keystore. This name should be the same as the value used when creating the private key with the -genkeypair option.

    • -file path. Specifies the path to the file to which the CSR should be written. If this is not provided, the request will be written to standard output.

    • -keystore path. Specifies the path to the keystore file. The file will be created if it does not already exist.

    • -keypass password. Specifies the password that should be used to protect the private key in the keystore. If this is not provided, you will be interactively prompted for it.

    • -storepass password. Specifies the password that should be used to protect the contents of the keystore. If this is not provided, you will be interactively prompted for it.

    • -storetype type. Specifies the keystore type that should be used. For the JKS keystore, the value should always be JKS.

  2. Send the certificate request to an external certificate authority. The certificate authority will send you a signed certificate file. Save the file in /tmp/server-cert.txt

  3. Use the -importcert to import the signed certificate.

    $ keytool -importcert -alias server-cert -file /tmp/server-cert.cert \
      -keystore config/keystore -storetype JKS -storepass password
    

    The arguments used with this command are as follows:

    • -alias alias. Specifies the name that should be used to refer to the certificate in the keystore. This name should be the same as the value used when creating the private key with the -genkeypair option.

    • -file path. Specifies the path to the file containing the signed certificate. The file should be in either the DER-encoded binary format or the base64-encoded ASCII format as described in RFC 1421 (http://www.ietf.org/rfc/rfc1421.txt).

    • -keystore path. Specifies the path to the keystore file. The file will be created if it doesn't already exist.

    • -storepass password. Specifies the password that should be used to protect the contents of the keystore. If this is not provided, then you will be interactively prompted for it.

    • -storetype type. Specifies the keystore type that should be used. For the JKS keystore, the value should always be JKS.

20.2.2.4 To Configure the JKS Key Manager Provider

When you have created a JKS keystore containing a signed certificate (whether self-signed or signed by an external CA), you can configure the server to use that keystore by configuring a key manager provider entry for that keystore.

This example uses dsconfig to configure the properties of the default JKS key manager provider. For details about all the properties of the key manager provider, see "File Based Key Manager Provider Configuration" in the Oracle Unified Directory Configuration Reference.

Use the dsconfig command to configure the key manager provider entry.

$ dsconfig -D "cn=Directory Manager" -j pwd-file -X -n \
  set-key-manager-provider-prop --provider-name "JKS" \
  --set enabled:true --set "key-store-type:JKS" \
  --set "key-store-file:config/keystore" \
  --set "key-store-pin:password"
  --reset key-store-pin-file

20.2.3 Using the PKCS #12 Key Manager Provider

PKCS #12 is a standard format for storing certificate information, including private keys. Oracle Unified Directory can use a PKCS #12 file as a certificate keystore if it includes the private key for the certificate.

Because PKCS #12 is a common format for storing certificate information, you might already have a certificate in this format, or the certificate authority (CA) that you use might create certificates in this form. In some cases, it might also be possible to convert an existing certificate into PKCS #12 format. For example, if you already have a certificate in a Network Security Services (NSS) certificate database, then the NSS pk12util tool can import it. The following example uses the pk12util tool to export a certificate named server-cert contained in the database../../alias/slapd-config-key3.db to a PKCS #12 file, /tmp/server-cert.p12:

$ ./pk12util -n server-cert -o /tmp/server-cert.p12 \
  -d ../../alias -P "slapd-config-"

To create a new certificate in PKCS #12 format, use the procedure described in Section 20.2.2, "Using the JKS Key Manager Provider" for obtaining a certificate in a JKS keystore. The only difference in the process is that you should use -storetype PKCS12 instead of -storetype JKS when you invoke the keytool commands. For example, to create a self-signed certificate in a PKCS #12 file, use the following commands:

$ keytool -genkeypair -alias server-cert -keyalg rsa \
  -dname "CN=server.example.com,O=example.com,C=US" \
  -keystore config/keystore.p12 -keypass password \
  -storetype PKCS12 -storepass password

$ keytool -selfcert -alias server-cert -validity 1825 \
  -keystore config/keystore.p12 -keypass password \
  -storetype PKCS12 -storepass password

As with JKS, the server provides a template key manager provider for use with PKCS #12 certificate files that uses the same set of configuration attributes as the configuration entry for the JKS key manager provider. The only differences are that the value of the key-store-type attribute must be PKCS12, and the key-store-file attribute should refer to the location of the PKCS #12 file rather than a JKS keystore. The following example uses dsconfig to configure the PKCS #12 keystore manager provider:

$ dsconfig -D "cn=directory manager" -j pwd-file -X -n\
  set-key-manager-provider-prop --provider-name "PKCS12" --set enabled:true \
  --set java-class:org.opends.server.extensions.FileBasedKeyManagerProvider \
  --set enabled:true --set "key-store-type:PKCS12" \
  --set "key-store-file:/config/keystore" \
  --set "key-store-pin:secret"

For a complete list of configurable properties, see "File Based Key Manager Provider Configuration" in the Configuration Guide for Oracle Unified Directory.

20.2.4 Using the PKCS #11 Key Manager Provider

PKCS #11 is a standard interface used for interacting with devices capable of holding cryptographic information and performing cryptographic functions. The PKCS #11 interface has two common uses of interest for the directory server:

  • Cryptographic accelerators use this interface to allow products to offload their cryptographic processing to an external board (or in some cases, a special module inside the system's CPU or a framework inside the OS kernel), which might provide better performance for those operations.

  • Hardware security modules (HSMs) use this interface to provide a secure repository for storing key information. This significantly reduces the likelihood that sensitive key information will be exposed and helps protect the overall integrity of the secure communication mechanisms.

Note:

The PKCS #11 format is not supported for use with a proxy server instance.

At present, the PKCS #11 support that Oracle Unified Directory provides has been tested and verified only on systems running at least Solaris 10 (on SPARC and x86/x64 systems) through the use of the Solaris OS cryptographic framework. Any device that plugs into this Solaris cryptographic framework should be supported in this manner. This includes the softtoken device, which is simulated in software and is therefore available on all systems supporting the Solaris cryptographic framework regardless of whether they have a hardware device providing PKCS #11 support.

If you do have a third-party PKCS #11 device installed in a Solaris system, it is likely that the Solaris OS cryptographic framework is already configured to access that device. However, if you will simply be using the software token or if you are running on a Sun Fire T1000 or T2000 system and want to take advantage of the cryptographic processor included in the UltraSPARC—T1 CPU, you will likely need to initialize the PKCS #11 interface. This should first be accomplished by choosing a PIN to use for the certificate store, which can be done with this command:

$ pktool setpin

This command prompts you for the current passphrase. If you have not yet used the Solaris OS cryptographic framework, the default passphrase is changeme. You are then prompted twice for the new password.

Note:

This step should be done while you are logged in as the user or as the role that will be used to run the directory server, because each user might have a different set of certificates.

At this point, it should be possible to use the Java keytool utility to interact with the Solaris cryptographic framework through PKCS #11. This will work much in the same way as it does when working with JKS or PKCS#12 keystores, with the following exceptions:

  • The value of the -keystore argument must be NONE.

  • The value of the -storetype argument must be PKCS11.

  • You should not use the -keypass argument, and the tool will not prompt you for that password interactively if you do not provide it.

  • The value of the -storepass argument must be the passphrase that you chose when using the pktool setpin command. Alternately, if you do not provide this argument on the command line, this is the password that you should enter when prompted.

For example, the following commands use the PKCS #11 interface to generate a self-signed certificate through the Solaris cryptographic framework:

$ keytool -genkeypair -alias server-cert -keyalg rsa \
  -dname "CN=server.example.com,O=example.com,C=US" \
  -keystore NONE -storetype PKCS11 -storepass password

$ keytool -selfcert -alias server-cert -validity 1825 \
  -keystore NONE -storetype PKCS11 -storepass password

When the certificate is installed in the PKCS #11 keystore, the directory server must be configured to use that keystore. Configure the PKCS #11 keystore provider in the same way as the entry for the JKS and PKCS#12 keystore manager providers, with the exception that the key-store-file attribute is not included. However, a PIN is still required and is provided either directly, in a PIN file, through a Java property, or through an environment variable.

The following example uses dsconfig to configure the PKCS #11 key manager provider:

$ dsconfig -D "cn=directory manager" -j pwd-file -X -n \
  set-key-manager-provider-prop --provider-name "PKCS11" --set enabled:true \
  --set enabled:true --set "key-store-type:PKCS11" \
  --set "key-store-file:/config/keystore" \
  --set "key-store-pin:secret"

For a complete list of configurable properties, see "PKCS11 Key Manager Provider Configuration" in the Configuration Guide for Oracle Unified Directory.

20.2.5 Replacing a Certificate in a Production Server

To replace a certificate in a production server, request the new certificate and configure the appropriate key manager provider, as described in Section 20.2.2, "Using the JKS Key Manager Provider", Section 20.2.3, "Using the PKCS #12 Key Manager Provider" or Section 20.2.4, "Using the PKCS #11 Key Manager Provider".

The key-manager-provider property of the SSL-based connection handler (named "LDAPS" by default) specifies the keystore manager that must be used for security. The default value of the key-manager-provider property is "JKS", which means that the SSL connection handler uses the JKS key manager provider by default. If you are using a different key manager provider, change this property of the SSL connection handler accordingly.

There is no need to restart the server after the new certificate is installed. The new certificate is used immediately for subsequent attempts to access the server for associated client connections. Existing connections are not reestablished.

20.2.6 Configuring Key Managers With ODSM

You can manage the key manager configuration by using ODSM, as follows:

  1. Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager".

  2. Select the Configuration tab.

  3. Under General Configuration, expand the Key Managers item.

  4. Select the key manager you want to configure.

    The configurable properties of the key manager are displayed in the right hand pane.

  5. Edit the key manager configuration, as required, and click Apply to save your changes.

20.3 Configuring Trust Manager Providers

Oracle Unified Directory uses trust manager providers to determine whether to trust a certificate that is presented to it. Trust managers serve an important role in the overall security of the system by ensuring that the peer (the system at the other end of the connection, whether it is an inbound connection from a client or an outbound connection to another server) is who it claims to be.

This section covers the following topics:

20.3.1 Overview of Certificate Trust Mechanisms

A trust manager provider can improve security whenever SSL or StartTLS is used by thwarting attempts to use forged certificates and foiling man-in-the-middle attacks.

The two primary use cases for trust manager providers are as follows:

  • Inbound connections: a client presents its own certificate to the server during the SSL or StartTLS negotiation process, potentially for use in SASL EXTERNAL authentication.

  • Outbound connections: the server attempts to establish an SSL-based connection to an external system, for example for the purpose of synchronization or for proxied or chained operations.

The trust manager has no impact on the strength of the encryption, so only the server and its peer will be able to understand the communication. Any third-party observer will be unable to decipher the exchange. The trust manager is responsible for ensuring that the peer is who it claims to be so that confidential information is not inadvertently exposed to one peer masquerading as another.

The trust manager considers a number of factors to determine whether a peer certificate should be trusted. This topic describes some of the most common criteria that are taken into account during this process.

One of the simplest trust mechanisms is the validity period for the certificate. All certificates have a specific window during which they should be considered valid, bounded by "notBefore" and "notAfter" time stamps. If the current time is beyond the "notAfter" time stamp, the certificate is expired and trust managers reject it. Similarly, certificates are also typically rejected if the current time is before the "notBefore" time stamp. Most often, the "notBefore" time stamp is set to the time that the certificate was signed, but there are cases in which a certificate might be issued that is not immediately valid. In those cases, it is important to ensure that the peer is not granted access too early.

Another very important factor in deciding whether to trust a peer certificate is the peer certificate chain. When one system presents its certificate to another, it does not present its certificate only, but a chain of certificates that describes all entities involved in the process. When a trust manager is attempting to determine whether to trust a peer, the trust manager first looks in its trust store to determine whether it contains the peer certificate. If that certificate is found, the peer will be trusted (barring rejection for another reason, such as being outside the validity period). If the peer's certificate is not found, the trust manager looks at the next certificate in the chain, which will be the certificate that was used to sign the peer's certificate (also called the issuer certificate). If the trust store contains the issuer's certificate, the server will trust that issuer certificate and will also implicitly trust any certificate that it has signed. This process continues up the certificate chain (looking at the certificate that signed the issuer certificate, and so on) until one of the certificates is found in the trust store or until the root of the chain is reached (in which case, the root certificate will be self-signed and therefore will be its own issuer). If none of the certificates in the peer chain is contained in the trust store, the peer's certificate is rejected.

This process makes it much easier to manage an environment with a large number of certificates (for example, one in which there is a large number of servers or in which many clients use SASL EXTERNAL authentication). It is not necessary for the trust store to have each individual peer certificate. The trust store can contain only one of the certificates in the peer chain. For example, if all of the certificates that might legitimately be presented to the server were signed by the same issuer, it is necessary to have only that issuer's certificate in the trust store in order to implicitly trust any of the peers.

In some environments, there might be other elements taken into account when deciding to trust a peer certificate chain. For example, there might be a certificate revocation list (CRL) that contains a list of all of the certificates that have been revoked and should no longer be considered valid even if they are still within their validity period and were signed by a trusted issuer. This can be useful, for example, if the certificate belonged to an employee that has left the company or if the private key for the certificate has been compromised. The Online Certificate Status Protocol (OCSP, as described in RFC 2560 (http://www.ietf.org/rfc/rfc2560.txt) also provides a similar mechanism, in which the trust manager might ask an OCSP server whether a given certificate is still valid. Oracle Unified Directory currently does not support using CRLs or OCSP when attempting to determine whether a peer certificate chain should be trusted.

The administration connector is an LDAPS connector. As with all SSL-based connectors, the administration connector requires a trust manager. Oracle Unified Directory provides a dedicated trust manager for the administration connector, that is enabled by default. For more information, see Section 14.3, "Managing Administration Traffic to the Server".

20.3.2 Using the Blind Trust Manager Provider

The blind trust manager provider is a simple provider that trusts any certificate that is presented to it. It does not look at the expiration date, who signed the certificate, the subject or alternate names, or any other criteria.

Oracle Unified Directory provides a blind trust manager provider that is disabled by default. You can enable the provider by changing the value of the enabled attribute to true. The blind trust manager provider does not require any other configuration attributes.

Note:

The blind trust manager provider is not supported with a proxy server instance.

The following example uses dsconfig to configure the blind trust manager provider:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X \
  set-trust-manager-provider-prop --provider-name "Blind Trust"

For a list of the configurable properties, see the "Blind Trust Manager Provider Configuration" in the Configuration Reference for Oracle Unified Directory.

Caution:

The blind trust manager provider is provided as a convenience for testing purposes only and should never be used in a production server, especially one that is configured to allow SASL EXTERNAL authentication. If a client attempts to use SASL EXTERNAL to authenticate to using a certificate and the server blindly accepts any certificate that the client presents, the user can create a self-signed certificate that allows it to impersonate any user in the directory.

20.3.3 Using the JKS Trust Manager Provider

Just as the JKS keystore can be used to provide the key material for a key manager provider, it can also be used to provide information that can used by trust manager providers. In general, using a JKS file as a trust store is similar to using it as a keystore. However, because private key information is not accessed when the file is used as a trust store, there is generally no need for a PIN when accessing its contents.

When the JKS trust manager provider determines whether to trust a given peer certificate chain, it considers two factors:

  • Is the peer certificate within the validity period?

  • Is any certificate in the chain contained in the trust store?

If the peer certificate is not within the validity period or none of the certificates in the peer certificate chain are contained in the trust store, the JKS trust manager rejects that peer certificate.

Use the keytool -importcert utility to import certificates into a JKS trust store. The -importcert option uses these arguments:

  • -alias alias. Specifies the name to give to the certificate in the trust store. Give each certificate a unique name, although the nickname is primarily for managing the certificates in the trust store and has no impact on whether a certificate is trusted.

  • -file path. Specifies the path to the file containing the certificate to import. The file can be in either DER format or in base64-encoded ASCII format, as described in RFC 1421 (http://www.ietf.org/rfc/rfc1421.txt).

  • -keystore path. Specifies the path to the file used as the JKS trust store. This path is typically config/truststore.

  • -storetype type. Specifies the format of the trust store file. For the JKS trust manager, this must be JKS.

  • -storepass password. Specifies the password used to protect the contents of the trust store. If the trust store file does not exist, this value is the password to assign to the trust store, and must be used for future interaction with the trust store. If this option is not provided, the password is interactively requested from the user.

The following command provides an example of importing a certificate into a JKS trust store. If the trust store does not exist, this command creates the trust store before importing the certificate.

$ keytool -importcert -alias server-cert -file /tmp/cert.txt \
  -keystore config/truststore -storetype JKS -storepass password

Oracle Unified Directory provides a template JKS trust manager provider. Use dsconfig to configure the following properties of the JKS trust manager provider:

  • enabled. Indicates whether the JKS trust manager provider is enabled. The JKS trust manager provider is not available for use by other server components unless the value of this property is true.

  • trust-store-file. The path to the trust store file, which is typically config/truststore, although an alternate file can be used if needed. The value of this property can be either an absolute path or a path that is relative to the INSTANCE_DIR.

  • trust-store-type. The format of the trust store. For the JKS trust store provider, the value of this property is JKS.

The following example uses dsconfig in interactive mode to configure the JKS trust manager provider:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X \
  set-trust-manager-provider-prop --provider-name "JKS"

For a list of the configurable properties, see the "File Based Trust Manager Provider Configuration" in the Configuration Reference for Oracle Unified Directory.

20.3.4 Using the PKCS #12 Trust Manager Provider

The PKCS #12 trust manager provider is primarily useful if you already have the peer or issuer certificates to be used in a PKCS #12 file. If you do not have the certificates in this format, use the JKS trust manager provider instead. The Java keytool utility does not currently support importing trusted certificates (that is, those with just a public key and no private key information) into a PKCS #12 file.

Oracle Unified Directory provides a template PKCS #12 trust manager provider. Use dsconfig to configure the following properties of the PKCS #12 trust manager provider:

  • enabled. Indicates whether the PKCS #12 trust manager provider is enabled. The trust manager provider is not available for use by other server components unless this property has a value of true.

  • trust-store-type. Specifies the format of the trust store. For the PKCS #12 trust manager provider, the value is PKCS12.

  • trust-store-file. Specifies the path to the trust store file, which is typically config/truststore.p12, although an alternate file can be used if needed. The value of this property can be either an absolute path or a path that is relative to the INSTANCE_DIR.

A PIN might be required to access the contents of the PKCS #12 file. In this case, one of the following configuration attributes must be used to provide the password. (At the present time, the password must be provided in clear text.)

  • trust-store-pin. Specifies the PIN needed to access the trust store directly.

  • trust-store-pin-file. Specifies the path to a file containing the PIN needed to access the trust store. The value of this property can be either an absolute path or a path that is relative to the server root.

  • trust-store-pin-property. Specifies the name of a Java property that holds the PIN needed to access the trust store.

  • trust-store-pin-environment-variable. Specifies the name of an environment variable that holds the PIN needed to access the trust store.

    The following example uses dsconfig in interactive mode, to configure the PKCS #12 trust manager provider:

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X \
      set-trust-manager-provider-prop --provider-name "PKCS12"
    

    For a list of the configurable properties, see the "File Based Trust Manager Provider Configuration" in the Configuration Reference for Oracle Unified Directory.

20.3.5 Configuring Trust Managers With ODSM

You can manage the trust manager configuration by using ODSM, as follows:

  1. Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager".

  2. Select the Configuration tab.

  3. Under General Configuration, expand the Trust Managers item.

  4. Select the trust manager you want to configure.

    The configurable properties of the trust manager are displayed in the right hand pane.

  5. Edit the trust manager configuration, as required, and click Apply to save your changes.

20.4 Configuring Certificate Mappers

A certificate mapper examines a certificate presented by a client and maps it to the user in the directory that should be associated with that certificate.

Certificate mappers are configured for directory server instances only - not for proxy or gateway instances.

Certificate mappers are primarily used in the context of processing SASL EXTERNAL authentication, where the client wants to authenticate to the server using its SSL certificate rather than a password or some other form of credentials.

Oracle Unified Directory provides the following certificate mappers by default:

You can also create a custom certificate mapper to suit the requirements of your deployment.

A certificate mapper is defined either at the global server configuration level, or at the network group level. If a certificate mapper is defined for the network group, that certificate mapper overrides what is defined in the global server configuration. If no certificate mapper is defined for a network group, the global certificate mapper is used. To define the certificate mapper that should be used, set the certificate-mapper property of the global configuration, or the network group.

The examples in this section use the dsconfig command to modify certificate mappers. The dsconfig command accesses the server configuration over SSL, using the administration connector. For more information, see Section 14.1, "Managing the Server Configuration With dsconfig".

20.4.1 Using the Subject Equals DN Certificate Mapper

The Subject Equals DN certificate mapper is a simple certificate mapper that expects the subject of the client certificate to be exactly the same as the distinguished name (DN) of the corresponding user entry. Using this certificate mapper is easy because there are no configuration attributes associated with it. However, this mapper is not suitable for many environments because certificate subjects and user DNs are often not the same.

The server uses the Subject Equals DN certificate mapper by default. To change the certificate mapper that is used by the server, set the appropriate global configuration property by using dsconfig. The following command changes the certificate mapper that the server uses from Subject Equals DN to Subject Attribute to User.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-global-configuration-prop \  --set certificate-mapper:"Subject Attribute to User Attribute"

You cannot disable the Subject Equals DN certificate mapper if it is referenced by the global server configuration. To disable the mapper, you must change the default certificate mapper, as described previously.

20.4.2 Using the Subject Attribute to User Attribute Certificate Mapper

The Subject Attribute to User Attribute certificate mapper attempts to map a client certificate to a user entry based on a set of attributes that they have in common. In particular, it takes the values of a specified set of attributes from the certificate subject and attempts to locate user entries that contain those same values in a corresponding set of attributes.

Use dsconfig to set the properties of this certificate mapper:

  • subject-attribute-mapping. A multi-valued property that maps attributes from the certificate subject to attributes in user entries. Values for this attribute consist of the name of the attribute in the certificate subject followed by a colon and the name of the corresponding attribute in the user's entry. For example, the value e:mail maps the e attribute from the certificate subject to the mail attribute in user entries. At least one attribute mapping must be defined. The default mappings are e:mail and cn:cn.

  • user-base-dn. A multi-valued property that specifies the set of base DNs below which the server should look for matching entries. If this attribute has no value, the server searches below all public naming contexts.

The following example uses dsconfig to configure the Subject Attribute to User Attribute certificate mapper, specifying that the server should search only below ou=people,dc=example,dc=com:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-certificate-mapper-prop \
  --mapper-name "Subject Attribute to User Attribute" \
  --set user-base-dn:ou=people,dc=example,dc=com

If multiple attribute mappings are defined, the server combines them with an AND search. For example, if two mappings are defined cn:cn and e:mail, and the server is presented with a certificate that has a subject of E=john.doe@example.com,CN=John Doe,O=Example Corp,C=US, then it generates a search filter of (&(cn=John Doe)(mail=john.doe@example.com)). Any attribute for which a mapping is defined but is not contained in the certificate subject is not included in the generated search filter. All attributes that can be used in generated search filters should have corresponding indexes in all remote LDAP databases that can be searched by this certificate mapper.

For the mapping to be successful, the generated search filter must match exactly one user in the directory (within the scope of the base DNs for the mapper). If no users match the generated criteria or if multiple users match, the mapping fails.

20.4.3 Using the Subject DN to User Attribute Certificate Mapper

The Subject DN to User Attribute certificate mapper attempts to establish a mapping by searching for the subject of the provided certificate in a specified attribute in user entries. In this case, you must ensure that user entries are populated with the subjects of the certificates associated with those users. However, it is possible that this process could be automated in the future with a plug-in that automatically identifies any certificates contained in a user entry and adds the subjects of those certificates to a separate attribute.

Use dsconfig to set the properties of this certificate mapper:

  • subject-attribute. This is a single-valued attribute whose value is the name of the attribute type that should contain the certificate subject in user entries. This attribute must be defined in the server schema, and it should be indexed for equality in all back ends that might be searched.

    The subject DN of the certificate received by the server will not contain any spaces between its RDN components, even though the certificate might have been created with them. The value of the subject-attribute in the user entries must also not contain any spaces between the RDN components, so that they will correctly match the subject DN of the received certificate. For example, if the original certificate looks like:

    keytool -printcert -file cert.002
    Owner: CN=test,  O=Test Certificate
    Issuer: CN=test,  O=Test Certificate
    Serial number: 49b55976
    Valid from: Mon Mar 09 19:01:26 MET 2009 until: Sat Mar 08 19:01:26 MET 2014
    Certificate fingerprints:
             MD5:  5E:08:78:36:DF:25:F4:6C:43:9E:7B:CF:1F:1E:B9:6B
             SHA1: B7:B9:1C:A0:B0:52:C3:87:3C:C2:70:27:11:6F:5E:58:C5:33:9D:6B
             Signature algorithm name: SHA1withRSA
             Version: 3
    

    The subject DN defined in the subject-attribute of the user entry should be:

    CN=test,O=Test Certificate
    

    Note the removal of the space between the RDN components of the subject-attribute.

  • user-base-dn. This is a multivalued attribute that is used to specify the set of base DNs below which the server should look for matching entries. If this is not present, then the server will search below all public naming contexts.

The following example uses dsconfig to configure the Subject DN to User Attribute certificate mapper, specifying that the server should search only below ou=people,dc=example,dc=com:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-certificate-mapper-prop \
  --mapper-name "Subject DN to User Attribute" \
  --set user-base-dn:ou=people,dc=example,dc=com

Although there is no standard attribute for holding the subjects of the certificates that a user might hold, does define a custom attribute type, ds-certificate-subject-dn, that can be used for this purpose. This attribute can be added to user entries along with the ds-certificate-user auxiliary object class. This attribute is multivalued. If a user has multiple certificates, the attribute should contain the subjects for each of them as separate values.

This attribute is not indexed by default, so if it is to be used, update the corresponding back ends so that they contain an equality index for this attribute.

For the mapping to be successful, the certificate mapper must match exactly one user (within the scope of the base DNs for the mapper). If no entries match or if multiple entries match, the mapping fails.

20.4.4 Using the Fingerprint Certificate Mapper

The Fingerprint certificate mapper attempts to establish a mapping by searching for the MD5 or SHA1 fingerprint of the provided certificate in a specified attribute in user entries. In this case, you must ensure that user entries are populated with the certificate fingerprints (in standard hexadecimal notation with colons separating the individual bytes, for example, 07:5A:AB:4B:E1:DD:E3:05:83:C0:FE:5F:A3:E8:1E:EB). In the future, this process could be automated by a plug-in that automatically identifies any certificates contained in user entries and adds the fingerprints of those certificates to the appropriate attribute.

Use dsconfig to set the properties of this certificate mapper:

  • fingerprint-attribute. Specifies a single-valued attribute whose value is the name of the attribute type that should contain the certificate fingerprint in user entries. This attribute must be defined in the server schema, and it should be indexed for equality in all back ends that can be searched.

  • fingerprint-algorithm. Specifies which digest algorithm to use to calculate certificate fingerprints. The value is either MD5 or SHA1.

  • user-base-dn. Specifies a multi-valued attribute that is used to specify the set of base DNs below which the server is to look for matching entries. If this property is not present, then the server searches below all public naming contexts.

The following example uses dsconfig to configure the Fingerprint certificate mapper, specifying that the server should search only below ou=people,dc=example,dc=com:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-certificate-mapper-prop \
  --mapper-name "Fingerprint Mapper" \
  --set user-base-dn:ou=people,dc=example,dc=com

Although there is no standard attribute for holding certificate fingerprints, does define a custom attribute type, ds-certificate-fingerprint, that can be used for this purpose. This attribute can be added to user entries along with the ds-certificate-user auxiliary object class. This attribute is multi-valued, and if a user has multiple certificates, then it should contain the fingerprints for each of them as separate values. However, this attribute type is not indexed by default in any of the server back ends, so if it is to be used, add the corresponding equality index to all appropriate back ends.

For the mapping to be successful, the certificate mapper must match exactly one user (within the scope of the base DNs for the mapper). If no entries match or if multiple entries match, the mapping fails.

20.5 Configuring SSL and StartTLS for LDAP and JMX

When you have configured Oracle Unified Directory with at least one enabled key manager provider and at least one enabled trust manager provider, you can enable SSL and StartTLS for the connection handlers.

The examples in this section use the dsconfig command to modify the server configuration. The dsconfig command accesses the server configuration over SSL via the administration connector. As such, the relevant connection options must be specified, including how the SSL certificate is trusted. These examples use the -X option to trust all certificates.

This section covers the following topics:

20.5.1 Configuring the LDAP and LDAPS Connection Handlers

The LDAP connection handler is responsible for managing all communication with clients using LDAP. By default, the LDAP protocol does not specify any form of security for protecting that communication, but it can be configured to use SSL or also to allow the use of the StartTLS extended operation.

The server configures two connection handlers that can be used for this purpose. While the LDAP connection handler entry is enabled by default and is used to perform unencrypted LDAP communication, it can also be configured to support StartTLS. For information, see To Enable StartTLS Support. The LDAPS connection handler entry is disabled, but the default configuration is set up for To Enable SSL-Based Communication.

This section describes how to configure LDAP and LDAPS connection handler parameters with dsconfig and includes the following topics:

20.5.1.1 To Enable a Connection Handler

Set the enabled property of the connection handler to true.

This example enables the LDAP connection handler.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-connection-handler-prop --handler-name "LDAP Connection Handler" \
  --set enabled:true

20.5.1.2 To Specify a Connection Handler's Listening Port

Set the listen-port property of the connection handler.

The listen-port property specifies the port number to use when communicating with the server through this connection handler. The standard port to use for unencrypted LDAP communication (or LDAP using StartTLS) is 389, and the standard port for SSL-encrypted LDAP is 636. However, it might be desirable or necessary to change this in some environments (for example, if the standard port is already in use, or if you are running on a UNIX system as a user without sufficient privileges to bind to a port below 1024).

This example sets the LDAPS connection handler's listen port to 1636.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-connection-handler-prop --handler-name "LDAPS Connection Handler" \
  --set listen-port:1636

20.5.1.3 To Specify a Connection Handler's Authorization Policy

Set the ssl-client-auth-policy property of the connection handler.

The ssl-client-auth-policy property specifies how the connection handler should behave when requesting a client certificate during the SSL or StartTLS negotiation process. If the value is optional, the server requests that the client present its own certificate but still accepts the connection even if the client does not provide a certificate. If the value is required, the server requests that the client present its own certificate and rejects any connection in which the client does not do so. If the value is disabled, the server does not ask the client to present its own certificate.

This example sets the LDAPS connection handler's authorization policy to required.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-connection-handler-prop --handler-name "LDAPS Connection Handler" \
  --set ssl-client-auth-policy:required

20.5.1.4 To Specify a Nickname for a Connection Handler's Certificate

Set the ssl-cert-nickname property of the connection handler.

The ssl-cert-nickname property specifies the nickname of the certificate that the server presents to clients during SSL or StartTLS negotiation. This property is primarily useful when multiple certificates are in the keystore and you want to specify which certificate is to be used for that listener instance.

This example sets the nickname of the LDAP connection handler's certificate to server-cert.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-connection-handler-prop --handler-name "LDAP Connection Handler" \
  --set ssl-cert-nickname:server-cert

20.5.1.5 To Specify a Connection Handler's Key Manager Provider

Set the key-manager-provider property of the connection handler.

The key-manager-provider property specifies which key manager provider among the available Configuring Key Manager Providers that should be used by the connection handler to obtain the key material for the SSL or StartTLS negotiation.

This example sets the LDAP connection handler's key manager provider to JKS. The specified manager must already be configured for the command to succeed.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-connection-handler-prop --handler-name "LDAP Connection Handler" \
  --set key-manager-provider:JKS

20.5.1.6 To Specify a Connection Handler's Trust Manager Provider

Set the trust-manager-provider property of the connection handler.

The trust-manager-provider property specifies which trust manager provider among the available Configuring Trust Manager Providers to be used by the connection handler to decide whether to trust client certificates presented to it.

This example sets the LDAP connection handler's trust manager to JKS. The specified manager must already be configured for the command to succeed.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-connection-handler-prop --handler-name "LDAP Connection Handler" \
  --set trust-manager-provider:JKS

20.5.1.7 To Enable StartTLS Support

  1. Specify the appropriate values for the key-manager-provider and trust-manager-provider properties.

  2. Set the allow-start-tls property to true, as follows:

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
      set-connection-handler-prop --handler-name "LDAP Connection Handler" \
      --set allow-start-tls:true
    

    Note:

    If SSL is enabled, the allow-start-tls property cannot be set.

    StartTLS is not supported for connections between the proxy and the remote LDAP servers. Depending on the setting of the remote LDAP server SSL policy, StartTLS client connections can be passed from the proxy to the remote LDAP servers as SSL connections or as insecure connections. For more information, see To Create a Global Index Catalog Containing Global Indexes.

20.5.1.8 To Enable SSL-Based Communication

  1. Display the connection handler properties to ensure that the configured key manager provider and trust manager provider values are correct.

    The following example displays the properties of the LDAPS connection handler:

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
      get-connection-handler-prop --handler-name "LDAPS Connection Handler"
    
  2. Set the enabled property to true, as follows:

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
      set-connection-handler-prop --handler-name "LDAPS Connection Handler" \
      --set enabled:true
    

    Note:

    If SSL is enabled, non-SSL communication will not be available for that connection handler instance.

20.5.2 Enabling SSL in the JMX Connection Handler

The JMX connection handler can be used to communicate with clients using the JMX (Java Management Extensions) protocol. This protocol does not support the use of StartTLS to allow both encrypted and unencrypted communication over the same port, but it can be configured to accept only unencrypted JMX or only SSL-encrypted JMX communication.

The JMX connection handler provides the server's default configuration for communicating over JMX. To enable SSL for this connection handler, use dsconfig to set the following configuration attributes:

  • key-manager-provider. Specifies the DN of the configuration entry for the key manager provider that is used to obtain the key material for the SSL negotiation.

  • ssl-cert-nickname. Specifies the nickname (or alias) of the certificate that is presented to clients.

  • use-ssl. Indicates whether the connection handler is to use SSL to communicate with clients.

The following example uses dsconfig in interactive mode to configure the JMX connection handler:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X \
  set-connection-handler-prop --handler-name "JMX Connection Handler"

For a list of the configurable properties, see the "JMX Connection Handler Configuration" in the Configuration Reference for Oracle Unified Directory.

20.6 Using SASL Authentication

The LDAP protocol definition provides two ways in which clients can authenticate to the server: LDAP simple authentication and SASL authentication.

Note:

SASL is not supported for use with a proxy server instance.

In LDAP simple authentication, the client specifies the DN and password for the user. This is by far the most common authentication mechanism, and in most cases it is also the easiest to use. However, it has a number of limitations, including the following:

To address these issues, it is also possible to authenticate clients through the Simple Authentication and Security Layer (SASL), as defined in RFC 4422 (http://www.ietf.org/rfc/rfc4422.txt). This is a very extensible framework, and makes it possible for servers to support many different kinds of authentication.

20.6.1 Supported SASL Mechanisms

currently supports the following SASL mechanisms:

Note:

With the proxy server, currently the only supported SASL mechanism is ANONYMOUS.

ANONYMOUS

This mechanism does not actually authenticate clients, but does provide a mechanism for including trace information in server logs for debugging purposes.

CRAM-MD5

This mechanism is provided for backward compatibility only. Do not configure CRAM-MD5 in a production environment. Use the DIGEST-MD5 mechanism instead, because it provides much better security.

DIGEST-MD5

This mechanism provides the ability for clients to use password-based authentication without sending the password to the server. Instead, the client only needs to provide information that proves it knows the password. This mechanism offers more options and better security than the CRAM-MD5 mechanism.

EXTERNAL

This mechanism provides the ability for clients to identify themselves based on information provided outside of the direct flow of LDAP communication. In Oracle Unified Directory, this may be achieved through the use of SSL client certificates.

GSSAPI

This mechanism provides the ability for clients to authenticate to the server through their participation in a Kerberos V5 environment.

PLAIN

This mechanism uses a password based authentication, but does offer the ability to use a username rather than requiring a DN.

Support for additional SASL mechanisms can be added by implementing custom SASL mechanism handlers in the server..

Because SASL mechanisms are so extensible, the set of information that the client needs to provide to the server in order to perform the authentication varies from one mechanism to another. As such, Oracle Unified Directory clients use a generic interface for users to provide this information. This is exposed through the -o or --saslOption argument, and the value for this argument should be a name-value pair. Select which SASL mechanism to use using the mech option, for example:

--saslOption mech=DIGEST-MD5

The other options that are available for use depend on the SASL mechanism that has been chosen, as described in the following sections.

20.6.2 Authorization IDs

Many of the SASL mechanisms below provide the ability to identify a user based on an authorization ID rather than a user DN. An authorization ID may be given in one of two forms:

dn:dn

This is used to provide the full DN of the user to authenticate (for example, dn:uid=john.doe,ou=People,dc=example,dc=com). A value of dn: with no DN is to be treated as the anonymous user, although this form is not accepted by many of the SASL mechanisms listed below.

u:username

This is used to provide the username of the user rather than the full DN (for example, u:john.doe).

If the u:username form is used, the mechanism that the server uses to resolve that username to the corresponding user entry is based on the identity mapping configuration within the server.

20.6.3 SASL Options for the ANONYMOUS Mechanism

Because the ANONYMOUS mechanism is not really used to perform authentication, no additional options are required. However, the following option can be supplied:

trace

This option can be used to provide a trace string that is written to the server's access log. This can be useful for debugging or to identify the client, although without authentication it is not possible to rely on the validity of this value.

The following command demonstrates the use of SASL anonymous authentication:

$ ldapsearch --hostname server.example.com --port 1389 --saslOption mech=ANONYMOUS \
  --saslOption "trace=Example Trace String" --baseDN "" \
  --searchScope base "(objectClass=*)"

20.6.4 SASL Options for the CRAM-MD5 Mechanism

The CRAM-MD5 mechanism is used to perform password-based authentication to the server without exposing the clear-text password. It does this by providing an MD5 digest of the clear-text password combined with some randomly-generated data provided by the server, which helps prevent replay attacks.

The SASL CRAM-MD5 mechanism has one SASL option that must be provided:

authid

This specifies the identity of the user that is authenticating to the server. It should be an authorization ID value as described above.

The password is specified using either the --bindPassword or --bindPasswordFile option, just as when using simple authentication. The following command demonstrates the use of SASL CRAM-MD5 authentication:

ldapsearch --hostname server.example.com --port 1389 --saslOption mech=CRAM-MD5 \
--saslOption authid=u:john.doe --baseDN "" --searchScope base "(objectClass=*)"

20.6.5 SASL Options for the DIGEST-MD5 Mechanism

The DIGEST-MD5 mechanism is similar to the CRAM-MD5 mechanism, but it is more secure because it combines random data from both the client and the server in order to help foil both replay and man-in-the-middle attacks. DIGEST-MD5 authentication also offers a number of SASL options, including the following:

authid

Specifies the identity of the user that is authenticating to the server. This option must be provided.

realm

This option should not be specified as a DN.

Note:

Do not use the realm option, because the server does not use it when mapping identities.

digest-uri

Specifies the digest URI that the client uses to communicate with the server. This is an optional parameter, but if it is provided, specify it in the form ldap/serveraddress, where serveraddress is the fully-qualified address of the server.

Note:

Do not use the digest-uri option in a production environment.

authzid

Specifies the authorization ID that should be used during the authentication process. This option can be used to indicate that the operations requested on the connection after authentication should be performed under the authority of another user.

The password is specified using either the --bindPassword or --bindPasswordFile option, just as when using simple authentication. The following command demonstrates the use of SASL DIGEST-MD5 authentication:

$ ldapsearch --hostname server.example.com --port 1389 --saslOption mech=DIGEST-MD5 \
  --saslOption authid=u:john.doe --saslOption realm=dc=example,dc=com --baseDN "" \
  --searchScope base "(objectClass=*)"

20.6.6 SASL Options for the EXTERNAL Mechanism

The EXTERNAL mechanism is used to perform authentication based on information that is available to the server outside of the LDAP session. At present, this is available only through SSL client authentication, in which case the information that the client's SSL certificate will be used to authenticate that client. As such, it is necessary to use SSL or StartTLS when communicating with the server, and a client certificate keystore must be available.

The EXTERNAL mechanism does not support any additional SASL options. In most cases, it can be requested using either --saslOption mech=EXTERNAL or --useSASLExternal. The following command demonstrates the use of SASL EXTERNAL authentication:

$ ldapsearch --hostname server.example.com --port 1636 --useSSL \
  --keyStorePath /path/to/key.store --keyStorePasswordFile /path/to/key.store.pin \
  --trustStorePath /path/to/trust.store --saslOption mech=EXTERNAL --baseDN "" \
  --searchScope base "(objectClass=*)"

For more information, see Configuring SASL External Authentication.

20.6.7 SASL Options for the GSSAPI Mechanism

The GSSAPI mechanism is used to perform authentication in a Kerberos V5 environment, and generally requires that the client system be configured to participate in such an environment. The options available for use with the GSSAPI mechanism include:

authid

Specifies the authentication ID that should be used to identify the user. This ID should be in the form of a Kerberos principal and not in the authorization ID form described previously. This option must be provided if the user has not authenticated to Kerberos before attempting to bind.

authzid

Specifies the authorization ID that should be used to identify the user under whose authority operations should be performed. does not yet support this capability.

quality-of-protection

Specifies the quality of protection to use for the communication. Currently, only the auth quality-of-protection value is supported by clients. The auth-int and auth-conf values are supported by the server.

If the user already has a valid Kerberos ticket on the system when attempting to use GSSAPI, the client attempts to use it so that no password is required. However, if the user does not have a valid Kerberos ticket or if it cannot be accessed for some reason, a password must be provided using either the --bindPassword or --bindPasswordFile options.

The following command demonstrates the use of SASL GSSAPI authentication for a user that already has a valid Kerberos session:

$ ldapsearch --hostname server.example.com --port 1389 --saslOption mech=GSSAPI \
--saslOption authid=jdoe@EXAMPLE.COM --baseDN "" --searchScope base "(objectClass=*)"

20.6.8 SASL Options for the PLAIN Mechanism

The PLAIN mechanism provides many of the same capabilities as LDAP simple authentication, although the user may be identified in the form of an authorization ID rather than requiring a full DN. The following options are available for use when using SASL PLAIN authentication:

authid

Specifies the identity of the user that is authenticating to the server. It should be an authorization ID value as described above. This option must be provided.

authzid

Specifies the identity of the user under whose authority operations should be performed. It should also be in the form of an authorization ID. does not yet support this capability.

The password is specified using either the --bindPassword or --bindPasswordFile option, just as when using simple authentication. The following command demonstrates the use of SASL PLAIN authentication:

$ ldapsearch --hostname server.example.com --port 1389 --saslOption mech=PLAIN \
--saslOption authid=u:john.doe --baseDN "" --searchScope base "(objectClass=*)"

20.7 Configuring SASL Authentication

This section describes the requirements for configuring directory server to use the various SASL authentication mechanisms.

Note:

SASL is not supported for use with a proxy server instance.

20.7.1 Configuring SASL External Authentication

The SASL EXTERNAL mechanism is used to allow a client to authenticate itself to the directory server using information provided outside of what is strictly considered LDAP communication. currently supports authentication using a client certificate presented to the server during SSL or StartTLS negotiation, for LDAP communication only.

20.7.1.1 Configuring the LDAP Connection Handler to Allow SASL EXTERNAL Authentication

For the directory server to be able to map the client certificate to a user entry, ensure that the connection handler is configured to handle client certificates. Use the dsconfig to set the following LDAP connection handler properties:

  • ssl-client-auth-policy. Specifies whether the directory server prompts the client to present its own certificate during the SSL or StartTLS negotiation process. To support SASL EXTERNAL authentication, the value must be either optional or required. If the value is disabled, clients are not prompted to provide a certificate and no certificate is available for authentication.

  • trust-manager-provider. Specifies the DN of the trust manager provider used to determine whether the directory server trusts the validity of the client certificate. If the server does not trust the client certificate, the SSL or StartTLS negotiation fails and it is not possible for the client to request SASL EXTERNAL authentication. If the server trusts illegitimate client certificates, it is possible for malicious users to forge certificates and impersonate any user in the directory. In most cases, the JKS or PKCS12 trust manager provider should be used and the corresponding trust store loaded only with the issuer certificates that are used to sign client certificates.

Note:

The dsconfig command accesses the server configuration over SSL via the administration connector. As such, the relevant connection options must be specified, including how the SSL certificate is trusted. These examples use the -X option to trust all certificates.

The following example uses dsconfig in interactive mode to set LDAP connection handler properties:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager"-j pwd-file -X \
  set-connection-handler-prop --handler-name "LDAP Connection Handler"

For a list of the configurable properties, see the "LDAP Connection Handler Configuration" in the Configuration Reference for Oracle Unified Directory.

20.7.1.2 Configuring the EXTERNAL SASL Mechanism Handler

SASL EXTERNAL bind requests are processed by the SASL mechanism handler. Use the dsconfig command to set the following SASL mechanism handler properties:

  • java-class. Specifies the fully-qualified name of the Java class that provides the logic for the SASL mechanism handler. For the EXTERNAL mechanism, this value is always org.opends.server.extensions.ExternalSASLMechanismHandler. An advanced property.

  • enabled. Indicates whether the EXTERNAL SASL mechanism is enabled for use. If you do not want to allow clients to use SASL EXTERNAL authentication, change its value to false.

  • certificate-mapper. Specifies the DN of the configuration entry for the certificate mapper to be used to map client certificates to user entries.

  • certificate-validation-policy. Specifies whether the directory server attempts to locate the client certificate in the user's entry after establishing a mapping. If the value is always, the authentication succeeds only if the mapped user's entry contains the certificate presented by the client. If the value is ifpresent (the default value) and the user's entry contains one or more certificates, the authentication succeeds only if one of those certificates matches the one presented by the client. If the value is ifpresent and the user's entry does not contain any certificates, the authentication still succeeds based on the fact that it would have been accepted by the trust manager and mapped by the certificate mapper. If the value is never, the server does not attempt to match the certificate to a value in the user's entry even if that entry contains one or more certificates.

  • certificate-attribute. Specifies the name of the attribute that holds user certificates to be examined if the certificate-validation-policy property has a value of either always or ifpresent.

The following example uses dsconfig in interactive mode to set EXTERNAL SASL mechanism handler properties:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager"-j pwd-file -X \
  set-sasl-mechanism-handler-prop --handler-name "EXTERNAL"

For a list of the configurable properties, see the "SASL Mechanism Handler Configuration" in the Configuration Reference for Oracle Unified Directory.

20.7.2 Configuring SASL DIGEST-MD5 Authentication

This section explains the access control and privilege restrictions on a user using the authorization ID keyword (authzid). If the user is not using the authzid keyword, these restrictions do not apply. Any user that binds using DIGEST-MD5 and the authzid keyword must fulfill the following requirements:

  • The authentication ID (authid) must be granted access by an ACI that grants it the proxy right to the authorization ID.

  • The authentication ID (authid) entry must contain the proxied-auth privilege. The following example creates a test environment and demonstrates the requirements for user authentication using the DIGEST-MD5 SASL mechanism.

The following example creates a test environment and then demonstrates the requirements for a user authentication using the DIGEST-MD5 SASL mechanism.

  1. Import the following entries into the directory. These entries define an ACI and three users:

    • The entry uid=user.0,ou=People,dc=example,dc=com does not have the proxied-auth privilege but is granted proxy access by the ACI.

    • The entry uid=user.1,ou=People,dc=example,dc=com has the proxied-auth privilege but is not granted proxy access by the ACI.

    • The entry uid=user.2,ou=People,dc=example,dc=com has the proxied-auth privilege and is granted proxy access by the ACI.

    dn: ou=People,dc=example,dc=com
    objectClass: top
    objectClass: organizationalunit
    objectClass: posixGroup
    ou: People
    aci: (target="ldap:///uid=proxy user,ou=People,dc=example,dc=com") \
     (targetattr="*") (version 3.0; acl "allow SASL Example"; \
     allow (proxy) userdn="ldap:///uid=user.0,ou=People,dc=example,dc=com || 
     ldap:///uid=user.2,ou=People,dc=example,dc=com";)
    
    dn: uid=user.0,ou=People,dc=example,dc=com
    objectClass: top
    objectClass: person
    objectClass: organizationalperson
    objectClass: inetorgperson
    ...
    description: This is the description for user.0
    
    dn: uid=user.1,ou=People,dc=example,dc=com
    objectClass: top
    objectClass: person
    objectClass: organizationalperson
    objectClass: inetorgperson
    ...
    description: This is the description for user.1
    ds-privilege-name: proxied-auth
    
    dn: uid=proxy user,ou=People,dc=example,dc=com
    objectClass: top
    objectClass: person
    objectClass: organizationalperson
    objectClass: inetorgperson
    ...
    description: This is the description for proxy user
    
    dn: uid=user.2,ou=People,dc=example,dc=com
    objectClass: top
    objectClass: person
    objectClass: organizationalperson
    objectClass: inetorgperson
    ...
    description: This is the description for user.2
    ds-privilege-name: proxied-auth
    
  2. Bind using DIGEST-MD5 as uid=user.1,ou=People,dc=example,dc=com:

    $ ldapsearch --port 1389 -j pwd-file --saslOption mech=DIGEST-MD5 \
      --saslOption authid=dn:uid=user.1,ou=People,dc=example,dc=com --saslOption \
      authzid=dn:uid=proxy user,ou=People,dc=example,dc=com --baseDN "" \
      --searchScope base "(objectClass=*)"
     The SASL DIGEST-MD5 bind attempt failed Result Code: 49 (Invalid Credentials)
    

    The search fails because uid=user.1,ou=People,dc=example,dc=com is not granted the proxy right by the ACI.

  3. Bind using DIGEST-MD5 as uid=user.0,ou=People,dc=example,dc=com:

    $ ldapsearch --port 1389 -j pwd-file --saslOption mech=DIGEST-MD5 \
      --saslOption authid=dn:uid=user.0,ou=People,dc=example,dc=com --saslOption \
      authzid=dn:uid=proxy user,ou=People,dc=example,dc=com --baseDN "" \
      --searchScope base "(objectClass=*)"
    The SASL DIGEST-MD5 bind attempt failed Result Code: 49 (Invalid Credentials)
    

    The search fails because uid=user.0,ou=People,dc=example,dc=com does not have the proxied-auth property.

  4. Bind using DIGEST-MD5 as uid=user.2,ou=People,dc=example,dc=com authid with both access control access and the proxied-auth privilege:

    $ ldapsearch --port 1389 -j pwd-file --saslOption mech=DIGEST-MD5 \
      --saslOption authid=dn:uid=user.2,ou=People,dc=example,dc=com --saslOption \
      authzid=dn:uid=proxy user,ou=People,dc=example,dc=com --baseDN "" \
      --searchScope base "(objectClass=*)"
    dn: 
    objectClass: ds-root-dse 
    objectClass: top
    

    The search succeeds because uid=user.2,ou=People,dc=example,dc=com has access allowed by the ACI and the proxied-auth privilege.

20.7.3 Configuring SASL GSSAPI Authentication

This section explains the access control and privilege restrictions on a user using the authorization ID keyword (authzid). If the user is not using the authzid keyword, the restrictions do not apply.

Any user that binds using GSSAPI must fulfill the following requirements:

  • The authentication ID (authid) must be granted access by an ACI that grants it the proxy right to the authorization ID.

  • The authentication ID (authid) entry must contain the proxied-auth privilege.

The following example creates a test environment with three example entries and demonstrates the requirements for user authentication using the GSSAPI SASL mechanism. These examples require a fully configured Kerberos environment, including a valid keytab file.

  1. Create three Kerberos principals in the realm TESTLOCAL.NET:

    • user.0@TESTLOCAL.NET

    • user.1@TESTLOCAL.NET

    • user.2@TESTLOCAL.NET

  2. Configure the GSSAPI SASL handler to be enabled, to use the regular expression identity mapper, and to use a valid TESTLOCAL.NET keytab file.

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
      set-sasl-mechanism-handler-prop --handler-name "GSSAPI" \
      --set enabled:true --set identity-mapper:"Regular Expression" \
      --set keytab:keytabPath
    

    The default value of the GSSAPI enabled property is false, so it must be set to true. The default value of identity-mapper is Regular Expression. The default value of the keytab property is /etc/krb5/krb5.keytab.

  3. Import the following entries into the directory. These entries define an ACI and three users:

    • The entry uid=user.0,ou=People,dc=example,dc=com does not have the proxied-auth privilege but is granted proxy access by the ACI.

    • The entry uid=user.1,ou=People,dc=example,dc=com has the proxied-auth privilege but is not granted proxy access by the ACI.

    • The entry uid=user.2,ou=People,dc=example,dc=com has the proxied-auth privilege and is granted proxy access by the ACI.

    dn: ou=People,dc=example,dc=com
    objectClass: top
    objectClass: organizationalunit
    objectClass: posixGroup
    ou: People
    aci: (target="ldap:///uid=proxy user,ou=People,dc=example,dc=com") \
     (targetattr="*") (version 3.0; acl "allow SASL Example"; \
     allow (proxy) userdn="ldap:///uid=user.0,ou=People,dc=example,dc=com"
     || "ldap:///uid=user.2,ou=People,dc=example,dc=com";)
    
    dn: uid=user.0,ou=People,dc=example,dc=com
    objectClass: top
    objectClass: person
    objectClass: organizationalperson
    objectClass: inetorgperson
    uid=user.0
    ...
    description: This is the description for user.0
    
    dn: uid=user.1,ou=People,dc=example,dc=com
    objectClass: top
    objectClass: person
    objectClass: organizationalperson
    objectClass: inetorgperson
    uid=user.1
    ...
    description: This is the description for user.1
    ds-privilege-name: proxied-auth
    
    dn: uid=user.2,ou=People,dc=example,dc=com
    objectClass: top
    objectClass: person
    objectClass: organizationalperson
    objectClass: inetorgperson
    uid=user.2
    ...
    description: This is the description for user.2
    ds-privilege-name: proxied-auth
    
    dn: uid=proxy user,ou=People,dc=example,dc=com
    objectClass: top
    objectClass: person
    objectClass: organizationalperson
    objectClass: inetorgperson
    uid=proxy user
    ...
    description: This is the description for proxy user
    
  4. Run this command to demonstrate a failing GSSAPI SASL bind using the Kerberos principal, user.0@TESTLOCAL.NET:

    $ ldapsearch --port 1389 \
      --saslOption mech=GSSAPI \
      --saslOption authid=user.0@TESTLOCAL.NET \
      --saslOption authzid=dn:uid=proxy user,ou=People,dc=example,dc=com \
      --baseDN "" --searchScope base "(objectClass=*)"
    The SASL DIGEST-MD5 bind attempt failed
    Result Code:  49 (Invalid Credentials)
    

    This search fails because user.0@TESTLOCAL.NET maps to uid=user.0,ou=People,dc=example,dc=com, which has access control permissions to uid=proxy user,ou=People,dc=example,dc=com but does not have the proxied-auth privilege.

  5. Run this command to demonstrate a failing GSSAPI SASL bind using the Kerberos principal, user.1@TESTLOCAL.NET.

    $ ldapsearch --port 1389 \
      --saslOption mech=GSSAPI \
      --saslOption authid=user.1@TESTLOCAL.NET \
      --saslOption authzid=dn:uid=proxy user,ou=People,dc=example,dc=com \
      --baseDN "" --searchScope base "(objectClass=*)"
    The SASL DIGEST-MD5 bind attempt failed
    Result Code:  49 (Invalid Credentials)
    

    This search fails because user.1@TESTLOCAL.NET maps to uid=user.1,ou=People,dc=example,dc=com, which has the proxied-auth privilege but does not have access control permissions to uid=proxy user,ou=People,dc=example,dc=com.

  6. Run this command to demonstrate a successful GSSAPI SASL bind using the Kerberos principal user.2@TESTLOCAL.NET:

    $ ldapsearch --port 1389 \
      --saslOption mech=GSSAPI \
      --saslOption authid=user.2@TESTLOCAL.NET \
      --saslOption authzid=dn:uid=proxy user,ou=People,dc=example,dc=com \
      --baseDN "" --searchScope base "(objectClass=*)"
    dn:
    objectClass: ds-root-dse
    objectClass: top }}} \\ \\ 
    

    This search succeeds because user.2@TESTLOCAL.NET maps to uid=user.2,ou=People,dc=example,dc=com, which has both the proxied-auth privilege and access control permission to id=proxy user,ou=People,dc=example,dc=com.

20.8 Configuring Kerberos and the Oracle Unified Directory Server for GSSAPI SASL Authentication

The following sections describe how to configure and Kerberos Version 5 for GSSAPI SASL authentication.

20.8.1 To Configure Kerberos V5 on a Host

You must configure Kerberos V5 on the host machine where your LDAP clients will run.

  1. Install Kerberos V5 according to its installation instructions.

    Sun recommends installing the Sun Enterprise Authentication Mechanism 1.0.1 client software.

  2. Configure the Kerberos software.

    Using the Sun Enterprise Authentication Mechanism software, configure the files under /etc/krb5. This configuration sets up the kdc server, and defines the default realm and any other configuration required by your Kerberos system.

  3. If necessary, modify the file /etc/gss/mech so that the first value that is listed is kerberos_v5.

20.8.2 To Specify SASL Options for Kerberos Authentication

You must specify appropriate SASL options for the Kerberos installation.

  1. Before using a client application that is enabled with the GSSAPI mechanism, initialize the Kerberos security system with your user Principal.

    $ kinit user-principal
    

    where the user-principal is your SASL identity, for example, bjensen@example.com.

  2. Specify SASL options for using Kerberos.

    Note that in the UNIX environment, you must set the SASL_PATH environment variable to the correct path for the SASL libraries. For example in the Korn shell:

    $ export SASL_PATH=SASL-library
    

    This path assumes that the Oracle Unified Directory software is installed on the same host where the LDAP tools are invoked.

    The following example of the ldapsearch tool shows the use of the -o (lowercase letter o) option to specify SASL options for using Kerberos:

    $ ldapsearch -h www.host1.com -p 1389 -o mech=GSSAPI -o authid="bjensen@EXAMPLE.COM" \
     -o authzid="bjensen@EXAMPLE.COM" -b "dc=example,dc=com" "(givenname=Richard)"
    

    The authid can be omitted because it is present in the Kerberos cache that was initialized by the kinit command. If authid is present, authid and authzid must be identical, although the authzid intended for proxy operations is not used. The value of authid is the Principal that is used in identity mapping. The Principal must be the full Principal, including the realm.

20.8.3 Example Configuration of Kerberos Authentication Using GSSAPI With SASL

Configuring Kerberos for the Oracle Unified Directory directory server can be complicated. Your first point of reference should be the Kerberos documentation.

For more help, use the following example procedure to get an idea of which steps to follow. Be aware, however, that this procedure is an example. You must modify the procedure to suit your own configuration and your own environment.

Additional information about configuring and using Kerberos in the Solaris OS can be found in System Administration Guide: Security Services. This guide is a part of the Solaris documentation set. You can also consult the man pages.

Information about this example and the steps used are as follows:

  1. Assumptions for This Example

  2. All Machines: Edit the Kerberos Client Configuration File

  3. All Machines: Edit the Administration Server ACL Configuration File

  4. KDC Machine: Edit the KDC Server Configuration File

  5. KDC Machine: Create the KDC Database

  6. KDC Machine: Create an Administration Principal and Keytab

  7. KDC Machine: Start the Kerberos Daemons

  8. KDC Machine: Add Host Principals for the KDC and Oracle Unified Directory Machines

  9. KDC Machine: Add an LDAP Principal for the Directory Server

  10. KDC Machine: Add a Test User to the KDC

  11. Directory Server Machine: Install Oracle Unified Directory

  12. Directory Server Machine: Configure the Directory Server to Enable GSSAPI

  13. Directory Server Machine: Create and Configure the Directory Server LDAP

  14. Directory Server Machine: Add a Test User to the Directory Server

  15. Directory Server Machine: Obtain a Kerberos Ticket as the Test User

  16. Client Machine: Authenticate to the Directory Server Through GSSAPI

20.8.3.1 Assumptions for This Example

This example procedure describes the process of configuring one machine to operate as a Key Distribution Center (KDC), and a second machine to run the directory server. The result of this procedure is that users can perform Kerberos authentication through GSSAPI.

It is possible to run both the KDC and the directory server on the same machine. If you choose to run both on the same machine, use the same procedure, but omit the steps for the directory server machine that have already been done for the KDC machine.

This procedure makes a number of assumptions about the environment that is used. When using the example procedure, modify the values accordingly to suit your environment. These assumptions are:

  • This system has a fresh installation of the Solaris 10 software with the latest recommended patch cluster installed. Kerberos authentication to the directory server can fail if the appropriate Solaris patches are not installed.

  • The machine that is running the Kerberos daemons has the fully qualified domain name of kdc.example.com. The machine must be configured to use DNS as a naming service. This configuration is a requirement of Kerberos. Certain operations might fail if other naming services such as file are used instead.

  • The machine that is running the directory server has the fully qualified domain name of directory.example.com. This machine must also be configured to use DNS as a naming service.

  • The directory server machine serves as the client system for authenticating to the directory server through Kerberos. This authentication can be performed from any system that can communicate with both the directory server and Kerberos daemons. However, all of the necessary components for this example are provided with the Oracle Unified Directory directory server, and the authentication is performed from that system.

  • Users in the directory server have DNs of the form uid=username,ou=People,dc=example,dc=com. The corresponding Kerberos principal is username@EXAMPLE.COM. If a different naming scheme is used, a different GSSAPI identity mapping must be used.

20.8.3.2 All Machines: Edit the Kerberos Client Configuration File

The /etc/krb5/krb5.conf configuration file provides information that Kerberos clients require in order to communicate with the KDC.

Edit the /etc/krb5/krb5.conf configuration file on the KDC machine, the directory server machine, and any client machines that will authenticate to the directory server using Kerberos.

  • Replace every occurrence of "___default_realm___" with "EXAMPLE.COM".

  • Replace every occurrence of "___master_kdc___" with "kdc.example.com".

  • Remove the lines that contain "___slave_kdcs___" as there will be only a single Kerberos server.

  • Replace "___domain_mapping___" with ".example.com = EXAMPLE.COM" (note the initial period in.example.com).

The updated /etc/krb5/krb5.conf configuration file should look like the contents of the following example.

Example 20-1 Edited Kerberos Client Configuration File /etc/krb5/krb5.conf

#pragma ident   "@(#)krb5.conf  1.2     99/07/20 SMI"
# Copyright (c) 1999, by Sun Microsystems, Inc.
# All rights reserved.
#
# krb5.conf template
# In order to complete this configuration file
# you will need to replace the __<name\>__ placeholders
# with appropriate values for your network.
#

[libdefaults]
        default_realm = EXAMPLE.COM
[realms]
        EXAMPLE.COM = {
                kdc = kdc.example.com
                admin_server = kdc.example.com
        }
[domain_realm]
        .example.com = EXAMPLE.COM
[logging]
        default = FILE:/var/krb5/kdc.log
        kdc = FILE:/var/krb5/kdc.log
        kdc_rotate = {

# How often to rotate kdc.log. Logs will get rotated no more
# often than the period, and less often if the KDC is not used
# frequently.
                period = 1d

# how many versions of kdc.log to keep around (kdc.log.0, kdc.log.1, ...)
                versions = 10
        }

[appdefaults]
        kinit = {
                renewable = true
                forwardable= true
        }
        gkadmin = {
                help_url =
 http://docs.sun.com:80/ab2/coll.384.1/SEAM/@AB2PageView/1195
        }

20.8.3.3 All Machines: Edit the Administration Server ACL Configuration File

Replace "___default_realm___" with "EXAMPLE.COM" in the /etc/krb5/kadm5.acl configuration file. The updated file should look like the following example.

Example 20-2 Edited Administration Server ACL Configuration File

#
# Copyright (c) 1998-2000 by Sun Microsystems, Inc.
# All rights reserved.
#
# pragma ident   "@(#)kadm5.acl  1.1     01/03/19 SMI"
*/admin@EXAMPLE.COM *

20.8.3.4 KDC Machine: Edit the KDC Server Configuration File

Edit the /etc/krb5/kdc.conf file to replace "___default_realm___" with "EXAMPLE.COM". The updated file should look like the following example.

Example 20-3 Edited KDC Server Configuration File /etc/krb5/kdc.conf

# Copyright 1998-2002 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
#ident  "@(#)kdc.conf   1.2     02/02/14 SMI"

[kdcdefaults]
        kdc_ports = 88,750

[realms]
        EXAMPLE.COM = {
                profile = /etc/krb5/krb5.conf
                database_name = /var/krb5/principal
                admin_keytab = /etc/krb5/kadm5.keytab
                acl_file = /etc/krb5/kadm5.acl
                kadmind_port = 749
                max_life = 8h 0m 0s
                max_renewable_life = 7d 0h 0m 0s
                default_principal_flags = +preauth
        }

20.8.3.5 KDC Machine: Create the KDC Database

$ /usr/sbin/kdb5_util create -r EXAMPLE.COM -s
Initializing database '/var/krb5/principal' for realm 'EXAMPLE.COM',
master key name 'K/M@EXAMPLE.COM'
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key: password
Re-enter KDC database master key to verify: password
$

20.8.3.6 KDC Machine: Create an Administration Principal and Keytab

Use the following command to create an administration user with a Principal of kws/admin@EXAMPLE.COM and service keys that will be used by the administration daemon.

$ /usr/sbin/kadmin.local
kadmin.local:  add_principal kws/admin
Enter password for principal "kws/admin@EXAMPLE.COM": secret
Re-enter password for principal "kws/admin@EXAMPLE.COM": secret
Principal "kws/admin@EXAMPLE.COM" created.
kadmin.local:  ktadd -k /etc/krb5/kadm5.keytab kadmin/kdc.example.com
Entry for principal kadmin/kdc.example.com with kvno 3, encryption type
 DES-CBC-CRC added to keytab WRFILE:/etc/krb5/kadm5.keytab.
kadmin.local:  ktadd -k /etc/krb5/kadm5.keytab changepw/kdc.example.com

Entry for principal changepw/kdc.example.com with kvno 3, encryption type
 DES-CBC-CRC added to keytab WRFILE:/etc/krb5/kadm5.keytab.
kadmin.local:  ktadd -k /etc/krb5/kadm5.keytab kadmin/changepw
Entry for principal kadmin/changepw with kvno 3, encryption type
 DES-CBC-CRC added to keytab WRFILE:/etc/krb5/kadm5.keytab.
kadmin.local:  quit$

20.8.3.7 KDC Machine: Start the Kerberos Daemons

The Kerberos daemons are managed by the Service Management Facility (SMF) framework. Run the following commands to start the KDC and administration daemons:

$ /etc/init.d/kdc start
$ /etc/init.d/kdc.master start
$

$ svcadm disable network/security/krb5kdc
$ svcadm enable network/security/krb5kdc
$ svcadm disable network/security/kadmin
$ svcadm enable network/security/kadmin
$

The KDC process appears in the process list as /usr/lib/krb5/krb5kdc. The administration daemon appears as /usr/lib/krb5/kadmind.

20.8.3.8 KDC Machine: Add Host Principals for the KDC and Oracle Unified Directory Machines

Use the following sequence of commands to add host Principals to the Kerberos database for the KDC and the directory server machines. The host Principal is used by certain Kerberos utilities such as klist.

$ /usr/sbin/kadmin -p kws/admin
Enter Password: secret
kadmin:  add_principal -randkey host/kdc.example.com
Principal "host/kdc.example.com@EXAMPLE.COM" created.
kadmin:  ktadd host/kdc.example.com
Entry for principal host/kdc.example.com with kvno 3, encryption type
 DES-CBC-CRC added to keytab WRFILE:/etc/krb5/krb5.keytab.
kadmin:  add_principal -randkey host/directory.example.com
Principal "host/directory.example.com@EXAMPLE.COM" created.
kadmin:  ktadd host/directory.example.com
Entry for principal host/directory.example.com with kvno 3, encryption type
 DES-CBC-CRC added to keytab WRFILE:/etc/krb5/krb5.keytab.
kadmin:  quit
$

20.8.3.9 KDC Machine: Add an LDAP Principal for the Directory Server

For the directory server to be able to validate the Kerberos tickets that are held by authenticating users, the directory server must have its own Principal. Currently Oracle Unified Directory is hard coded to require a Principal of ldap/fqdn@realm where fqdn is the fully-qualified domain name of the directory server and realm is the Kerberos realm. The fqdn must match the fully qualified name that is provided when you install Oracle Unified Directory. In this case, the Principal for the directory server would be ldap/directory.example.com@EXAMPLE.COM.

Use the following sequence of commands to create an LDAP Principal for the directory server:

$ /usr/sbin/kadmin -p kws/admin 
Enter Password: secret 
kadmin: add_principal -randkey ldap/directory.example.com 
Principal "ldap/directory.example.com@EXAMPLE.COM" created. 
kadmin: quit 
$

20.8.3.10 KDC Machine: Add a Test User to the KDC

To perform Kerberos authentication, the user authenticating must exist in the Kerberos database. In this example, the user has the user name kerberos-test, which means that the Kerberos Principal is kerberos-test@EXAMPLE.COM.

Create the user by using the command sequence in this example:

$ /usr/sbin/kadmin -p kws/admin
Enter Password: secret
kadmin:  add_principal kerberos-test
Enter password for principal "kerberos-test@EXAMPLE.COM": secret

Re-enter password for principal "kerberos-test@EXAMPLE.COM": secret

Principal "kerberos-test@EXAMPLE.COM" created.
kadmin:  quit
$

20.8.3.11 Directory Server Machine: Install Oracle Unified Directory

Install Oracle Unified Directory. The following table lists the installation settings that this section uses in examples.

Variable Type Example Value

Fully qualified directory server DNS name

directory.example.com

Server port

389

Suffix

dc=example,dc=com

Installation directory

/asinst_1/oud

Oracle Unified Directory server user

oud

Oracle Unified Directory server group

oud

Kerberos test principal

kerberos-test

Oracle Unified Directory keytab path

/asinst_1/oud/config/oud.keytab


Note:

The fully qualified directory server DNS name must resolve to the same IP address on all of the servers (the Oracle Unified Directory servers and the Kerberos Key Distribution Center (KDC) and client machines that expect to bind to the server using GSSAPI SASL).

20.8.3.12 Directory Server Machine: Create and Configure the Directory Server LDAP

As mentioned previously, to authenticate Kerberos users through GSSAPI, Oracle Unified Directory must have its own Principal in the KDC. The Principal information must reside in a Kerberos keytab on the directory server machine. This information must be in a file that is readable by the user account under which the directory server operates.

Note:

This step must be performed before the GSSAPI SASL mechanism handler is configured. The handler checks to make sure the keytab file exists before it will initialize.

Create a keytab file with the correct properties by using the following command sequence:

$ kadmin -p kws/admin@EXAMPLE.COM
kadmin:  addprinc -randkey ldap/directory.example.com
WARNING: no policy specified for ldap/directory.example.com@EXAMPLE.COM;
  defaulting to no policy
Principal "ldap/directory.example.com@EXAMPLE.COM" created.
kadmin:  ktadd -k asinst_1/oud/config/oud.keytab ldap/directory.example.com
Entry for principal ldap/directory.example.com with kvno 3,
  encryption type AES-128 CTS mode
  with 96-bit SHA-1 HMAC added to keytab WRFILE:asinst_1/oud/config/oud.keytab.
Entry for principal ldap/directory.example.com with kvno 3,
  encryption type Triple DES cbc mode
  with HMAC/sha1 added to keytab WRFILE:asinst_1/oud/config/oud.keytab.
Entry for principal ldap/directory.example.com with kvno 3, 
  encryption type ArcFour with HMAC/md5
  added to keytab WRFILE:asinst_1/oud/config/oud.keytab.
Entry for principal ldap/directory.example.com with kvno 3,
  encryption type DES cbc mode with RSA-MD5
  added to keytab WRFILE:asinst_1/oud/config/oud.keytab.
kadmin:  quit

Change the permissions and ownership on this custom keytab. Make the keytab owned by the user account used to run the directory server and readable only by that user:

$ chown oud:oud asinst_1/oud/config/oud.keytab
$ chmod 600 asinst_1/oud/config/oud.keytab

To allow these changes to take effect, stop and restart the directory server.

20.8.3.13 Directory Server Machine: Configure the Directory Server to Enable GSSAPI

This step shows examples of managing the GSSAPI SASL mechanism handler on the directory server host directory.example.com.

Use the dsconfig command as shown in the following example to enable the GSSAPI SASL mechanism handler on the directory server host directory.example.com and configure it to use the asinst_1/oud/config/oud.keytab.

$ dsconfig -X -n -p 4444 -h directory.example.com \
  -D "cn=directory manager" -j pwd-file
  set-sasl-mechanism-handler-prop \
  --handler-name GSSAPI \
  --set enabled:true \
  --set keytab:asinst_1/oud/config/oud.keytab \
  --set server-fqdn:directory.example.com

The last line in this command sets the GSSAPI SASL mechanism property server-fqdn to directory.example.com. This is an optional parameter, which can be left out only if it is assured that a hostname lookup on the directory server host returns the exact hostname that was used in creating the LDAP principal. Setting this property explicitly assures that the two names are the same (in this example, directory.example.com).

Confirm that the configuration is correct by examining the properties of the GSSAPI SASL mechanism handler on the directory server host directory.example.com.

$ dsconfig -X -n -p 4444 -h directory.example.com \
  -D "cn=directory manager" -j pwd-file \
  get-sasl-mechanism-handler-prop \
  --handler-name GSSAPI
Property              : Value(s)
----------------------:----------------------
enabled               : true
identity-mapper       : Regular Expression
kdc-address           : -
keytab                : asinst_1/oud/config/oud.keytab
principal-name        : -
quality-of-protection : none
realm                 : -
server-fqdn           : directory.example.com

If necessary for troubleshooting, you can use dsconfig to list the status of all the SASL mechanism handlers on the directory server host directory.example.com.

$ dsconfig -X -n -p 4444 -h directory.example.com \
  -D "cn=directory manager" -j pwd-file \
  list-sasl-mechanism-handlers
SASL Mechanism Handler : Type       : enabled
-----------------------:------------:--------
ANONYMOUS              : anonymous  : false
CRAM-MD5               : cram-md5   : true
DIGEST-MD5             : digest-md5 : true
EXTERNAL               : external   : true
GSSAPI                 : gssapi     : true
PLAIN                  : plain      : true

If necessary, you can use dsconfig to disable the GSSAPI SASL mechanism handler on the directory server host directory.example.com.

$ dsconfig -X -n -p 4444 -h directory.example.com \
  -D "cn=directory manager" -j pwd-file \
  set-sasl-mechanism-handler-prop \
  --handler-name GSSAPI \
  --set enabled:false

20.8.3.14 Directory Server Machine: Add a Test User to the Directory Server

To authenticate a Kerberos user to the directory server, there must be a directory entry for the user that corresponds to the Kerberos Principal for that user.

In a previous step, a test user was added to the Kerberos database with a Principal of kerberos-test@EXAMPLE.COM. Because of the identity mapping configuration added to the directory, the corresponding directory entry for that user must have a DN of uid=kerberos-test,ou=People,dc=example,dc=com.

Before you can add the user to the directory, you must create the file testuser.ldif with the following contents.

Example 20-4 New testuser.ldif File

dn: uid=kerberos-test,ou=People,dc=example,dc=com
changetype: add
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
uid: kerberos-test
givenName: Kerberos
sn: Test
cn: Kerberos Test
description: An account for testing Kerberos authentication through GSSAPI

Next, use ldapmodify to add this entry to the server:

$ ldapmodify -D "cn=Directory Manager" -w - -f testuser.ldif
adding new entry uid=kerberos-test,ou=People,dc=example,dc=com
$

20.8.3.15 Directory Server Machine: Obtain a Kerberos Ticket as the Test User

The test user exists in the Kerberos database, the directory server, and the KDC. Therefore, it is now possible to authenticate as the test user to the directory server over Kerberos through GSSAPI.

First, use the kinit command to get a Kerberos ticket for the user, as shown in the following example:

$ kinit kerberos-test
Password for kerberos-test@EXAMPLE.COM: secret
$

Then, use the klist command to view information about this ticket:

$ klist
Kerberos 5 ticket cache: 'API:6'
Default principal: kerberos-test@EXAMPLE.COM
Valid Starting     Expires            Service Principal
03/23/09 12:35:05  03/23/09 20:35:05  krbtgt/EXAMPLE.COM@EXAMPLE.COM
renew until 03/30/09 12:34:15
$

20.8.3.16 Client Machine: Authenticate to the Directory Server Through GSSAPI

The final step is to authenticate to the directory server by using GSSAPI. The ldapsearch utility provided with The directory server provides support for SASL authentication, including GSSAPI, DIGEST-MD5, and EXTERNAL mechanisms. However, to bind by using GSSAPI you must provide the client with the path to the SASL library. Provide the path by setting the SASL_PATH environment variable to the lib/sasl directory:

$ SASL_PATH=SASL-library
$ export SASL_PATH
$

To actually perform a Kerberos-based authentication to the directory server using ldapsearch, you must include the -o mech=GSSAPI and -o authzid=principal arguments.

You must also specify the fully qualified host name, shown here as -h directory.example.com, which must match the value of the nsslapd-localhost attribute on cn=config for the server. This use of the -h option is needed because the GSSAPI authentication process requires the host name provided by the client to match the host name provided by the server.

The following example retrieves the dc=example,dc=com entry while authenticated as the Kerberos test user account created previously:

$ ldapsearch -h directory.example.com -p 389 -o mech=GSSAPI \ -o authzid="kerberos-test@EXAMPLE.COM" -b "dc=example,dc=com" -s base "(objectClass=*)"
version: 1
dn: dc=example,dc=com
dc: example
objectClass: top
objectClass: domain
$

Check the directory server access log to confirm that the authentication was processed as expected:

$ tail -12 /local/ds/logs/access

[24/Jul/2004:00:30:47 -0500] conn=0 op=-1 msgId=-1 - fd=23 slot=23 LDAP 
        connection from 1.1.1.8 to 1.1.1.8
[24/Jul/2004:00:30:47 -0500] conn=0 op=0 msgId=1 - BIND dn="" method=sasl 
     version=3 mech=GSSAPI
[24/Jul/2004:00:30:47 -0500] conn=0 op=0 msgId=1 - RESULT err=14 tag=97 
     nentries=0 etime=0, SASL bind in progress
[24/Jul/2004:00:30:47 -0500] conn=0 op=1 msgId=2 - BIND dn="" method=sasl 
     version=3 mech=GSSAPI
[24/Jul/2004:00:30:47 -0500] conn=0 op=1 msgId=2 - RESULT err=14 tag=97 
     nentries=0 etime=0, SASL bind in progress
[24/Jul/2004:00:30:47 -0500] conn=0 op=2 msgId=3 - BIND dn="" method=sasl 
     version=3 mech=GSSAPI
[24/Jul/2004:00:30:47 -0500] conn=0 op=2 msgId=3 - RESULT err=0 tag=97 
     nentries=0 etime=0 dn="uid=kerberos-test,ou=people,dc=example,dc=com"
[24/Jul/2004:00:30:47 -0500] conn=0 op=3 msgId=4 - SRCH base="dc=example,dc=com"
     scope=0 filter="(objectClass=*)" attrs=ALL
[24/Jul/2004:00:30:47 -0500] conn=0 op=3 msgId=4 - RESULT err=0 tag=101 nentries=1 
     etime=0
[24/Jul/2004:00:30:47 -0500] conn=0 op=4 msgId=5 - UNBIND
[24/Jul/2004:00:30:47 -0500] conn=0 op=4 msgId=-1 - closing - U1
[24/Jul/2004:00:30:48 -0500] conn=0 op=-1 msgId=-1 - closed.
$

This example shows that the bind is a three-step process. The first two steps return LDAP result 14 (SASL bind in progress), and the third step shows that the bind was successful. The method=sasl and mech=GSSAPI tags show that the bind used the GSSAPI SASL mechanism. The dn="uid=kerberos-test,ou=people,dc=example,dc=com" at the end of the successful bind response shows that the bind was performed as the appropriate user.

20.8.4 Creating a Kerberos Workflow Element Using dsconfig

You can create a Kerberos workflow element by running the dsconfig create-workflow-element command:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
 create-workflow-element \
 --type KerberosAuthProviderWorkflowElement  \
 --element-name Kerberos_Test_WE  \

20.8.5 Troubleshooting Kerberos Configuration

If the Kerberos installation does not perform as expected, check the following conditions:

  • Perform a successful kinit using the test principal from the directory server machine to make sure that the directory server can authenticate to the Kerberos KDC.

  • Perform a successful kinit using the test principal from the client machines to make sure that the client machines can authenticate to the Kerberos KDC.

  • Make sure that the directory server's keytab file exists and is readable by the directory server. That is, make sure that the keytab file's ownership and permission settings are correct.

  • Make sure that the LDAP principal name in the keytab file matches the hostname that the directory server used when it was configured. The following example shows a configuration that fails:

    1. Configure GSSAPI as shown below. The value specified for the server-fqdn attribute, bad.example.com, does not match the value used in creating the keytab, directory.example.com.

      $ dsconfig -X -n -p 4444 -h directory.example.com \
        -D "cn=directory manager" -j pwd-file \
        set-sasl-mechanism-handler-prop \
        --handler-name GSSAPI \
        --set enabled:true \
        --set keytab:asinst_1/oud/config/oud.keytab \
        --set server-fqdn:bad.example.com
      
    2. From a client, attempt an ldapsearch authenticating using GSSAPI.

      $ ldapsearch -h directory.example.com \
        -o mech=GSSAPI -o authid=kerberos-test@EXAMPLE.COM \
        --searchScope base \
        -b "uid=kerberos-test,ou=people,dc=example,dc=com" "(objectclass=*)"
      An error occurred while attempting to perform GSSAPI authentication to 
        the Directory Server: \
      PrivilegedActionException(AccessController.java:-2)
      Result Code:  82 (Local Error)
      

      The search fails as expected.

    3. To determine the cause of the search failure, inspect the directory server's access log:

      $ tail asinst_1/oud/logs/access
      [23/Mar/2009:13:12:59 -0500] CONNECT conn=14 from=129.150.33.77:65076 
        to=192.168.0.199:1389 protocol=LDAP
      [23/Mar/2009:13:13:00 -0500] BIND REQ conn=14 op=0 msgID=1 
        type=SASL mechanism=GSSAPI dn=""
      [23/Mar/2009:13:13:00 -0500] BIND RES conn=14 op=0 msgID=1 
        result=49 authFailureID=1310915   authFailureReason="An unexpected error 
        occurred while trying to create an GSSAPI context:
        major code (13) No valid credentials provided, 
        minor code (-1)   Failed to find any Kerberos Key" etime=253
      [23/Mar/2009:13:13:00 -0500] DISCONNECT conn=14 reason="Client Disconnect"
      

      The message in the minor code of the last record in the access log shows that the directory server could not find a match in the keytab file.

    4. To fix the situation, disable the handler and then re-enable it with the correct information, as shown in the following example.

      $ dsconfig -X -n -p 4444 -h directory.example.com \
        -D "cn=directory manager" -j pwd-file \
        set-sasl-mechanism-handler-prop \
        --handler-name GSSAPI \
        --set enabled:false
      $ dsconfig -X -n -p 4444 -h directory.example.com 
        -D "cn=directory manager" -j pwd-file \
        set-sasl-mechanism-handler-prop \
        --handler-name GSSAPI \
        --set enabled:true \
        --set keytab:asinst_1/oud/config/oud.keytab \
        --set server-fqdn:directory.example.com
      $ ldapsearch -h directory.example.com \
        -o mech=GSSAPI \
        -o authid=kerberos-test@EXAMPLE.COM \
        --searchScope base \
        -b "uid=kerberos-test,ou=people,dc=example,dc=com" "(objectclass=*)"
      dn: uid=kerberos-test,ou=People,dc=example,dc=com
      changetype: add
      objectClass: top
      objectClass: person
      objectClass: organizationalPerson
      objectClass: inetOrgPerson
      uid: kerberos-test
      givenName: Kerberos
      sn: Test
      cn: Kerberos Test
      description: An account for testing Kerberos authentication through GSSAPI
      

20.9 Testing SSL, StartTLS, and SASL Authentication With ldapsearch

The ldapsearch utility included with the directory server is useful for testing that the server is properly configured to support SSL and StartTLS. This utility includes a number of options that are well-suited for testing in a number of different scenarios. This section describes how to use ldapsearch to test SSL and StartTLS communication, and SASL EXTERNAL authentication. The same process can be used with many of the other client tools provided with the directory server, including ldapmodify, ldapcompare, and ldapdelete.

20.9.1 ldapsearch Command Line Arguments Applicable To Security

The following command-line arguments are of particular interest when using the ldapsearch tool to communicate via SSL or StartTLS:

  • -h address or --hostname address Specifies the address of the directory server to which you want to connect. If no value is specified, the IPv4 loopback address (127.0.0.1) is used.

  • -p port or --port port Specifies the port number on which the directory server is listening for connections. If no value is specified, the standard unencrypted LDAP port (389) is used.

  • -Z or --useSSL Indicates that the client should use SSL to secure communication with the directory server. If this option is used, the value specified for the port argument must be one on which the server is listening for SSL-based connections. The default LDAPS port is 636.

  • -q or --startTLS Indicates that the client should use the StartTLS extended operation to secure communication with the directory server. If this option is used, the value specified for the port argument must be the one on which the server is listening for clear-text LDAP connections. Note that the port argument is not required if the server is listening on the default LDAP port (389).

  • -r or --useSASLExternal Indicates that the client should use SASL EXTERNAL authentication to authenticate to the directory server. If this option is used, you must also provide a keystore path.

  • -X or --trustAll Indicates that the client should blindly trust any certificate that the directory server presents. This option should not be used in conjunction with the argument used to specify the trust store path.

  • -K path or --keyStorePath path Specifies the path to the keystore that should be used if the client is to present a certificate to the directory server (for example, when using SASL EXTERNAL authentication). This should be the path to a JKS keystore.

  • -W password or --keyStorePassword password Specifies the PIN required to access the contents of the key tore. This should not be used in conjunction with the keystore password file argument.

  • --keyStorePasswordFile path Specifies the path to a file containing the PIN required to access the contents of the keystore. This should not be used in conjunction with the keystore password argument.

  • -N nickname or --certNickname nickname Specifies the nickname, or alias, of the certificate that the client should present to the directory server. The keystore path argument must also be provided. If no nickname is given, then the client will pick the first acceptable client certificate that it finds in the keystore.

  • -P path or --trustStorePath path Specifies the path to the JKS trust store file that the client should use when determining whether to trust the certificate presented by the directory server. If this argument is not given and the trustAll option is not given, then any certificate presented to the client will be displayed and the user will be prompted about whether to trust it.

  • --trustStorePassword password Specifies the password needed to access the trust store contents. In most cases, no trust store password is required. This should not be used in conjunction with the trust store password file option.

  • --trustStorePasswordFile path Specifies the path to a file containing the password needed to access the trust store contents. In most cases, no trust store password is required. This should not be used in conjunction with the trust store password option.

  • -E or --reportAuthzID Indicates that the directory server should include the authorization identity of the authenticated user in the bind response. This is useful when performing SASL authentication to determine the user to which the client certificate (or other form of SASL credentials if a mechanism other than EXTERNAL was used) was mapped.

20.9.2 Testing SSL

The following demonstrates the use of ldapsearch to communicate with a directory server using LDAP over SSL:

$ ldapsearch --hostname directory.example.com --port 1636 \
--useSSL --baseDN "" --searchScope base "(objectClass=*)"

In this case, no trust store was specified, and the --trustAll argument was also not given. Therefore, when the server presents its certificate to the client, the user will be prompted about whether that certificate should be trusted. The entire sequence might look something like:

$ ldapsearch --hostname directory.example.com --port 1636 \
--useSSL --baseDN "" --searchScope base "(objectClass=*)"

The server is using the following certificate:
Subject DN: CN=directory.example.com, O=Example Corp, C=US
Issuer DN: CN=directory.example.com, O=Example Corp, C=US
Validity: Fri Mar 02 16:48:17 CST 2007 through Thu might 31 17:48:17 CDT 2007
Do you want to trust this certificate and continue connecting to the server?
Please enter "yes" or "no":
dn:
objectClass: ds-rootDSE
objectClass: top

If the client simply wants to always trust any certificate that the server presents without being prompted, then the --trustAll argument might be provided. For example:

$ ldapsearch --hostname directory.example.com --port 1636 \
--useSSL --trustAll --baseDN "" --searchScope base \
"(objectClass=*)"

If the client has a trust store and wants to use that to determine whether to trust the server certificate, then the --trustStorePath argument might also be given. For example:

$ ldapsearch --hostname directory.example.com --port 1636 \
--useSSL --trustStorePath client.truststore --baseDN "" \
--searchScope base "(objectClass=*)"

20.9.3 Testing StartTLS

The process for using StartTLS with the ldapsearch utility is almost identical to the process for using SSL. The only differences are that you should use the port on which the server is listening for unencrypted LDAP requests and that you should indicate that StartTLS should be used instead of SSL (that is, use --useStartTLS instead of --useSSL). The following example is the equivalent of the first example given for using SSL with ldapsearch except that it uses StartTLS to secure the communication:

$ ldapsearch -h directory.example.com --port 1389 \
--useStartTLS --baseDN "" --searchScope base "(objectClass=*)"

This applies to all of the other examples given. Simply change the port number from the LDAPS port to the LDAP port, and replace the --useSSL option with --useStartTLS.

20.9.4 Testing SASL External Authentication

Note:

SASL is not supported for use with a proxy server instance.

SASL EXTERNAL authentication might be used in conjunction with either SSL or StartTLS. The primary differences are that it will be necessary to provide a keystore that contains the client certificate, the PIN required to access the contents of that keystore, and a flag indicating that the client should use SASL EXTERNAL authentication. The following example demonstrates sample usage for such a command:

$ ldapsearch --hostname directory.example.com --port 1636 \
--useSSL --keyStorePath /path/to/client.keystore \
--keyStorePasswordFile /path/to/client.keystore.pin \
--useSASLExternal --certNickName nickname \
--baseDN "" --searchScope base \
"(objectClass=*)"

When using SASL EXTERNAL authentication, it is also often useful to ask the server to return the authorization identity to ensure that the authentication is being performed as the correct user. The following demonstrates an example of this process. (Note the value reported on the line beginning with the "#" character.)

$ ldapsearch --hostname directory.example.com --port 1636 \
--useSSL --keyStorePath /path/to/client.keystore \
--keyStorePasswordFile /path/to/client.keystore.pin \
--useSASLExternal --reportAuthzID --certNickName nickname \
--baseDN "" --searchScope base "(objectClass=*)"

# Bound with authorization ID dn:uid=test.user,dc=example,dc=com
dn:
objectClass: ds-rootDSE
objectClass: top

20.10 Debugging SSL Using OpenSSL s_client Test Utility

OpenSSL provides an extremely valuable and useful diagnostic tool, called s_client, to debug SSL servers. The command implements a generic SSL/TLS client which connects to a remote host using SSL/TLS.

This utility lets you test or debug servers that use SSL/TLS with a powerful command line utility. To test the secure connections to the Oracle Unified Directory server, type the following command on the command prompt:

openssl s_client -connect <host>:<port> [options]

Here:

s_client: It is an SSL/TLS test client, which is used to test secure servers. The test client can connect to a secure port, while providing a detailed log of the steps performed during the SSL/TLS handshake.

hostname:port: This specifies the host and optional port to connect to. If not specified then an attempt is made to connect to the local host on port 443,since https uses port 443.

If connected, you can manually type in several commands, such as "GET /" and "HEAD / HTTP/1.0" for secure servers. However, if the handshake fails then there are several possible causes. If you want to know the problem you are experiencing is related to the application, firewall, certificate trust, or so on then this section describes a way to eliminate SSL from your list of usual suspects.

This section contains the following topics:

20.10.1 Scenario 1- Connection Refused

You connect the SSL client over the designated SSL port, but the connection fails. Consider the following example to demonstrate this scenario:

openssl s_client -connect localhost:<ldaps_portnumber>
connect: Connection refused
connect:errno=146

Solution

A possible solution is to check the correct value of LDAPS number in config.ldif file.

20.10.2 Scenario 2- Verify Return Code: 18 (Self Signed Certificate)

When you receive an error code 18, this implies your SSL client program failed to establish the secure connection (https) with the server due to certificate chain verification failure. The server that you using is a self-signed certificate, and you need to use a certificate chain.

Consider the following example to demonstrate this scenario:

openssl s_client -connect localhost:<ldaps-port-number>
CONNECTED(00000004)
depth=0 /C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
verify return:1
---
Certificate chain
 0 s:/C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
   i:/C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIDBjCCAsSgAwIBAgIETxRMvTALBgcqhkjOOAQDBQAwZjELMAkGA1UEBhMCY2Ex
EzARBgNVBAgTCkNhbGlmb3JuaWExCzAJBgNVBAcTAlNGMQ8wDQYDVQQKEwZPcmFj
bGUxDTALBgNVBAsTBGxkYXAxFTATBgNVBAMTDHNlcnZlciBhZG1pbjAeFw0xMjAx
MTYxNjEzNDlaFw0xMjA0MTUxNjEzNDlaMGYxCzAJBgNVBAYTAmNhMRMwEQYDVQQI
EwpDYWxpZm9ybmlhMQswCQYDVQQHEwJTRjEPMA0GA1UEChMGT3JhY2xlMQ0wCwYD
VQQLEwRsZGFwMRUwEwYDVQQDEwxzZXJ2ZXIgYWRtaW4wggG4MIIBLAYHKoZIzjgE
ATCCAR8CgYEA/X9TgR11EilS30qcLuzk5/YRt1I870QAwx4/gLZRJmlFXUAiUftZ
PY1Y+r/F9bow9subVWzXgTuAHTRv8mZgt2uZUKWkn5/oBHsQIsJPu6nX/rfGG/g7
V+fGqKYVDwT7g/bTxR7DAjVUE1oWkTL2dfOuK2HXKu/yIgMZndFIAccCFQCXYFCP
FSMLzLKSuYKi64QL8Fgc9QKBgQD34aCF1ps93su8q1w2uFe5eZSvu/o66oL5V0wL
PQeCZ1FZV4661FlP5nEHEIGAtEkWcSPoTCgWE7fPCTKMyKbhPBZ6i1R8jSjgo64e
K7OmdZFuo38L+iE1YvH7YnoBJDvMpPG+qFGQiaiD3+Fa5Z8GkotmXoB7VSVkAUw7
/s9JKgOBhQACgYEAw+2EIpmwy0rqtHbNb6gxbEtW0hplXXQdHEQp24brde1jt1qv
LDz/c8KR+fVxqvTxAmurGt1qbrhjXcUxi1KdaLnLnLXTCoD+ZLQU+F6B/TNmfrxb
AJmHtmoZsFtNCBTC++FClXtconKyXjEWnKMw7fEb+gNY3eTUrcyIpa/YEbYwCwYH
KoZIzjgEAwUAAy8AMCwCFEtf5+J77Q/5fI6bZ7k3D1rdbw6UAhQkWGmp8VOiMdUg
5K4wK7Y7cC0wSQ==
-----END CERTIFICATE-----
subject=/C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
issuer=/C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
---
Acceptable client certificate CA names
/C=FR/ST=France/L=Grenoble/O=Oracle/OU=OUD/CN=CA Certificate
/C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=user.41
/C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
---
SSL handshake has read 1594 bytes and written 312 bytes
---
New, TLSv1/SSLv3, Cipher is EDH-DSS-DES-CBC3-SHA
Server public key is 1024 bit
SSL-Session:
    Protocol  : TLSv1
    Cipher    : EDH-DSS-DES-CBC3-SHA
    Session-ID: 4F16C3F27655013F71AE2120134A8D1AFE966A1D9233618507DEFE9C607417AA
    Session-ID-ctx:
    Master-Key: 57BDB7FCA9A293E65274AA7CDD0E7CC48AA227806FC2B54C9F9E36BB26D32943FC115CE4FF9A605B6B6BD237026F3D0E
    Key-Arg   : None
    Start Time: 1326892018
    Timeout   : 300 (sec)
    Verify return code: 18 (self signed certificate)

Solution

You must import in the server key store, signed certificate reply, and CA certificate.

20.10.3 Scenario 3 - Verify Return Code: 0 (ok)

If a connection is successfully established with an SSL server, then you receive a return code 0. This implies that any data received from the server is displayed and any key presses will be sent to the server. In addition, the certificate chain in use is also displayed.

Consider the following example to demonstrate a working session:

openssl s_client -connect localhost:8636 -verify 250 \
-key $SERVER_SSL/config/keystore   -CApath $CA_SSL -CAfile ca-cert.pem
 
-key is specifying the path to teh server keystore
-CAPath/-CAfile allows to locate CA certificate (pem format)
 
verify depth is 250
CONNECTED(00000004)
depth=1 /C=FR/ST=France/L=Grenoble/O=Oracle/OU=OUD/CN=CA Certificate
verify return:1
depth=0 /C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
verify return:1
---
Certificate chain
 0 s:/C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
   i:/C=FR/ST=France/L=Grenoble/O=Oracle/OU=OUD/CN=CA Certificate
 1 s:/C=FR/ST=France/L=Grenoble/O=Oracle/OU=OUD/CN=CA Certificate
   i:/C=FR/ST=France/L=Grenoble/O=Oracle/OU=OUD/CN=CA Certificate
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIDYDCCAsmgAwIBAgIFAJbW4rkwDQYJKoZIhvcNAQEFBQAwaTELMAkGA1UEBhMC
RlIxDzANBgNVBAgTBkZyYW5jZTERMA8GA1UEBxMIR3Jlbm9ibGUxDzANBgNVBAoT
Bk9yYWNsZTEMMAoGA1UECxMDT1VEMRcwFQYDVQQDEw5DQSBDZXJ0aWZpY2F0ZTAe
Fw0xMjAxMTcxMDQ5MjdaFw0xMjA0MTcxMDQ5MjdaMGYxCzAJBgNVBAYTAmNhMRMw
EQYDVQQIEwpDYWxpZm9ybmlhMQswCQYDVQQHEwJTRjEPMA0GA1UEChMGT3JhY2xl
MQ0wCwYDVQQLEwRsZGFwMRUwEwYDVQQDEwxzZXJ2ZXIgYWRtaW4wggG3MIIBLAYH
KoZIzjgEATCCAR8CgYEA/X9TgR11EilS30qcLuzk5/YRt1I870QAwx4/gLZRJmlF
XUAiUftZPY1Y+r/F9bow9subVWzXgTuAHTRv8mZgt2uZUKWkn5/oBHsQIsJPu6nX
/rfGG/g7V+fGqKYVDwT7g/bTxR7DAjVUE1oWkTL2dfOuK2HXKu/yIgMZndFIAccC
FQCXYFCPFSMLzLKSuYKi64QL8Fgc9QKBgQD34aCF1ps93su8q1w2uFe5eZSvu/o6
6oL5V0wLPQeCZ1FZV4661FlP5nEHEIGAtEkWcSPoTCgWE7fPCTKMyKbhPBZ6i1R8
jSjgo64eK7OmdZFuo38L+iE1YvH7YnoBJDvMpPG+qFGQiaiD3+Fa5Z8GkotmXoB7
VSVkAUw7/s9JKgOBhAACgYA8N/yzB5rrvNOPhOrea1RNCRePn0bMvXkDpfUs8dpH
z1qQog4soloAhojIYJYA3OGqKr3ryNnfB0B8lePQ1ZaJgkURqOjiVKF6xv5FmnuM
C1uwiTfr/9IKijiy8oCKKKSLTB5lY3Rk0o03D+LrqgLp27A41WvvhGo4djBqXse1
OTANBgkqhkiG9w0BAQUFAAOBgQBzTpgFc1YCpo8QKeoDBRag4tn2y8BzkeLeLMgy
gQAYCGNjJjrV0ChYKMJnqLPCrP9+/Otyj9ZByn9+T1Jx9/khuh9oNXCwF5FUE5VE
gkn3kPo1LdLBqKpfUSeFcYNJDQDhtThVwEq05Ifm+JuCCM4J3BbFuZpJM5xnbcIZ
mjcn5w==
-----END CERTIFICATE-----
subject=/C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
issuer=/C=FR/ST=France/L=Grenoble/O=Oracle/OU=OUD/CN=CA Certificate
---Verify return code: 0 (ok)
Acceptable client certificate CA names
/C=FR/ST=France/L=Grenoble/O=Oracle/OU=OUD/CN=CA Certificate
/C=fr/ST=Isere/L=Montbonnot/O=Oracle/OU=ldap/CN=server_8839
---
SSL handshake has read 2179 bytes and written 312 bytes
---
New, TLSv1/SSLv3, Cipher is EDH-DSS-DES-CBC3-SHA
Server public key is 1024 bit
SSL-Session:
    Protocol  : TLSv1
    Cipher    : EDH-DSS-DES-CBC3-SHA
    Session-ID: 4F16C59B172D329E44AF199B4E49B14E54163AAF783A68FBD48556FCB06A9238
    Session-ID-ctx:
    Master-Key: 21CC1BBF638FFDAF16E5DBAB337728D029F0125D483636EF7590BE3005DDA96AEAF60DE88172DE925806F633EB09ACBE
    Key-Arg   : None
    Start Time: 1326892443
    Timeout   : 300 (sec)
    Verify return code: 0 (ok)

20.10.4 Scenario 4 - SSLHandshakeException

When you try to establish a server secure connection, the following error message is issued by the ldapsearch:

ldapsearch  -p 7636 -D "cn=Directory Manager" -w secret12  -P config/truststore -Z -b dc=example,dc=com uid=user.0 Cannot send the simple bind request:  SSLHandshakeException(sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target)

This error appears because the server certificate is self signed certificate and not a certificate chain. You will receive an error code 18.

The following demonstrates an example of this process.

openssl s_client -connect localhost:7636
CONNECTED(00000004)
depth=0 /C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
verify return:1
---
Certificate chain
 0 s:/C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
   i:/C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIDBjCCAsSgAwIBAgIETxRMvTALBgcqhkjOOAQDBQAwZjELMAkGA1UEBhMCY2Ex
EzARBgNVBAgTCkNhbGlmb3JuaWExCzAJBgNVBAcTAlNGMQ8wDQYDVQQKEwZPcmFj
bGUxDTALBgNVBAsTBGxkYXAxFTATBgNVBAMTDHNlcnZlciBhZG1pbjAeFw0xMjAx
MTYxNjEzNDlaFw0xMjA0MTUxNjEzNDlaMGYxCzAJBgNVBAYTAmNhMRMwEQYDVQQI
EwpDYWxpZm9ybmlhMQswCQYDVQQHEwJTRjEPMA0GA1UEChMGT3JhY2xlMQ0wCwYD
VQQLEwRsZGFwMRUwEwYDVQQDEwxzZXJ2ZXIgYWRtaW4wggG4MIIBLAYHKoZIzjgE
ATCCAR8CgYEA/X9TgR11EilS30qcLuzk5/YRt1I870QAwx4/gLZRJmlFXUAiUftZ
PY1Y+r/F9bow9subVWzXgTuAHTRv8mZgt2uZUKWkn5/oBHsQIsJPu6nX/rfGG/g7
V+fGqKYVDwT7g/bTxR7DAjVUE1oWkTL2dfOuK2HXKu/yIgMZndFIAccCFQCXYFCP
FSMLzLKSuYKi64QL8Fgc9QKBgQD34aCF1ps93su8q1w2uFe5eZSvu/o66oL5V0wL
PQeCZ1FZV4661FlP5nEHEIGAtEkWcSPoTCgWE7fPCTKMyKbhPBZ6i1R8jSjgo64e
K7OmdZFuo38L+iE1YvH7YnoBJDvMpPG+qFGQiaiD3+Fa5Z8GkotmXoB7VSVkAUw7
/s9JKgOBhQACgYEAw+2EIpmwy0rqtHbNb6gxbEtW0hplXXQdHEQp24brde1jt1qv
LDz/c8KR+fVxqvTxAmurGt1qbrhjXcUxi1KdaLnLnLXTCoD+ZLQU+F6B/TNmfrxb
AJmHtmoZsFtNCBTC++FClXtconKyXjEWnKMw7fEb+gNY3eTUrcyIpa/YEbYwCwYH
KoZIzjgEAwUAAy8AMCwCFEtf5+J77Q/5fI6bZ7k3D1rdbw6UAhQkWGmp8VOiMdUg
5K4wK7Y7cC0wSQ==
-----END CERTIFICATE-----
subject=/C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
issuer=/C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
---
Acceptable client certificate CA names
/C=FR/ST=France/L=Grenoble/O=Oracle/OU=OUD/CN=CA Certificate
/C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=user.41
/C=ca/ST=California/L=SF/O=Oracle/OU=ldap/CN=server admin
---
SSL handshake has read 1594 bytes and written 312 bytes
---
New, TLSv1/SSLv3, Cipher is EDH-DSS-DES-CBC3-SHA
Server public key is 1024 bit
SSL-Session:
    Protocol  : TLSv1
    Cipher    : EDH-DSS-DES-CBC3-SHA
    Session-ID: 4F16C3F27655013F71AE2120134A8D1AFE966A1D9233618507DEFE9C607417AA
    Session-ID-ctx:
    Master-Key: 57BDB7FCA9A293E65274AA7CDD0E7CC48AA227806FC2B54C9F9E36BB26D32943FC115CE4FF9A605B6B6BD237026F3D0E
    Key-Arg   : None
    Start Time: 1326892018
    Timeout   : 300 (sec)
    Verify return code: 18 (self signed certificate)

Solution

Perform the following steps to fix the issue:

  1. Import the CA certificate into the server keystore.

    keytool -importcert -alias ca-cert -keystore config/keystore -storetype JKS -file $CA_SSL/ca-cert.pem
    Enter keystore password:
    Owner: CN=CA Certificate, OU=OUD, O=Oracle, L=Grenoble, ST=France, C=FR
    Issuer: CN=CA Certificate, OU=OUD, O=Oracle, L=Grenoble, ST=France, C=FR
    Serial number: 96b69e65
    Valid from: Wed Jan 04 15:51:37 MET 2012 until: Mon Sep 04 16:51:37 MEST 2428
    Certificate fingerprints:
             MD5:  D0:5B:C8:2A:3D:3B:09:07:5A:29:62:E3:27:99:4E:D4
             SHA1: E4:C9:BB:B7:5B:49:C7:7E:BF:8B:C3:C3:DC:DF:29:E7:74:A0:66:03
             Signature algorithm name: SHA1withRSA
             Version: 3
    Trust this certificate? [no]:  yes
    Certificate was added to keystore
    
  2. Import the signed server certificate reply into the server keystore.

    keytool -importcert -trustcacerts -alias server-cert -keystore config/keystore -storetype JKS -file server-cert.pem Enter keystore password:
    Certificate reply was installed in keystore
    
  3. List certificates in the LDAP server keystore.

    keytool -list -keystore config/keystore -storepass secret12 -v
     
    Keystore type: JKS
    Keystore provider: SUN
     
    Your keystore contains 2 entries
     
    Alias name: ca-cert
    Creation date: Jan 18, 2012
    Entry type: trustedCertEntry
     
    Owner: CN=CA Certificate, OU=OUD, O=Oracle, L=Grenoble, ST=France, C=FR
    Issuer: CN=CA Certificate, OU=OUD, O=Oracle, L=Grenoble, ST=France, C=FR
    Serial number: 96b69e65
    Valid from: Wed Jan 04 15:51:37 MET 2012 until: Mon Sep 04 16:51:37 MEST 2428
    Certificate fingerprints:
             MD5:  D0:5B:C8:2A:3D:3B:09:07:5A:29:62:E3:27:99:4E:D4
             SHA1: E4:C9:BB:B7:5B:49:C7:7E:BF:8B:C3:C3:DC:DF:29:E7:74:A0:66:03
             Signature algorithm name: SHA1withRSA
             Version: 3
    
  4. Verify the connection with a ldapsearch request over SSL.

    ldapsearch  -p 7636 -D "cn=Directory Manager" -w secret12  -P config/truststore -Z -b dc=example,dc=com uid=user.0
    dn: uid=user.0,ou=People,dc=example,dc=com
    postalAddress: Aaccf Amar$01251 Chestnut Street$Panama City, DE  50369
    postalCode: 50369
    uid: user.0
    description: This is the description for Aaccf Amar.
    userPassword: {SSHA}vVIy4fjEUyt0L8GSVzX+VrJKEgGASLkeCvL1ng==
    employeeNumber: 0
    initials: ASA
    givenName: Aaccf
    objectClass: person
    objectClass: inetorgperson
    objectClass: organizationalperson
    objectClass: top
    pager: +1 779 041 6341
    mobile: +1 010 154 3228
    cn: Aaccf Amar
    telephoneNumber: +1 685 622 6202
    sn: Amar
    street: 01251 Chestnut Street
    homePhone: +1 225 216 5900
    mail: user.0@maildomain.net
    l: Panama City
    st: DE
    
  5. Access the log.

    [18/Jan/2012:16:39:24 +0100] CONNECT conn=1 from=127.0.0.1:46726 to=127.0.0.1:7636 protocol=LDAPS
    [18/Jan/2012:16:39:24 +0100] BIND REQ conn=1 op=0 msgID=1 type=SIMPLE dn="cn=Directory Manager"
    [18/Jan/2012:16:39:24 +0100] BIND RES conn=1 op=0 msgID=1 result=0 authDN="cn=Directory Manager,cn=Root DNs,cn=config" etime=31
    [18/Jan/2012:16:39:24 +0100] SEARCH REQ conn=1 op=1 msgID=2 base="dc=example,dc=com" scope=wholeSubtree filter="(uid=user.0)" attrs="ALL"
    [18/Jan/2012:16:39:24 +0100] SEARCH RES conn=1 op=1 msgID=2 result=0 nentries=1 etime=18
    [18/Jan/2012:16:39:24 +0100] UNBIND REQ conn=1 op=2 msgID=3
    [18/Jan/2012:16:39:24 +0100] DISCONNECT conn=1 reason="Client Disconnect"
    

20.10.5 Scenario 5 - SASL EXTERNAL Bind Request Could Not Be Processed

When you try to perform OUD SASL client external authentication over SSL the following error message appears:

ldapsearch -p 7636 -Z -K /export/home/oud/security/client/config/keystore -W secret12 -P /export/home/oud/security/client/config/truststore --trustStorePassword secret12 -N user.41-cert --useSASLExternal -b dc=example,dc=com uid=user.0
The SASL EXTERNAL bind attempt failed
Result Code:  49 (Invalid Credentials)

When you view the access log, then the following message is shown:

CONNECT conn=2 from=127.0.0.1:46763 to=127.0.0.1:7636 protocol=LDAPS
[18/Jan/2012:17:48:44 +0100] BIND REQ conn=2 op=0 msgID=1 type=SASL mechanism=EXTERNAL dn=""
[18/Jan/2012:17:48:44 +0100] BIND RES conn=2 op=0 msgID=1 result=49 authFailureID=1245310 authFailureReason="The SASL EXTERNAL bind request could not be processed because the client did not present a certificate chain during SSL/TLS negotiation" etime=6
[18/Jan/2012:17:48:44 +0100] DISCONNECT conn=2 reason="Client Disconnect"

This error appears because the client certificate is not a valid certificate chain.

Solution

Perform the following steps to fix this issue:

  1. Import the CA certificate into the client keystore.

    keytool -importcert -alias ca-cert -keystore config/keystore \
    -storetype JKS -file $CA_SSL/ca-cert.pem
    Enter keystore password:
    Owner: CN=CA Certificate, OU=OUD, O=Oracle, L=Grenoble, ST=France, C=FR
    Issuer: CN=CA Certificate, OU=OUD, O=Oracle, L=Grenoble, ST=France, C=FR
    Serial number: 96b69e65
    Valid from: Wed Jan 04 15:51:37 MET 2012 until: Mon Sep 04 16:51:37 MEST 2428
    Certificate fingerprints:
             MD5:  D0:5B:C8:2A:3D:3B:09:07:5A:29:62:E3:27:99:4E:D4
             SHA1: E4:C9:BB:B7:5B:49:C7:7E:BF:8B:C3:C3:DC:DF:29:E7:74:A0:66:03
             Signature algorithm name: SHA1withRSA
             Version: 3
    Trust this certificate? [no]:  yes
    Certificate was added to keystore
    
  2. Import the user signed reply certificate into the client keystore.

    keytool -importcert -trustcacerts -alias user.41-cert -keystore config/keystore -storetype JKS -file user.41-cert.pem -storepass secret12
    Certificate reply was installed in keystore
    
  3. Run the ldap command.

    ldapsearch -p 7636 -Z -K /export/home/oud/security/client/config/keystore -W secret12 -P /export/home/oud/security/client/config/truststore --trustStorePassword secret12 -N user.41-cert --useSASLExternal -b dc=example,dc=com uid=user.0
    dn: uid=user.0,ou=People,dc=example,dc=com
    postalAddress: Aaccf Amar$01251 Chestnut Street$Panama City, DE  50369
    postalCode: 50369
    uid: user.0
    description: This is the description for Aaccf Amar.
    employeeNumber: 0
    initials: ASA
    givenName: Aaccf
    objectClass: person
    objectClass: inetorgperson
    objectClass: organizationalperson
    objectClass: top
    pager: +1 779 041 6341
    mobile: +1 010 154 3228
    cn: Aaccf Amar
    telephoneNumber: +1 685 622 6202
    sn: Amar
    street: 01251 Chestnut Street
    homePhone: +1 225 216 5900
    mail: user.0@maildomain.net
    l: Panama City
    st: DE
    
  4. Validate the log.

    [18/Jan/2012:18:04:49 +0100] CONNECT conn=3 from=127.0.0.1:46777 to=127.0.0.1:7636 protocol=LDAPS
    [18/Jan/2012:18:04:49 +0100] BIND REQ conn=3 op=0 msgID=1 type=SASL mechanism=EXTERNAL dn=""
    [18/Jan/2012:18:04:49 +0100] BIND RES conn=3 op=0 msgID=1 result=0 authDN="uid=user.41,ou=People,dc=example,dc=com" etime=37
    [18/Jan/2012:18:04:49 +0100] SEARCH REQ conn=3 op=1 msgID=2 base="dc=example,dc=com" scope=wholeSubtree filter="(uid=user.0)" attrs="ALL"
    [18/Jan/2012:18:04:49 +0100] SEARCH RES conn=3 op=1 msgID=2 result=0 nentries=1 etime=15
    [18/Jan/2012:18:04:49 +0100] UNBIND REQ conn=3 op=2 msgID=3
    [18/Jan/2012:18:04:49 +0100] DISCONNECT conn=3 reason="Client Disconnect"
    

20.11 Debugging SSL or TLS Using Java Debug Information

You can troubleshoot network Traffic for SSL or TLS connections using Java debug information.

There are situations when the only way to analyze SSL is to trace network access. Oracle Unified Directory allows you to debug SSL by adding -Djavax.net.debug=all option to the server in the config/java.properties file.

A sample debug output is as follows:

server.core.DirectoryServer (alert type org.opends.server.DirectoryServerStarted, alert ID 458887):  The Directory Server has started successfully
***
found key for : server-cert
chain [0] = [
[
  Version: V3
  Subject: CN=server admin, OU=ldap, O=mycompany, L=City1, ST=Country1, C=ca
  Signature Algorithm: SHA1withRSA, OID = 1.2.840.113549.1.1.5
 
  Key:  SunPKCS11-Solaris DSA public key, 1024 bits (id 22714576, session object)
  y: 137585178298829672773992262717400783035252676067753730258902133887472765737596162865068864757751081632128325087288240737049199605991868092341784810001823893557764102282007356730105011462039459191437293297725512863853468183519862577505401958362086546885405080570540575677103845462467633475547155894544465662390
  p: 178011905478542266528237562450159990145232156369120674273274450314442865788737020770612695252123463079567156784778466449970650770920727857050009668388144034129745221171818506047231150039301079959358067395348717066319802262019714966524135060945913707594956514672855690606794135837542707371727429551343320695239
  q: 864205495604807476120572616017955259175325408501
  g: 174068207532402095185811980123523436538604490794561350978495831040599953488455823147851597408940950725307797094915759492368300574252438761037084473467180148876118103083043754985190983472601550494691329488083395492313850000361646482644608492304078721818959999056496097769368017749273708962006689187956744210730
  Validity: [From: Mon Jan 16 17:15:45 MET 2012,
             To: Mon Apr 16 18:15:45 MEST 2012]
  Issuer: CN=CA Certificate, OU=OUD, O=mycompany, L=City2, ST=Country2, C=FR
  SerialNumber: [96d4f0dc]
 
]
  Algorithm: [SHA1withRSA]
  Signature:
0000: 72 F6 7E 93 2B 87 B9 C7   39 51 4C D2 A7 B0 AA 36  r...+...9QL....6
0010: B8 0F BA C4 6E 43 70 72   81 50 09 7A 88 05 16 A2  ....nCpr.P.z....
0020: 1C 96 C2 49 B3 0A F9 AB   2B 4B 8D 59 4C BA 58 C9  ...I....+K.YL.X.
0030: EF B9 48 58 A7 C5 BB B5   0E 64 51 CF BC 58 DA 71  ..HX.....dQ..X.q
0040: E1 F7 2E A4 1D 1B FC D5   4F B2 70 B0 78 F4 FB E6  ........O.p.x...
0050: C4 6A 6A E0 DE B0 F5 98   7B 09 A9 A4 9D 17 4C F5  .jj...........L.
0060: 9F 06 07 E1 09 81 77 9E   41 3C 02 4C FB D8 94 ED  ......w.A<.L....
0070: 36 6A 65 5A 96 2C AE A4   86 83 66 63 BC 3C 8C 47  6jeZ.,....fc.<.G
 
]

The preceding information is provided in addition to the Oracle Unified Directory debug log text.

This section describes how to work with SSL debug recording and contains the following topics:

20.11.1 Enabling SSL Debug Recording

Perform the following steps to enable SSL debug recording:

  1. Update the start-ds.java-args property in the config/java.properties file with:

    start-ds.java-args=-server -Djavax.net.debug=all
    
  2. Run the dsjavaproperties command as described in Section A.2.5, "dsjavaproperties."

  3. Stop the server instance using the stop-ds command.

  4. Restart the server instance using the start-ds command.

Note:

The SSL debug information is logged in the logs/server.out file.

20.11.2 Disabling SSL Debug Recording

Perform the following steps to disable SSL debug recording:

  1. Delete the -Djavax.net.debug=all property from java.properties file.

    start-ds.java-args=-server
    
  2. Run the dsjavaproperties command as described in Section A.2.5, "dsjavaproperties."

  3. Stop the server instance using the stop-ds command.

  4. Restart the server instance using the start-ds command.

20.12 Controlling Connection Access Using Allowed and Denied Rules

You can use connection handler allowed and denied client rules to control which hosts can make TCP connections to the server. Connection handlers are responsible for accepting connections to the server.

The different types of connection handlers and their configuration properties are presented in this section and include the following:

Note:

Both IPv4 and IPv6 addresses are supported.

20.12.1 Property Syntax of Allowed and Denied Client Rules

The allowed-client and denied-client properties share the same syntax to perform pattern matching against IP (IPv4 or IPv6) addresses and host names.

The following syntaxes are supported:

  • IP address - The IP address of the clients to be allowed or denied can be specified in the rule. For example:

    ds-cfg-denied-client:   192.168.5.6
    ds-cfg-allowed-client:  2001:fecd:ba23:cd1f:dcb1:1010:9234:4088
    
  • IP address with CIDR notation - A range of IP addresses can be allowed or denied by specifying an IP address using CIDR notation. For example:

    ds-cfg-denied-client:   192.168.5.6/28
    ds-cfg-allowed-client:  2001:0db8:1234::/48
    

    The first denies clients in the range 192.168.5.0 - 192.168.5.15 and the second allows clients in the range 2001:0db8:1234:0000:0000:0000:0000:0000 - 2001:0db8:1234:ffff:ffff:ffff:ffff:ffff.

  • IP address with '*' notation - A range of IP addresses (IPv4 only) can be allowed or denied by specifying an IP address with a '*' character to match parts of the IP address. For example:

    ds-cfg-denied-client:   192.168.5.*
    ds-cfg-allowed-client:   129.45.*.*
    

    The first example denies clients with IP addresses starting with 192.168.5 and the second allows clients with IP address starting with 129.45. Notice that the second example uses multiple match characters. To allow all IP addresses to match, the rule would look like:

    ds-cfg-denied-client:   *.*.*.*
    
  • DNS names - Clients can be restricted by DNS name. For example to restrict clients with the host name foo.example.com, enter:

    ds-cfg-denied-client:   foo.example.com
    
  • DNS names with pattern matching - This is similar to IP address pattern matching. The property can specify the '*' character to match parts of the DN name:

    ds-cfg-allowed-client: foo.*.test.com
    

    The property allows clients with DN names such as: foo.bar.test.com or foo.foobar.test.com. To only match DNS names ending in a suffix the property would be:

    ds-cfg-allowed-client: .example.com
    

    This property allows clients with DNS names such as: test.example.com or test.me.example.com.

    Note:

    Be careful when you use the DNS properties because the host name resolution depends on the server name service configuration.

20.12.2 Configuring Allowed and Denied Client Rules

Each connection handler needs to have its own set of rules. For example:

dn: cn=LDAP Connection Handler,cn=Connection Handlers,cn=config
objectClass: top
objectClass: ds-cfg-connection-handler
objectClass: ds-cfg-ldap-connection-handler
cn: LDAP Connection Handler
ds-cfg-java-class: org.opends.server.protocols.ldap.LDAPConnectionHandler
ds-cfg-enabled: true
ds-cfg-listen-address: 0.0.0.0
ds-cfg-listen-port: 389
ds-cfg-accept-backlog: 128
ds-cfg-allow-ldap-v2: true
ds-cfg-keep-stats: true
ds-cfg-use-tcp-keep-alive: true
ds-cfg-use-tcp-no-delay: true
ds-cfg-allow-tcp-reuse-address: true
ds-cfg-send-rejection-notice: true
ds-cfg-max-request-size: 5 megabytes
ds-cfg-max-blocked-write-time-limit: 2 minutes
ds-cfg-num-request-handlers: 2
ds-cfg-allow-start-tls: false
ds-cfg-use-ssl: false
ds-cfg-ssl-client-auth-policy: optional
ds-cfg-ssl-cert-nickname: server-cert
ds-cfg-denied-client: *.example.com
ds-cfg-denied-client:  129.45.*.*
ds-cfg-denied-client:   192.168.5.6

dn: cn=LDAPS Connection Handler,cn=Connection Handlers,cn=config
objectClass: top
objectClass: ds-cfg-connection-handler
objectClass: ds-cfg-ldap-connection-handler
cn: LDAPS Connection Handler
ds-cfg-java-class: org.opends.server.protocols.ldap.LDAPConnectionHandler
ds-cfg-enabled: true
ds-cfg-listen-address: 0.0.0.0
ds-cfg-listen-port: 636
ds-cfg-accept-backlog: 128
ds-cfg-allow-ldap-v2: true
ds-cfg-keep-stats: true
ds-cfg-use-tcp-keep-alive: true
ds-cfg-use-tcp-no-delay: true
ds-cfg-allow-tcp-reuse-address: true
ds-cfg-send-rejection-notice: true
ds-cfg-max-request-size: 5 megabytes
ds-cfg-max-blocked-write-time-limit: 2 minutes
ds-cfg-num-request-handlers: 2
ds-cfg-allow-start-tls: false
ds-cfg-use-ssl: true
ds-cfg-ssl-client-auth-policy: optional
ds-cfg-ssl-cert-nickname: server-cert
ds-cfg-key-manager-provider: cn=JKS,cn=Key Manager Providers,cn=config
ds-cfg-trust-manager-provider: cn=JKS,cn=Trust Manager Providers,cn=config
ds-cfg-allowed-client: .example.com
ds-cfg-allowed-client: foo.*.test.com
ds-cfg-allowed-client: 192.168.6.7/22

Use the dsconfig command to manage the allowed and denied properties for each connection handler. For example:

$ dsconfig -n -X -p 4444 -D "cn=directory manager" -j pwd-file \
  set-connection-handler-prop   --handler-name "LDAPS Connection Handler" \
  --set denied-client:.example.com \
  --set allowed-client:192.168.1.6/17

Note:

Denied rules are applied before the allowed rules.

20.13 Configuring Unlimited Strength Cryptography

To configure unlimited strength cryptography, you must download the Java Cryptography Extension Unlimited Strength Jurisdiction policy files for missing cryptography support. Perform the following steps to download and install the policy file for configuring unlimited strength cryptography:

  1. Download the Java Cryptography Extension Unlimited Strength Jurisdiction policy files from the following Web page

    http://www.oracle.com/technetwork/java/javase/downloads/index.html

  2. Perform the installation instructions described in the README.txt file that is part of the downloaded zip.

    Java Cryptography Extension Unlimited Strength Jurisdiction policy files are now installed.

  3. Stop the Oracle Unified Directory server, and then restart.