Skip Navigation Links | |
Exit Print View | |
Oracle Fusion Middleware Administration Guide for Oracle Unified Directory 11g Release 1 (11.1.1) |
1. Starting and Stopping the Server
2. Configuring the Server Instance
3. Configuring the Proxy Components
4. Configuring Security Between Clients and Servers
Getting SSL Up and Running Quickly
To Accept SSL-Based Connections Using a Self-Signed Certificate
Configuring Key Manager Providers
Using the JKS Key Manager Provider
To Sign the Certificate by Using an External Certificate Authority
To Configure the JKS Key Manager Provider
Using the PKCS #12 Key Manager Provider
Configuring Trust Manager Providers
Overview of Certificate Trust Mechanisms
Using the Blind Trust Manager Provider
Using the JKS Trust Manager Provider
Using the PKCS #12 Trust Manager Provider
Configuring Certificate Mappers
Using the Subject Equals DN Certificate Mapper
Using the Subject Attribute to User Attribute Certificate Mapper
Using the Subject DN to User Attribute Certificate Mapper
Using the Fingerprint Certificate Mapper
Configuring SSL and StartTLS for LDAP and JMX
Configuring the LDAP and LDAPS Connection Handlers
To Enable a Connection Handler
To Specify a Connection Handler's Listening Port
To Specify a Connection Handler's Authorization Policy
To Specify a Nickname for a Connection Handler's Certificate
To Specify a Connection Handler's Key Manager Provider
To Specify a Connection Handler's Trust Manager Provider
To Enable SSL-Based Communication
Enabling SSL in the JMX Connection Handler
SASL Options for the ANONYMOUS Mechanism
SASL Options for the CRAM-MD5 Mechanism
SASL Options for the DIGEST-MD5 Mechanism
SASL Options for the EXTERNAL Mechanism
SASL Options for the GSSAPI Mechanism
SASL Options for the PLAIN Mechanism
Configuring SASL Authentication
Configuring SASL External Authentication
Configuring the LDAP Connection Handler to Allow SASL EXTERNAL Authentication
Configuring the EXTERNAL SASL Mechanism Handler
Configuring SASL DIGEST-MD5 Authentication
Configuring SASL GSSAPI Authentication
To Configure Kerberos V5 on a Host
To Specify SASL Options for Kerberos Authentication
Example Configuration of Kerberos Authentication Using GSSAPI With SASL
All Machines: Edit the Kerberos Client Configuration File
All Machines: Edit the Administration Server ACL Configuration File
KDC Machine: Edit the KDC Server Configuration File
KDC Machine: Create the KDC Database
KDC Machine: Create an Administration Principal and Keytab
KDC Machine: Start the Kerberos Daemons
KDC Machine: Add Host Principals for the KDC and Oracle Unified Directory Machines
KDC Machine: Add an LDAP Principal for the Directory Server
KDC Machine: Add a Test User to the KDC
Directory Server Machine: Install the Directory Server
Directory Server Machine: Create and Configure the Directory Server LDAP
Directory Server Machine: Configure the Directory Server to Enable GSSAPI
Directory Server Machine: Add a Test User to the Directory Server
Directory Server Machine: Obtain a Kerberos Ticket as the Test User
Client Machine: Authenticate to the Directory Server Through GSSAPI
Troubleshooting Kerberos Configuration
Testing SSL, StartTLS, and SASL Authentication With ldapsearch
ldapsearch Command Line Arguments Applicable To Security
Testing SASL External Authentication
Controlling Connection Access Using Allowed and Denied Rules
Property Syntax of Allowed and Denied Client Rules
Configuring Allowed and Denied Client Rules
5. Configuring Security Between the Proxy and the Data Source
6. Managing Oracle Unified Directory With Oracle Directory Services Manager
10. Managing Users and Groups With dsconfig
11. Managing Password Policies
Key manager providers are ultimately responsible for providing access to the certificate that should be used by the directory server when performing SSL or StartTLS negotiation.
This section covers the following topics:
Using the PKCS #11 Key Manager Provider
PKCS #11 is not supported for use with the proxy.
For additional information, see the Key Manager Provider Configuration.
Oracle Unified Directory supports keystore formats for the following key manager providers:
JKS keystore, which is the default keystore format used by Java Secure Socket Extension (JSSE)
PKCS #12 file
PKCS #11 device, such as a hardware security module or cryptographic accelerator
Note - PKCS #11 is not supported for use with Oracle Unified Directory proxy.
The process for configuring Oracle Unified Directory to use these key manager providers is described in detail in the following sections.
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 .
Using the JKS key manager provider involves the following:
Generating the private key
Self-signing the certificate, or using an external certificate authority to sign the certificate
Configuring the JKS key manager provider
If the certificate is to be self-signed, use the -selfcert option. The most important arguments for use with this option include:
-alias alias. Specifies the name that should be used to refer to the certificate in the keystore. This name should be the same as the value used when creating the private key with the -genkeypair option.
-validity days. Specifies the length of time in days that the certificate should be valid. The default validity is 90 days.
-keystore path. Specifies the path to the keystore file. The file will be created if it does not already exist.
-keypass password. Specifies the password that should be used to protect the private key in the keystore. If this is not provided, then you will be interactively prompted for it.
-storepass password. Specifies the password that should be used to protect the contents of the keystore. If this is not provided, then you will be interactively prompted for it.
-storetype type. Specifies the keystore type that should be used. For the JKS keystore, the value should always be JKS.
$ keytool -selfcert -alias server-cert -validity 1825 \ -keystore config/keystore -keypass password -storetype JKS \ -storepass password
If the certificate is to be signed by an external certificate authority, you must first generate a certificate signing request (CSR) using the -certreq option. The CSR can be submitted to a certificate authority to be signed. The method for doing this, and the method for obtaining the signed certificate, might vary from one certificate authority to another.
When you receive the signed certificate from the Certificate Authority, import it into the keystore with the -importcert option.
$ keytool -certreq -alias server-cert -file /tmp/server-cert.csr \ -keystore config/keystore -keypass password -storetype JKS \ -storepass password
The arguments used with this command are as follows:
-alias alias. Specifies the name that should be used to refer to the certificate in the keystore. This name should be the same as the value used when creating the private key with the -genkeypair option.
-file path. Specifies the path to the file to which the CSR should be written. If this is not provided, the request will be written to standard output.
-keystore path. Specifies the path to the keystore file. The file will be created if it does not already exist.
-keypass password. Specifies the password that should be used to protect the private key in the keystore. If this is not provided, you will be interactively prompted for it.
-storepass password. Specifies the password that should be used to protect the contents of the keystore. If this is not provided, you will be interactively prompted for it.
-storetype type. Specifies the keystore type that should be used. For the JKS keystore, the value should always be JKS.
$ keytool -importcert -alias server-cert -file /tmp/server-cert.cert \ -keystore config/keystore -storetype JKS -storepass password
The arguments used with this command are as follows:
-alias alias. Specifies the name that should be used to refer to the certificate in the keystore. This name should be the same as the value used when creating the private key with the -genkeypair option.
-file path. Specifies the path to the file containing the signed certificate. The file should be in either the DER-encoded binary format or the base64-encoded ASCII format as described in RFC 1421.
-keystore path. Specifies the path to the keystore file. The file will be created if it doesn't already exist.
-storepass password. Specifies the password that should be used to protect the contents of the keystore. If this is not provided, then you will be interactively prompted for it.
-storetype type. Specifies the keystore type that should be used. For the JKS keystore, the value should always be JKS.
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 creating a key manager provider entry for that keystore.
This example defines an instance of a file-based key manager provider, using dsconfig to set the properties of the key manager provider. For details about the properties of the key manager provider, see the File Based Key Manager Provider Configuration.
$ dsconfig -D "cn=Directory Manager" -w password -X -n \ set-key-manager-provider-prop --provider-name "JKS" \ --set java-class:org.opends.server.extensions.FileBasedKeyManagerProvider \ --set enabled:true --set "key-store-type:JKS" \ --set "key-store-file:/config/keystore" \ --set "key-store-pin:secret"
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 the JKS Key Manager Provider for obtaining a certificate in a JKS keystore. The only difference in the process is that you should use -storetype PKCS12 instead of -storetype JKS when you invoke the keytool commands. For example, to create a self-signed certificate in a PKCS #12 file, use the following commands:
$ keytool -genkeypair -alias server-cert -keyalg rsa \ -dname "CN=server.example.com,O=example.com,C=US" \ -keystore config/keystore.p12 -keypass password \ -storetype PKCS12 -storepass password
$ keytool -selfcert -alias server-cert -validity 1825 \ -keystore config/keystore.p12 -keypass password \ -storetype PKCS12 -storepass password
As with JKS, the server provides a template key manager provider for use with PKCS #12 certificate files that uses the same set of configuration attributes as the configuration entry for the JKS key manager provider. The only differences are that the value of the key-store-type attribute must be PKCS12, and the key-store-file attribute should refer to the location of the PKCS #12 file rather than a JKS keystore. The following example uses dsconfig to configure the PKCS #12 keystore manager provider:
$ dsconfig -D "cn=directory manager" -w password -X -n\ set-key-manager-provider-prop --provider-name "PKCS12"
For a complete list of configurable properties, see the File Based Key Manager Provider Configuration.
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:
Note - The PKCS #11 format is not supported for use with the Oracle Unified Directory proxy.
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.
At present, the PKCS #11 support that Oracle Unified Directory provides has been tested and verified only on systems running at least Solaris 10 (on SPARC and x86/x64 systems) through the use of the Solaris OS cryptographic framework. Any device that plugs into this Solaris cryptographic framework should be supported in this manner. This includes the softtoken device, which is simulated in software and is therefore available on all systems supporting the Solaris cryptographic framework regardless of whether they have a hardware device providing PKCS #11 support.
If you do have a third-party PKCS #11 device installed in a Solaris system, it is likely that the Solaris OS cryptographic framework is already configured to access that device. However, if you will simply be using the software token or if you are running on a Sun Fire T1000 or T2000 system and want to take advantage of the cryptographic processor included in the UltraSPARC—T1 CPU, you will likely need to initialize the PKCS #11 interface. This should first be accomplished by choosing a PIN to use for the certificate store, which can be done with this command:
$ pktool setpin
This command prompts you for the current passphrase. If you have not yet used the Solaris OS cryptographic framework, the default passphrase is changeme. You are then prompted twice for the new password.
Note - This step should be done while you are logged in as the user or as the role that will be used to run the directory server, because each user might have a different set of certificates.
At this point, it should be possible to use the Java keytool utility to interact with the Solaris cryptographic framework through PKCS #11. This will work much in the same way as it does when working with JKS or PKCS#12 keystores, with the following exceptions:
The value of the -keystore argument must be NONE.
The value of the -storetype argument must be PKCS11.
You should not use the -keypass argument, and the tool will not prompt you for that password interactively if you do not provide it.
The value of the -storepass argument must be the passphrase that you chose when using the pktool setpin command. Alternately, if you do not provide this argument on the command line, this is the password that you should enter when prompted.
For example, the following commands use the PKCS #11 interface to generate a self-signed certificate through the Solaris cryptographic framework:
$ keytool -genkeypair -alias server-cert -keyalg rsa \ -dname "CN=server.example.com,O=example.com,C=US" \ -keystore NONE -storetype PKCS11 -storepass password
$ keytool -selfcert -alias server-cert -validity 1825 \ -keystore NONE -storetype PKCS11 -storepass password
When the certificate is installed in the PKCS #11 keystore, the directory server must be configured to use that keystore. Configure the PKCS #11 keystore provider in the same way as the entry for the JKS and PKCS#12 keystore manager providers, with the exception that the key-store-file attribute is not included. However, a PIN is still required and is provided either directly, in a PIN file, through a Java property, or through an environment variable.
The following example uses dsconfig to configure the PKCS #11 key manager provider:
$ dsconfig -D "cn=directory manager" -w password -X -n \ set-key-manager-provider-prop --provider-name "PKCS11"
For a complete list of configurable properties, see the PKCS11 Key Manager Provider Configuration.
If none of the key manager providers available with Oracle Unified Directory suits your needs, you can create your own key manager provider to obtain the key material from virtually anywhere you like.
To create a custom key manager provider, create a class that extends the org.opends.server.api.KeyManagerProvider super class and implement the methods that it contains. The source for the existing key manager providers is located in the org.opends.server.extensions package and can be useful for reference purposes.