Configuring Security Between Clients and Servers

26 Configuring Security Between Clients and Servers

You can have several mechanisms to secure traffic between the client and the server.

The following topics describe the configuring secure traffic between the client and the server:

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

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

26.1 Getting SSL Up and Running Quickly

Oracle Unified Directory provides several 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 Configuring Key Manager Providers.
For detailed information about truststores, see 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 Configuring Key Manager Providers.

26.1.1 Setting Up SSL Using an Existing Private Key and Certificate

If you already have a security certificate that was generated with the openssl command-line tool, you must create keystores and update the certificate before you can use it with Oracle Unified Directory.

In the following example, these certificate files already exist:

ca.crt

Certificate authority public key (certificate)
mycert.key

The private key of the previously generated certificate
mycert.crt

The public key of the previously generated certificate

To update the existing security certificate:

Create a PKCS12 keystore containing both public and private keys.
In this example, keystore.p12 is the PKCS12 keystore you are creating:
```
$ openssl pkcs12 -export -out keystore.p12 -inkey 
mycert.key -in mycert.crt -chain -CAfile ca.crt 
-password file:<FILE CONTAINING THE PASSWORD FOR THE PKCS12 KEYSTORE>
```
You can use the generated PKCS12 keystore as described in Using the PKCS #12 Key Manager Provider.

Or you can complete step 2 and step 3 to import the certificate into a JKS keystore and update the certificate alias.
Create a JKS keystore by importing the certificate from the PKCS12 keystore.
In this example, keystore.jks is the JKS keystore you are creating. You must specify 1 as an alias. The alias is required in the step 3.

If you want to update the alias of the certificate but continue to store the certificate in a PKCS12 keystore, add the argument -storetype PKCS12 when invoking the following keytool command:
```
$ keytool -importkeystore -deststorepass <PASSWORD OF THE JKS KEYSTORE>
 -destkeypass <PASSWORD OF THE JKS KEY> -destkeystore keystore.jks 
-srckeystore keystore.p12 -srcstoretype PKCS12 -srcstorepass 
<PASSWORD OF THE PKCS12 KEYSTORE> -alias 1
```
Update the alias of the certificate from 1 to my-server-cert.
If you want to update the alias of the certificate but continue to store the certificate in a PKCS12 keystore, add the argument -storetype PKCS12 when invoking the following keytool command:
```
$ keytool -changealias -keystore keystore.jks -alias 1 -destalias my-server-cert -storepass <PASSWORD OF THE JKS KEYSTORE>
```

Now you can use the JKS keystore keystore.jks and the certificate it contains to configure the key manager provider. See Configuring the JKS Key Manager Provider.

26.1.2 Accepting SSL-Based Connections Using a Self-Signed 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.

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.

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.
- -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.
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 and private key password, enter the same passwords that you provided in the previous step.

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

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

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
--set key-store-pin:KEYSTORE_PASSWORD
$ dsconfig -D "cn=directory manager" -j pwd-file -X -n
set-trust-manager-provider-prop --provider-name JKS --set enabled:true
--set trust-store-pin:TRUSTSTORE_PASSWORD
$ dsconfig -D "cn=directory manager" -j pwd-file -X -n 
  set-connection-handler-prop --handler-name "LDAPS Connection Handler" 
  --set trust-manager-provider:JKS --set key-manager-provider:JKS 
  --set listen-port:1636 --set enabled:true
```
Note:
You need to use the argument, --reset key-store-pin-file along with other arguments for 12.2.1.4.210406 BP only.
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 must 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 you have specified a different value for -keypass and -storepass when generating the private key in step 1, then you must provide the key password using dsconfig:
```
$ dsconfig -D "cn=directory manager" -j pwd-file -X -n \
create-key-manager-provider-key-pin --provider-name JKS --set
 key-pin:<password> --type generic --pin-name
 server-cert
```
Note:
You need to use the argument, --reset key-store-pin-file along with other arguments for 12.2.1.4.210406 BP only.
For the name of the key pin, provide the same name of the alias of the certificate. This is needed to identify which key pin/password is associated with each certificate in the key manager provider.

Then, update the SSL certificate nickname in the connection handler using the dsconfig command as follows:
```
dsconfig -D "cn=directory manager" -j pwd-file -X -n
set-connection-handler-prop --handler-name "LDAPS Connection Handler"
--set ssl-cert-nickname:server-cert
```
Note:
You need to use the argument, --reset key-store-pin-file along with other arguments for 12.2.1.4.210406 BP only.
For detailed information about keystores and truststores, see Configuring Key Manager Providers and Configuring Trust Manager Providers, respectively.
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.

26.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.

Configuring key manager providers are covered in this section:

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

26.2.1 Overview of Key Manager Provider

Oracle Unified Directory supports keystore formats for certain key manager providers.

Key manager providers are listed below:

JKS keystore, which is the default keystore format used by Java Secure Socket Extension (JSSE)
PKCS #12 file
Hardware-based devices such as a hardware security module (HSM) or cryptographic accelerator
PKCS #11 device, which is a specific hardware-based key manager provider

Note:

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

The following sections describe the process for configuring Oracle Unified Directory to use these key manager providers.

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 Managing Administration Traffic to the Server.

26.2.2 Using 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:

26.2.2.1 Generating 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:

Table 26-1 Private Key arguments

Arguments	Description
`-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 file that contains the private key information. The default keystore path used by the directory server is `config/keystore.jks`. This may be an absolute path or a path that is relative to the Oracle Unified Directory instance root. Changes to this property will take effect the next time that the key manager is accessed.
`-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. This is an optional parameter and is not recommended to be used considering the storage of clear text password in the command-line history.
`-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. This is an optional parameter and is not recommended to be used considering the storage of clear text password in the command-line history.
`-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. You will be prompted to enter the required passwords.

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

26.2.2.2 Self-Signing the Certificate

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

Table 26-2 Self-signed Certificate options

Arguments	Description
`-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. This is an optional parameter and is not recommended to be used considering the storage of clear text password in the command-line history.
`-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. This is an optional parameter and is not recommended to be used considering the storage of clear text password in the command-line history.
`-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. You will be prompted to provide the required passwords.

$ keytool -selfcert -alias server-cert -validity 1825 \
  -keystore config/keystore.jks -storetype JKS

26.2.2.3 Signing the Certificate 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.

Use the -certreq option to generate a certificate signing request. You will be prompted to provide the required passwords.

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

The arguments used with this command are as follows:

Table 26-3 -certreq option arguments

Arguments	Description
`-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. This is an optional parameter and is not recommended to be used considering the storage of clear text password in the command-line history.
`-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. This is an optional parameter and is not recommended to be used considering the storage of clear text password in the command-line history.
`-storetype` type.	Specifies the keystore type that should be used. For the JKS keystore, the value should always be `JKS.` This is an optional parameter.

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.

After receiving the signed certificate from the Certificate Authority, use the -importcert option to import it into the keystore.

Note:

If the certificate authority provides you an Intermediate Certificate, then you must also import the Intermediate Certificate into the keystore.

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

The arguments used with this command are as follows:

Table 26-4 importcert command arguments

Arguments	Description
`-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 does not 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. This is an optional parameter and is not recommended to be used considering the storage of clear text password in the command-line history.
`-storetype` type.	Specifies the keystore type that should be used. For the JKS keystore, the value should always be `JKS`. This is an optional parameter.

26.2.2.4 Configuring 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 Configuration Reference for Oracle Unified Directory.

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.jks" \
  --set "key-store-pin:<key-store-pwd>" \

Note:

You need to use the argument, --reset key-store-pin-file along with other arguments for 12.2.1.4.210406 BP only.

If you have specified a different value for -keypass and -storepass when generating the private key in step 1 of Generating the Private Key, you must provide the key password using dsconfig. For example:

dsconfig -D "cn=directory manager" -j pwd-file -X -n \
create-key-manager-provider-key-pin --provider-name JKS
--set key-pin:<key password> --type generic --pin-name server-cert

Note:

You need to use the argument, --reset key-store-pin-file along with other arguments for 12.2.1.4.210406 BP only.

Important: When you provide the name of the key pin, use the same name as the alias of the certificate. The key pin name and the certificate alias name must be identical to identify which key pin/password is associated with each certificate in the key manager provider.

26.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 Using 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 -storetype PKCS12

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

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.p12" \
  --set "key-store-pin:secret" \

Note:

You need to use the argument, --reset key-store-pin-file along with other arguments for 12.2.1.4.210406 BP only.

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

26.2.4 Overview of 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.

Oracle Unified Directory provides PKCS #11 support that, currently, has been tested and verified only on systems running at least Solaris 10 (on SPARC and x86/x64 systems) with the Solaris OS cryptographic framework. Any devices that plug into this Solaris cryptographic framework should be supported in this manner — including 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 simply use the software token or if you run 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

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

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, except 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" \

Note:

You need to use the argument, --reset key-store-pin-file along with other arguments for 12.2.1.4.210406 BP only.

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

26.2.5 Overview of Hardware-Based Key Manager Provider

You can create a key manager provider of type Hardware-Based. The Hardware Based Key Manager Provider enables the server to access the private key information through a generic hardware-based key store. This standard interface is used by cryptographic accelerators and hardware security modules.

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.

Before Oracle Unified Directory can use a hardware-based key manager provider, the Java Virtual Machine used by Oracle Unified Directory must be configured to integrate with the HSM. To verify that the HSM is properly configured, use keytool to read its contents.

To specify the PIN to be used to access the key store, configure one of the following: a Java property, an environment variable, the PIN value itself, or the path to a file containing the PIN in clear text.

The following example uses dsconfig to configure the Hardware-Based key manager provider:

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

Note:

You need to use the argument, --reset key-store-pin-file along with other arguments for 12.2.1.4.210406 BP only.

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

26.2.6 About Replacing a Certificate in a Production Server

In a production server, to replace a certificate, you need to request the new certificate. 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.

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

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.

The server needs to be restarted after the new certificate is installed.

26.2.7 Configuring Key Managers Using OUDSM

You can configure key manager configuration by using OUDSM.

Perform the following steps to manage the key manager configuration:

Connect to the directory server from OUDSM, as described in Connecting to the Server Using OUDSM.
Select the Configuration tab.
Under General Configuration, expand the Key Managers item.
Select the key manager you want to configure.

The configurable properties of the key manager are displayed in the right hand pane.
Edit the key manager configuration, as required, and click Apply to save your changes.

26.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.

The following topics covers information on trust manager providers and using them:

26.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 several factors to determine whether a peer certificate should be trusted. This topic describes some 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, then it is necessary to have only that issuer's certificate in the trust store 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 Managing Administration Traffic to the Server.

26.3.2 About 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.

26.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:

Table 26-5 -importcert options

Arguments	Description
`-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 containing the trust information. The default `-keystore` path used by the directory server when specified for the truststore is `config/truststore.jks`. This may be an absolute path or a path that is relative to the Oracle Unified Directory instance root. Changes to this property will take effect the next time that the trust manager is accessed.
`-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. This is an optional parameter and is not recommended to be used considering the storage of clear text password in the command-line history.

The following command provides an example of importing the Root CA 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 rootca -file /tmp/rootca_cert.txt
  -keystore config/truststore.jks -storetype JKS

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

Table 26-6 JKS trust manager provider properties

Properties	Description
`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.jks`, 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" \
--set enabled:true --set "trust-store-type:JKS" \
--set key-store-file:config/keystore

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

26.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:

Table 26-7 Properties of PKCS #12 trust manager provider

Property	Description
`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, you must use the trust-store-pin configuration attribute to provide the password. (Currently, the password must be provided in clear text.)

Note:

From April 2021 bundle patch release onward, the trust-store-pin-file, trust-store-pin-property, and trust-store-pin-environment-variable configuration attributes are no longer supported. The PIN value determined from these three configuration attributes is moved to the trust-store-pin attribute after you upgrade to the April 2021 bundle patch. The trust-store-pin contains the PIN needed to access the trust store directly.

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.

26.3.5 Configuring Trust Managers Using OUDSM

To configure the Trust Managers by using OUDSM:

Connect to the directory server from OUDSM, as described in Connecting to the Server Using OUDSM.
Select the Configuration tab.
Under General Configuration, expand the Trust Managers item.
Select the trust manager you want to configure.

The configurable properties of the trust manager are displayed in the right hand pane.
Edit the trust manager configuration, as required, and click Apply to save your changes.

26.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 Managing the Server Configuration Using dsconfig.

26.4.1 Using 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 different.

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.

26.4.2 Using 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.

26.4.3 Using 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, this process might possibly 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.

26.4.4 Using Subject Alternative Name To User Attribute Certificate Mapper

Subject Alternative Name to User Attribute certificate mapper attempts to establish a mapping between Oracle Unified Directory and certificate by fetching the Principal Name (or other names) that is present under subject alternative name extension of the provided certificate. You must ensure that user entries are populated with the Principal Name(or other names) that are present under subject alternative name extension of the certificates, are associated with those users.

Use dsconfig to set the properties of this certificate mapper:

subject-alternative-name-attribute-mapping

A multi-valued property that maps attributes from the certificate subject to alternative attributes in user entries. Values for this attribute consist of the Principal Name 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 user.421 maps to Principal Name and query to OUD is based on the mapping configuration defined in the SAN mapper.

For example, Figure 26-1 is a certificate containing the Subject Alternative Name To User attribute certificate mapper for smart card login use case having subject-alternative-name-attribute-mapping value as 1.3.6.1.4.1.311.20.2.3:cn where 1.3.6.1.4.1.311.20.2.3= Principal Name and cn =user.421:

Figure 26-1 Example1: Subject Alternative Name to User Attribute Certificate Mapper

Description of "Figure 26-1 Example1: Subject Alternative Name to User Attribute Certificate Mapper"

In the below example, the attribute mapping is defined in the mapper is as follows:

In the certificate extension, subject-alternative-name-attribute-mapping value is 1.3.6.1.4.1.311.20.2.3:cn@:ou, where cn=EMPID123 and ou=Orgainzation1

Figure 26-2 Example 2: Subject Alternative Name to User Attribute Certificate Mapper

Description of "Figure 26-2 Example 2: Subject Alternative Name to User Attribute Certificate Mapper"
user-base-dn

A multi-valued property that specifies the set of base DNs used in this certificate mapper.

Smart card users present their certificate to ESSO during login or authentication which will be passed to Oracle Unified Directory. Oracle Unified Directory has to read this certificate and get the subject or user details which is present under one of the certificate extension called "Subject Alternative Names". The "Subject Alternative Names" has the Principal Name attribute whose oid is 1.3.6.1.4.1.311.20.2.3 and has the actual subject details. This value is read by Oracle Unified Directory and it performs authentication.

Note:

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.

You can enable the Subject Alternative Name To User attribute certificate mapper by executing these commands:

By using set-certificate-mapper-prop:

$ dsconfig set-certificate-mapper-prop \
 --mapper-name "Subject Alternative Name To User Attribute" \ 
--set enabled:true -n -X -h localhost -p 1444 -D "cn=directory manager" -j pwdfile

By using set-global-configuration-prop:

$ dsconfig set-global-configuration-prop \
 --set certificate-mapper:"Subject Alternative Name To User Attribute" -n -X -h localhost -p 1444 -D "cn=directory manager" -j pwdfile

The container structure for smart card login use-case with subject-alternative-name-attribute-mapping is explained with the following example:

user-base-dn value dc=example, dc=com , and subject-alternative-name-attribute-mapping value is 1.3.6.1.4.1.311.20.2.3:cn@:ou where ou=organization1 and cn=EMPID123:

com,example, organization1, users,                        
     EMPID123                                               
     EMPID456         
     ......

user-base-dn value ou=users, dc=example, dc=com and subject-alternative-name-attribute-mapping value is 1.3.6.1.4.1.311.20.2.3:cn@:ou where ou=organization1 and cn=EMPID123:
```
com, example, users, organization1,
     EMPID123 
     EMPID456 
     ......
```

You can set user-base-dn, and configure the Subject Alternative Name To User Attribute certificate mapper by specifying that the server should search only dc=example,dc=com:

$ dsconfig set-certificate-mapper-prop \
 --mapper-name "Subject Alternative Name To User Attribute" \
--set user-base-dn:dc=example,dc=com 
--hostname localhost --port 1444 --portProtocol LDAP --trustStorePath /<oud-instance>/OUD/config/admin-truststore 
--bindDN "cn=Directory Manager" 
--bindPasswordFile pwdfile --no-prompt

26.4.5 Using 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.

Note:

JDK 8 adds MD5 in the list of disabled algorithms. This JDK release introduces a new restriction on how MD5 signed JAR files are verified. If the signed JAR file uses MD5, signature verification operations will ignore the signature and treat the JAR as if it were unsigned. To revert this restriction, you must remove MD5 from the list of disabled algorithms by updating the security property, jdk.jar.disabledAlgorithms, in the java.security file. The java.security file is located in JAVA_HOME/jre/lib/security/java.security.

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.

26.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 through 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 includes the following topics:

26.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 you can configure it to use SSL or 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 Enabling StartTLS Support.

The LDAPS connection handler entry is disabled, but the default configuration is set up for enabling SSL-based communication. For more information, see Enabling SSL-Based Communication.

The following topics describe how to configure LDAP and LDAPS connection handler parameters with dsconfig:

26.5.1.1 Enabling 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

26.5.1.2 Specifying 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 run on a UNIX system as a user without sufficient privileges to bind to a port below 1024.

In UNIX-like systems port numbers less than 1024 are restricted for privileged users (root) only. If you use a port number that is less than 1024 for an OUD instance, OUD setup, and execution of OUD instance then the commands must be run as privileged user (root). Therefore, you cannot assign these ports to processes running as a regular user. So, if you want to run the server as a regular user, then you use an unprivileged port, for example 1389 by default for LDAP connection. Similarly, you can use the default 1636 port when running as a regular user for SSL-based connection.

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

26.5.1.3 Specifying 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

26.5.1.4 Specifying 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

26.5.1.5 Specifying 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 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

26.5.1.6 Specifying 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 should 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

26.5.1.7 Enabling StartTLS Support

To enable StartTLS support:

Specify the appropriate values for the key-manager-provider and trust-manager-provider properties.
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 Creating a Global Index Catalog Containing Global Indexes.

26.5.1.8 Enabling SSL-Based Communication

To enable SSL-based communication:

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"
```

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.

26.5.1.9 Specifying Protocol Version and Cipher Suites in a Connection Handler

By default, Oracle Unified Directory connection handlers which support SSL/TLS based communication, supports system default SSL/TLS protocols and cipher suites. You can configure ssl-protocol and ssl-cipher-suite properties of the corresponding connection handlers to override system default SSL/TLS protocols and cipher suites.

See Supported System Default TLS Protocols by Oracle Unified Directory to view the list of TLS protocols and cipher suites supported.

The following connection handlers support the ssl-protocol and ssl-cipher-suite properties:

LDAPS
Admin Connector

The following example enables you to set ssl-protocol to TLSv1.1 and the ssl-cipher-suite to TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 for LDAPS Connection Handler:

$ dsconfig set-connection-handler-prop \
--handler-name LDAPS Connection Handler \
--set ssl-cipher-suite:TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 \
--set ssl-protocol:TLSv1.1

26.5.2 About 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 using StartTLS to allow both encrypted and unencrypted communication over the same port, but you can configure it 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:

Table 26-8 JMX Connection Handler Attributes

Attributes	Description
`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 JMX Connection Handler Configuration in Configuration Reference for Oracle Unified Directory.

26.6 Configuring SSL Protocol and Cipher Suites in Crypto Manager for Replication

By default, replication between Oracle Unified Directory server instances use SSL-based communication that is facilitated by Crypto Manager. Oracle Unified Directory supports system default protocols and cipher suites to facilitate SSL/TLS communication for replication.

See Supported System Default TLS Protocols by Oracle Unified Directory to view the list of system default TLS protocols and cipher suites supported. This behavior can be overridden by configuring ssl-protocol and ssl-cipher-suite properties of Crypto Manager. To view the list of configurable properties of Crypto Manager, see “Crypto Manager” in the Configuration Reference for Oracle Unified Directory.

The following example enables you to set ssl-protocol to TLSv1.1 and ssl-cipher-suite to TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 of Crypto Manager :

$ dsconfig set-crypto-manager-prop \
--set ssl-cipher-suite:TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 \
--set ssl-protocol:TLSv1.1

26.7 Overriding System Default Protocols and Cipher Suites for TLS Communication

CLI tools, such as, ldapsearch (including other ldap tools), dsconfig, dsreplication, ds2oud uses the system default protocols and cipher suites for TLS communication with Oracle Unified Directory server.

See Supported TLS Protocols and Cipher Suites by Oracle Unified Directory to understand about system default values. Follow the procedure provided below to override the settings.

To provide TLS protocol or cipher suites configuration for a particular CLI tool:

Create a properties file containing tls_protocols and cipher_suite_sequence as keys, and desired protocols and cipher suites as their values.
Edit the OUD_INST/OUD/config/java.properties file, and then add the custom.config.location JVM arg that is pointing to the above properties file, in the CLI specific java-args as specified below.

ldapsearch.java-args=-client -Dcustom.config.location=/scratch/tlsconfig.properties
Run OUD_INST/OUD/bin/dsjavaproperties so that the above java arg is in effect.

If you now run any of the CLI tools, for example, ldapsearch it would honor the configuration, during any TLS communication with OUD server. Refer to the sample below:

tls_protocols=TLSv1.1,TLSv1

cipher_suite_sequence=TLS_DHE_RSA_WITH_AES_128_CBC_SHA256, TLS_DHE_RSA_WITH_AES_256_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA

For CLI commands that are outside the OUD instance, or for the commands where Java arguments cannot be configured using INSTANCE_DIR/OUD/config/java.properties, you need to edit the corresponding CLI script, and add the custom.config.location java system property specifying the absolute location of the TLS config file.

For example, -Dcustom.config.location=/scratch/tlsconfig.properties

To configure oud-replication-gateway-setup/oud-replication-gateway-setup.bat tool to use specific protocols and cipher suites, you need to edit the script to add the system property. Follow the command given below:

"${OPENDS_JAVA_BIN}" -client -Dcustom.config.location=/scratch/tlsconfig.properties ${SCRIPT_NAME_ARG} com.sun.gateway.server.tools.setup.ReplicationGatewaySetupLauncher "${@}"

For .bat file:

"%OPENDS_JAVA_BIN%" -client -Dcustom.config.location=/scratch/tlsconfig.properties %SCRIPT_NAME_ARG% com.sun.gateway.server.tools.setup.ReplicationGatewaySetupLauncher %*

26.8 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 several limitations, including the following:

The user is always required to provide a full DN, rather than something that could be more user-friendly like a user name.
Only password-based authentication is allowed.
The client must provide the complete clear-text password to the server.

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.

SASL options are described in the following sections:

26.8.1 About the Supported SASL Mechanisms

SASL mechanisms are extensible, and the set of information that the client must provide to the server to perform the authentication varies from one mechanism to another.

The following SASL mechanisms are supported:

Note:

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

Other supported SASL mechanisms are:

ANONYMOUS

This mechanism does not actually authenticate clients, but does provide a mechanis 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 with 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

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 must provide to the server 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.

26.8.2 About 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.

26.8.3 About the SASL Options for the ANONYMOUS Mechanism

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=*)"

26.8.4 About the 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=*)"

26.8.5 About the 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 to help foil both replay and man-in-the-middle attacks.

DIGEST-MD5 authentication also offers several 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.

$ 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=*)"

26.8.6 About the 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.

26.8.7 About the 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=*)"

26.8.8 About the 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.

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

26.8.9 About DIGEST-MD5 SASL Mechanism

The DIGEST-MD5 SASL mechanism provides a way for clients to authentication to the Directory Server with a username and password.

The DIGEST-MD5 password does not expose the clear-text password, so it is significantly safer than simple authentication or the PLAIN SASL mechanism when the connection between the client and the server is not secure.

RFC 2831 (http://www.ietf.org/rfc/rfc2831.txt) describes the DIGEST-MD5 SASL mechanism, but a revised specification is contained in draft-ietf-sasl-rfc2831bis. The process is as follows:

The client sends an message to the server with a bind request protocol op type using an authentication type of SASL with a mechanism name of DIGEST-MD5 and no credentials.
The server sends a bind response message back to the client with a result code of 14 (SASL bind in progress) and a server SASL credentials element including, among other things, some randomly-generated data (the nonce).
The client takes the nonce provided by the server, and some randomly generated data of its own (the cnonce), an authentication ID, an optional authorization ID, the user's clear-text password, and some other information and uses that to create an MD5 digest. The client then sends a second bind request message including that digest and some other clear-text information back to the server.
The server uses the authentication ID to identify the user, and then retrieves the clear-text password for that user (if the clear-text password cannot be obtained, then authentication will fail) and uses it to determine whether the provided digest is valid. The server will then send an appropriate response to the client (usually with a result of either success or invalid credentials) indicating whether the authentication was successful.
If the client requested a quality of protection (QoP) value indicating that the connection should be protected with integrity, confidentiality, or both, then the server will initiate the necessary negotiation with the client. Currently, the directory server does not support the use of the DIGEST-MD5 mechanism with the use of integrity or confidentiality protection.

The DIGEST-MD5 SASL mechanism is very similar to CRAM-MD5 SASL mechanism, but it is somewhat strong because CRAM-MD5 includes only random data from the server whereas DIGEST-MD5 includes random data from both the client and the server. DIGEST-MD5 also provides a provision for ensuring connection integrity, confidentiality, or both that CRAM-MD5 does not offer.

26.9 Configuring SASL Authentication

You can configure directory server to use the various SASL authentication mechanisms.

Some of the SASL authentication mechanisms are:

Note:

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

26.9.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.

The following sections describe the SASL authentication:

26.9.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 through 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.

26.9.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, then the authentication still succeeds because it would have been accepted by the trust manager and mapped by the certificate mapper. If the value is never, then 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.

26.9.2 Configuring SASL DIGEST-MD5 Authentication

The access control and privilege restrictions on a user can be done 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.

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

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.

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.

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.

26.9.3 Configuring SASL GSSAPI Authentication

The access control and privilege restrictions on a user is done by 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.

Create three Kerberos principals in the realm TESTLOCAL.NET:
- user.0@TESTLOCAL.NET
- user.1@TESTLOCAL.NET
- user.2@TESTLOCAL.NET
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.

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

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.
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.
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.

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

You can configure and Kerberos Version 5 for GSSAPI SASL authentication.

The following sections describe configuring Kerberos and Oracle Unified Directory:

26.10.1 Configuring Kerberos V5 on a Host

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

Perform the following steps to configure Kerberos V5 on a host:

Install Kerberos V5 according to its installation instructions.

Note:

Previously, you were advised to install the Sun Enterprise Authentication Mechanism 1.0.1 client software.

Starting with the Oracle Solaris 10 release, the necessary Sun Enterprise Authentication Mechanism 1.0.1 client software components were incorporated into Solaris. If you are using Oracle Solaris release 10 or later, installing that client software is no longer necessary.
Configure the Kerberos software.

For Solaris: 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.
If necessary, modify the file /etc/gss/mech so that the first value that is listed is kerberos_v5.

26.10.2 Specifying SASL Options for Kerberos Authentication

You can specify appropriate SASL options for the Kerberos installation.

Perform the following steps for Kerberos installation:

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.
Specify SASL options for using Kerberos.
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.

26.10.3 Configuring 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:

26.10.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 several 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.

26.10.3.2 Editing the Kerberos Client Configuration File(All machines)

The /etc/krb5/krb5.conf configuration file provides information that Kerberos clients require 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.

26.10.3.2.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
        }

26.10.3.3 Editing the Administration Server ACL Configuration File(All machines)

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

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 *

26.10.3.4 Editing the KDC Server Configuration File (KDC Machine)

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

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
        }

26.10.3.5 Creating the KDC Database (KDC Machine)

$ /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
$

26.10.3.6 Creating an Administration Principal and Keytab(KDC Machine)

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$

26.10.3.7 Start the Kerberos Daemons(KDC Machine)

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.

26.10.3.8 Adding Host Principals for the KDC and Oracle Unified Directory Machines(KDC Machine)

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
$

26.10.3.9 Adding an LDAP Principal for the Directory Server(KDC Machine)

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 
$

26.10.3.10 Adding a Test User to the KDC(KDC Machine)

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
$

26.10.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).

26.10.3.12 Creating and Configuring the Directory Server LDAP(Directory Server Machine)

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.

26.10.3.13 Configuring the Directory Server to Enable GSSAPI(Directory Server Machine)

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

26.10.3.14 Adding a Test User to the Directory Server(Directory Server Machine)

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.

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
$

26.10.3.15 Obtaining a Kerberos Ticket as the Test User(Directory Server Machine)

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
$

26.10.3.16 Authenticating to the Directory Server Through GSSAPI(Client Machine)

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.

26.10.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  \

26.10.5 Troubleshooting Kerberos Configuration

You can check the conditions to troubleshoot 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 ensure that the directory server can authenticate to the Kerberos KDC.
Perform a successful kinit using the test principal from the client machines to ensure that the client machines can authenticate to the Kerberos KDC.
Ensure that the directory server's keytab file exists and is readable by the directory server. That is, ensure that the keytab file's ownership and permission settings are correct.

Ensure 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:

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

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.

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.

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

26.11 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 several options that are well-suited for testing in various 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. Detailed information is described in the following sections:

26.11.1 ldapsearch Command Line Arguments Applicable To Security

You can use the command-line arguments when using the ldapsearch tool to communicate through SSL or StartTLS:

Table 26-9 ldapsearch Command Line Arguments

Arguments	Description
`-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 `--useStartTLS`	Indicates that the client should use the `--useStartTLS` 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. 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. Do not use this option 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. Do not use this option 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. Do not use this option 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. Do not use this option 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. Do not use this option 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.

26.11.2 Testing SSL

You can use ldapsearch to communicate with a directory server using LDAP over SSL.

The following demonstrates the use of ldapsearch:

$ 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=*)"

26.11.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.

26.11.4 Testing SASL External Authentication

SASL EXTERNAL authentication might be used 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.

Note:

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

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

26.12 Debugging SSL Using OpenSSL `s_client` Test Utility

OpenSSL provides an extremely valuable and useful diagnostic tool, called s_client, to debug SSL servers.

These topics describe the OpenSSL s_client test utility and the solutions to debug different scenarios:

26.12.1 About OpenSSL `s_client` Test Utility

s_client is a diagnostic tool used 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,because 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.

26.12.2 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.

26.12.3 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 are using is a self-signed certificate, and you must 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.

26.12.4 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 the 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)

26.12.5 Scenario 4 - SSLHandshakeException

When you try to establish a server secure connection, the ldapsearch issues the error message.

The error message is as follows:

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

To fix this issue:

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

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

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

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

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"

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

When performing OUD SASL client external authentication over SSL, you get error message.

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

To fix this issue:

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

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

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

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"

26.13 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: 13758517829882967277399226271740078303525267606775373025890213388747276573
7596162865068864757751081632128325087288240737049199605991868092341784810001823
8935577641022820073567301050114620394591914372932977255128638534681835198625775
05401958362086546885405080570540575677103845462467633475547155894544465662390
  p: 17801190547854226652823756245015999014523215636912067427327445031444286578873
70207706126952521234630795671567847784664499706507709207278570500096683881440
341297452211718185060472311500393010799593580673953487170663198022620197149665
24135060945913707594956514672855690606794135837542707371727429551343320695239
  q: 864205495604807476120572616017955259175325408501
  g: 17406820753240209518581198012352343653860449079456135097849583104059995
348845582314785159740894095072530779709491575949236830057425243876103708447
3467180148876118103083043754985190983472601550494691329488083395492313850000
3616464826446084923040787218189599990564960977693680177492737089620066891879
56744210730
  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.

The following topics describe how to work with SSL debug recording:

26.13.1 Enabling SSL Debug Recording

You can enable SSL debug recording by updating start-ds.java-args property.

Perform the following steps to enable SSL debug recording:

Update the start-ds.java-args property in the config/java.properties file with:
```
start-ds.java-args=-server -Djavax.net.debug=all
```
Run the dsjavaproperties command as described in dsjavaproperties
Stop the server instance using the stop-ds command.
Restart the server instance using the start-ds command.

Note:

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

26.13.2 Disabling SSL Debug Recording

You can disable SSL debug recording by deleting -Djavax.net.debug=all property.

Perform the following steps to disable SSL debug recording:

Delete the -Djavax.net.debug=all property from java.properties file.
```
start-ds.java-args=-server
```
Run the dsjavaproperties command as described in dsjavaproperties
Stop the server instance using the stop-ds command.
Restart the server instance using the start-ds command.

26.14 Controlling Connection Access Using Allowed and Denied Rules

You can control connection handlers that are responsible for accepting connections to the server.

These topics provide description on the types of connection handlers and their properties and syntax:

26.14.1 About Connection Handlers

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:

allowed-client. Specifies a set of host names or address masks that determine the clients that are allowed to establish connections to this Connection Handler. Valid values include a host name, a fully qualified domain name, a domain name, an IP address, or a subnetwork with subnetwork mask.
denied-client. Specifies a set of host names or address masks that determine the clients that are not allowed to establish connections to this Connection Handler. Valid values include a host name, a fully qualified domain name, a domain name, an IP address, or a subnetwork with subnetwork mask. If both allowed and denied client masks are defined and a client connection matches one or more masks in both lists, then the connection is denied. If only a denied list is specified, then any client not matching a mask in that list is allowed.

Note:

Both IPv4 and IPv6 addresses are supported.

26.14.2 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.

26.14.3 Configuring Allowed and Denied Client Rules

Each connection handler needs to have its own set of rules. You can use dsconfig command to manage the allowed and denied properties for each connection handler

Below example lists the set of rules:

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.

26.15 Configuring Unlimited Strength Cryptography

You must download the Java Cryptography Extension Unlimited Strength Jurisdiction policy files for missing cryptography support to configure unlimited strength cryptography.

To download and install the policy file for configuring unlimited strength cryptography:

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
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.
Stop the Oracle Unified Directory server, and then restart.

26.16 Configuring TLS Protocols and Cipher Suites for OUDSM to OUD Communication

If Oracle Unified Directory server is not using system default protocols and cipher suites, then you must configure OUDSM to use the protocols and cipher suites that Oracle Unified Directory server supports.

See Supported TLS Protocols and Cipher Suites by Oracle Unified Directory to learn about system default values that are used for secured communication.

To configure TLS protocols and cipher suites for OUDSM to OUD server communication, perform these steps:

To configure protocol version, set OUDSM weblogic system property as: weblogic.security.SSL.minimumProtocolVersion=[protocol]

Consider the following example to set protocol version to TLSv1.1:

weblogic.security.SSL.minimumProtocolVersion=TLSv1.1

See Using the weblogic.security.SSL.minimumProtocolVersion System Property in Oracle Fusion Middleware Administering Security for Oracle WebLogic Server to know about protocols used for SSL connection.

Note:
You need to restart OUDSM weblogic server after you set the protocol version.
To configure cipher suites, use WLST command setCipherSuites() in weblogic server's SSL configuration.
See Setting Cipher Suites Using WLST: An Example in Oracle Fusion Middleware Administering Security for Oracle WebLogic Server to know about setting cipher suites using WLST script.

26.1 Getting SSL Up and Running Quickly

26.1.1 Setting Up SSL Using an Existing Private Key and Certificate

26.1.2 Accepting SSL-Based Connections Using a Self-Signed Certificate

26.2 Configuring Key Manager Providers

26.2.1 Overview of Key Manager Provider

26.2.2 Using JKS Key Manager Provider

26.2.2.1 Generating the Private Key

26.2.2.2 Self-Signing the Certificate

26.2.2.3 Signing the Certificate Using an External Certificate Authority

26.2.2.4 Configuring the JKS Key Manager Provider

26.2.3 Using the PKCS #12 Key Manager Provider

26.2.4 Overview of PKCS #11 Key Manager Provider

26.2.5 Overview of Hardware-Based Key Manager Provider

26.2.6 About Replacing a Certificate in a Production Server

26.2.7 Configuring Key Managers Using OUDSM

26.3 Configuring Trust Manager Providers

26.3.1 Overview of Certificate Trust Mechanisms

26.3.2 About Blind Trust Manager Provider

26.3.3 Using the JKS Trust Manager Provider

26.3.4 Using the PKCS #12 Trust Manager Provider

26.3.5 Configuring Trust Managers Using OUDSM

26.4 Configuring Certificate Mappers

26.4.1 Using Subject Equals DN Certificate Mapper

26.4.2 Using Subject Attribute to User Attribute Certificate Mapper

26.4.3 Using Subject DN to User Attribute Certificate Mapper

26.4.4 Using Subject Alternative Name To User Attribute Certificate Mapper

26.4.5 Using Fingerprint Certificate Mapper

26.5 Configuring SSL and StartTLS for LDAP and JMX

26.5.1 Configuring the LDAP and LDAPS Connection Handlers

26.5.1.1 Enabling a Connection Handler

26.5.1.2 Specifying a Connection Handler's Listening Port

26.5.1.3 Specifying a Connection Handler's Authorization Policy

26.5.1.4 Specifying a Nickname for a Connection Handler's Certificate

26.5.1.5 Specifying a Connection Handler's Key Manager Provider

26.5.1.6 Specifying a Connection Handler's Trust Manager Provider

26.5.1.7 Enabling StartTLS Support

26.5.1.8 Enabling SSL-Based Communication

26.5.1.9 Specifying Protocol Version and Cipher Suites in a Connection Handler

26.5.2 About JMX Connection Handler

26.6 Configuring SSL Protocol and Cipher Suites in Crypto Manager for Replication

26.7 Overriding System Default Protocols and Cipher Suites for TLS Communication

26.8 Using SASL Authentication

26.8.1 About the Supported SASL Mechanisms

26.8.2 About Authorization IDs

26.8.3 About the SASL Options for the ANONYMOUS Mechanism

26.8.4 About the SASL Options for the CRAM-MD5 Mechanism

26.8.5 About the SASL Options for the DIGEST-MD5 Mechanism

26.8.6 About the SASL Options for the EXTERNAL Mechanism

26.8.7 About the SASL Options for the GSSAPI Mechanism

26.8.8 About the SASL Options for the PLAIN Mechanism

26.8.9 About DIGEST-MD5 SASL Mechanism

26.9 Configuring SASL Authentication

26.9.1 Configuring SASL External Authentication

26.9.1.1 Configuring the LDAP Connection Handler to Allow SASL EXTERNAL Authentication

26.9.1.2 Configuring the EXTERNAL SASL Mechanism Handler

26.9.2 Configuring SASL DIGEST-MD5 Authentication

26.9.3 Configuring SASL GSSAPI Authentication

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

26.10.1 Configuring Kerberos V5 on a Host

26.10.2 Specifying SASL Options for Kerberos Authentication

26.10.3 Configuring Kerberos Authentication Using GSSAPI With SASL

26.10.3.1 Assumptions for This Example

26.10.3.2 Editing the Kerberos Client Configuration File(All machines)

26.10.3.2.1 Edited Kerberos Client Configuration File /etc/krb5/krb5.conf

26.10.3.3 Editing the Administration Server ACL Configuration File(All machines)

26.10.3.4 Editing the KDC Server Configuration File (KDC Machine)

26.10.3.5 Creating the KDC Database (KDC Machine)

26.10.3.6 Creating an Administration Principal and Keytab(KDC Machine)

26.10.3.7 Start the Kerberos Daemons(KDC Machine)

26.10.3.8 Adding Host Principals for the KDC and Oracle Unified Directory Machines(KDC Machine)

26.10.3.9 Adding an LDAP Principal for the Directory Server(KDC Machine)

26.10.3.10 Adding a Test User to the KDC(KDC Machine)

26.10.3.11 Directory Server Machine: Install Oracle Unified Directory

26.10.3.12 Creating and Configuring the Directory Server LDAP(Directory Server Machine)

26.10.3.13 Configuring the Directory Server to Enable GSSAPI(Directory Server Machine)

26.10.3.14 Adding a Test User to the Directory Server(Directory Server Machine)

26.10.3.15 Obtaining a Kerberos Ticket as the Test User(Directory Server Machine)

26.10.3.16 Authenticating to the Directory Server Through GSSAPI(Client Machine)

26.10.4 Creating a Kerberos Workflow Element Using dsconfig

26.10.5 Troubleshooting Kerberos Configuration

26.10.4 Creating a Kerberos Workflow Element Using `dsconfig`

26.11 Testing SSL, StartTLS, and SASL Authentication With `ldapsearch`

26.12 Debugging SSL Using OpenSSL `s_client` Test Utility

26.12.1 About OpenSSL `s_client` Test Utility