Previous     Contents     Index     Next     
iPlanet Directory Access Router Administrator's Guide



Chapter 5   Configuring System Parameters


System parameters are those that effect the functional behavior of iPlanet Directory Access Router (iDAR). This chapter explains how to specify system configuration and configure iDAR for TLS/SSL-enabled communication with LDAP clients and servers.

The chapter contains the following sections:



Configuring System Settings

This section explains how to configure system-specific parameters of an iDAR instance.


Creating System Configuration Objects

To create an object for system configuration:

  1. Access the iDAR Configuration Editor Console; see Accessing the iDAR Consoles.

  2. In the navigation tree, select System Configurations.

    The right pane shows existing objects for the system configuration.



  3. Click New.

    The System Configuration window appears.



  4. In the Name field, type a name for the system configuration. The name must be a unique alphanumeric string.

  5. In the Settings tab, specify general setting for this system configuration:

    Host. Enter the name of the host interface on which iDAR will listen for connections. This attribute is needed only if there are multiple network interfaces on the host running iDAR. By default, the hostname is set to "localhost," meaning iDAR will listen on all available network interfaces. Specifying "localhost" will permit shared system properties.

    Port. Enter the port number on which iDAR will listen for incoming connections. Legal values for this field are 1 through 65535. By default, the value is set to 389, as specified for LDAP. This port number must be different from that used by any other LDAP server running on the same host. On UNIX platforms the server must be started as root to listen on a port number below 1024.

    SSL port. Enter a value representing the port number on which to listen for LDAPS (LDAP over SSL) connections. By default, iDAR does not listen for connections from LDAPS clients. This value must be present to enable LDAPS connections from clients using this nonstandard function, with a value such as 636. This value must be different from the Host value. This option also requires TLS/SSL configuration, found on the Encryption tab.

    Log property. Choose a log property from which this system configuration will derive its custom logging information.

    Edit. Displays a dialog for editing the property currently displayed in Log Property.

    UNIX properties. This panel contains attributes that pertain to iDAR servers in a UNIX environment only.

    User ID. Enter the user ID under which iDAR will run. If iDAR was run as root then it will change its uid to the one specified here. The default is to switch to nobody. This option is not applicable on Windows NT.

    Working directory. Enter the directory from which iDAR should run. iDAR will change its working directory to the directory specified as value for this attribute on startup. The default is /tmp. This attribute only takes effect on platforms other than Windows NT.

  6. Select the Encryption tab and configure iDAR for SSL-enabled communication.



    The description of the parameters is as follows:

    Enable SSL/TLS for this server. Select this box to enable SSL/TLS information needed by iDAR to listen over a secure connection. If an SSL port is specified, you must enable this setting and provide both the private key file and signed CA certificate file in order to save this configuration.

    Private key file. Enter the path of the file on disk containing the private key associated with the server's certificate.

    CA signed certificate file. Enter the path of the file on disk containing the server's own certificate signed by the CA. The certificate in the file must be in PEM format.

    CA root certificate file. Enter the path of the file on disk containing trusted root certificates. These certificates must be in the PEM format.

    Send certificate when making SSL connections to LDAP severs. Enable this setting if you want iDAR to send its certificate to the backend LDAP directory server when making a TLS connection. By default this setting is disabled.

    Require a client certificate. Enable this setting to specify that iDAR will require all clients that establish an SSL session to submit a certificate chain. iDAR will close the connection if a certificate chain is not submitted. Note that this option does not effect SSL sessions between iDAR and the backend servers. By default this setting is disabled.

    SSL/TLS version. Select the SSL/TLS versions used for client and LDAP server communications with iDAR.

    Client communication. Specify the SSL/TLS version iDAR will use between itself and the clients. The default is SSL version 2 or 3.

    LDAP server communication. Specify the SSL/TLS version iDAR will use for connections between itself and backend LDAP servers. The default is SSL version 2 or 3.

  7. Select the Connections tab and specify how iDAR should maintain its connections.



    The description of the parameters is as follows:

    Connection backlog. Enter a value greater than zero specifying the maximum number of outstanding connections in the listening socket's queue. The default is 128 connections. The maximum value depends on the underlying operating system configuration.

    Specify maximum number of connections. Select the option and enter a value (greater than zero) specifying the maximum number of simultaneous client connections that iDAR will accept. To allow an unlimited number of simultaneous connections, do not select this option.

    Enable Connection Pool. Enables the connection pool module with which iDAR will preconnect to the directory servers. The default for the setting is disabled. If the connection pool is enabled, iDAR will try to reuse existing connections to the backend LDAP servers. Switching on this option can give significant performance gain if the backend server is on a Wide Area Network (WAN).

    Interval. Enter the number of seconds (greater or equal to one) specifying the interval in seconds at which iDAR will sample the incoming requests to anticipate future activity. The default is 15.

    Specify timeout. Select the option and enter the number of seconds (greater or equal to zero) specifying the period of time in seconds after which an idle connection to an LDAP server will be terminated. If the checkbox is unchecked, no timeout will be applied. The default is 30. This value should be less than the idle connection timeout value of the backend LDAP server.

  8. Click Save to save the object.

    The iDAR configuration is modified, and you are prompted to restart the servers that rely on this configuration. Don't restart the servers yet. You can do this after you've completed all the configuration changes.

  9. Repeat Step 3 through Step 8 to create any additional objects.

  10. Restart the servers; see Restarting iDAR.


    Note Changes to the following will require stopping and starting iDAR: Host, Port, and "SSL port" fields in the Settings tab; the "CA signed certificate file" and "Private key file" fields in the Encryption tab; and the "Connection backlog" field in the Connections tab.

    For instructions to stop and start iDAR, see Starting and Stopping iDAR.




Configuring iDAR for TLS/SSL-Enabled Communication

This section explains how to set up iDAR for TLS/SSL-enabled communication with an LDAP client and an LDAP server. It is recommended that you also read the overview part of Chapter 12 "Configuring Security."

Some of the information in this section is written with an assumption that you are familiar with the basic concepts of public-key cryptography and Secure Sockets Layer (SSL) protocol, and understand the concepts of intranet, extranet, and the Internet security and the role of digital certificates in an enterprise. If you are new to these concepts, we recommend you read the security-related documents available on line at this URL: http://docs.iplanet.com/docs/manuals/security.html

You may also refer to the security-related appendixes of the accompanying manual, Managing Servers with iPlanet Console.

iDAR has two separately configurable communication links. Each communication link can be plaintext or encrypted using Transport Layer Security (TLS) or Secure Sockets Layer (SSL) protocol. Availability of the two separate communication links enables you to configure TLS- or SSL-enabled communication between an LDAP client and iDAR and between iDAR and an LDAP directory. Figure 5-1 illustrates this capability of iDAR.

Figure 5-1    Two Separate Communication Links in iDAR


iDAR also supports strong authentication, which is also known as certificate-based authentication. It can verify both client and server certificates, provided the trusted root CA certificate for the certificate being validated is installed and is available to iDAR. Note that the verification process is limited to verifying the validity period and the issuer name of the CA present on the certificate being validated; iDAR does not verify the revocation status of the certificate.

Figure 5-2 illustrates how iDAR can verify the certificates presented to it by the clients after they establish an SSL session.

Figure 5-2    Certificate-Based Authentication of Clients


Note that, unlike some of the SSL-enabled servers that come under the iPlanet Console framework, this version of iDAR is not built with Network Security Services (NSS); for details about NSS, check this site:

http://www.mozilla.org/projects/security/pki/nss/

Hence, the iDAR Console doesn't have a built-in Certificate Setup Wizard, which automates the process of requesting and installing an SSL server certificate.

To get an SSL server certificate for iDAR, you must first generate a key pair and a corresponding certificate request using the command-line utility named certreq, submit the certificate request to a CA, and obtain a server certificate from the CA.

The certreq utility is available in your iDAR installation at this location: <server-root>/bin/idar/server/bin

For more information about this utility, see Chapter 12 "Configuring Security."

In general, setting up iDAR for SSL-enabled communication involves these steps:


Step 1. Install a Server Certificate for iDAR

To install a server certificate for iDAR, follow these steps:


Step A. Generate a Key Pair and a Certificate Request

In this step you use the certreq utility to generate a key pair and a corresponding certificate request for iDAR.

  1. Open a terminal window in the iDAR host system.

  2. Go to this directory: <server-root>/bin/idar/server/bin

  3. Run the certreq command with the appropriate options to generate a key pair and a certificate request for the key pair.

    The command syntax is as follows:

    certreq -dn <dn> -reqout <filename> -keyout <filename>
    [-dsaparms <filename>] [-bits <bits>]

    For example, the command to generate an RSA key of size 1024 bits will look like this:

    ./certreq -dn 'cn=idarhost.siroe.com, o=Siroe Corporation, c=US' -reqout idar-certreq.txt -keyout idar-key.txt -bits 1024


Step B. Verify the iDAR Key File and Certificate Request Files

After you've run the certreq command, verify that the key and certificate request files are generated and that they contain the appropriate information.

If you generated a RSA key, the key file is the file specified by the -keyout parameter. The file should contain the RSA private key. The contents of the file should look similar to the example shown below:

-----BEGIN RSA PRIVATE KEY-----

MIICXQIBAAKBgQDrYc78Q9PnU8Q5d0SfFyNXI84sRtGP9NXgP70XxY6Wdg3xoQA
Z/xWyE/0dx0xRR8bzCpi25eTVyYbyQMxY6yu2OxvsywDYwkAN2bRBgePUMVSlx2
Zi62Fr2CzsAaajbOO0yqXFP/gyjXphYorbOvyG78Xp3vFIesWYl6GgzglwIDAQA
BAoGBAOIm1E9N/+/XbMXl0Nmlyn+z2Ch0Vm6gx0kEYduvTXMmiAzwWpKipbRW7V
bwfiqJP1opfe8hBPgD7b8CRo5wQziQlypp7JnFnDjL7U/QARzRATUax/t8iugcb
RdCxQ4PrZ45At/amZpkkWCozYfXA+57LlhW35KxLcstMTNpNu7YPhAkEA+w5fhs
PgUO09eSzMsYyAfvVlctmaLDmcapMLRlNp5AnUYvwK17l0mCrAT

-----END RSA PRIVATE KEY-----


Caution

The information contained in the key file is the base-64 encoding of the RSA private key. Do not make any changes to the file. Also ensure that iDAR has read permission to the file.

The private key file must be protected against theft, tampering, or viewing. You must use the operating system's security feature to restrict access to the file—only you or authorized administrators should have access to this file. It's also important to know if the file is stored on backup tapes or is otherwise available for someone to intercept. Because the destruction of a private key in a disk crash will require you to regenerate the key and reconfigure iDAR, backing up your key file is commensurately important. If you do make copies of the key file, however, you must protect your backups with the same level of security that you use for protecting your original key file.


The certificate request file is the file specified by the -reqout parameter. This file should contain a certificate request. The contents of the file should look similar to the example shown below:

-----BEGIN CERTIFICATE REQUEST-----

MIIBbTCB1wIBADAuMRMwEQYKCZImiZPyLGQBGRYDY29tMRcwFQYKCZImiZPyLGQB
GRYHaVBsYW5ldDCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA62HO/EPT51PE
OXdEnxcjVyPOLEbRj/TV4D+9F8WOlnYN8aEAMWf8VshP9HcdMUUfG8wqYtuXk1cm
G8kDMWOsrtjsb7MsA2MJADdm0QYHj1DFUpcdo2Yutha9gs7AGmo2zjtMqlxT/4Mo
16YWKK2zr8hu/F6d7xSHrFmJehoM4JcCAwEAAaAAMA0GCSqGSIb3DQEBBAUAA4GB
AHcBoLa3Bi3o+HblCIkD6Rx29gShLwVK+QyzrPHrC9iGgrOu

-----END CERTIFICATE REQUEST-----

The contents of the certificate request file are a base-64 encoding of a value of the ASN.1 type defined in PKCS#10:

SIGNED { SEQUENCE {
version Version,
subject Name,
subjectPublicKeyInfo SubjectPublicKeyInfo,
attributes [0] IMPLICIT Attributes } }

Do not make any modifications to the file. You will need to send the contents in the certificate request file to the CA, as explained in the next step. (After you receive the certificate from the CA, you may destroy the certificate request file; iDAR does not make use of the certificate request.)


Step C. Submit the Certificate Request to a CA

In this step, you submit the iDAR certificate request to a certificate authority (CA) so that it can sign the certificate request and send the server certificate to you:

  1. Open a Web browser window.

  2. Navigate to the CA's site, and locate the enrollment form for submitting a SSL server certificate request.

  3. In your local file system, open the certificate request file that you created.

  4. Copy the certificate request.

    Unless the instructions in the enrollment form specify otherwise, you need to copy the request including the marker lines -----BEGIN CERTIFICATE REQUEST----- and -----END CERTIFICATE REQUEST-----. The information you copied should look similar to the example below:

    -----BEGIN CERTIFICATE REQUEST-----

    MIIBbTCB1wIBADAuMRMwEQYKCZImiZPyLGQBGRYDY29tMRcwFQYKCZImiZPyLGQB
    GRYHaVBsYW5ldDCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA62HO/EPT51PE
    OXdEnxcjVyPOLEbRj/TV4D+9F8WOlnYN8aEAMWf8VshP9HcdMUUfG8wqYtuXk1cm
    G8kDMWOsrtjsb7MsA2MJADdm0QYHj1DFUpcdo2Yutha9gs7AGmo2zjtMqlxT/4Mo
    16YWKK2zr8hu/F6d7xSHrFmJehoM4JcCAwEAAaAAMA0GCSqGSIb3DQEBBAUAA4GB
    AHcBoLa3Bi3o+HblCIkD6Rx29gShLwVK+QyzrPHrC9iGgrOu

    -----END CERTIFICATE REQUEST-----

  5. Go back to the CA's enrollment form, and paste the certificate request into the text area provided in the form.

  6. Fill out any other information required by the CA; some CA's mandate this in order to approve a certificate request.

  7. Submit the request.

    If you submitted the request to a third-party or public CA, as opposed to an internally-deployed CA, you might want to keep the response you receive from the CA. It will contain information, for example, a reference number, that will help you to track your request.

    The issuance or availability of your certificate will depend on the CA's policy for issuing server certificates. Some CAs might take longer time to process your request and issue the certificate. You should wait till you get the certificate and then continue with the remaining instructions.


Step D. Copy the Certificate to a Text File

When you get a notification about the availability of the server certificate, follow the instructions in this step:

  1. In the notification you got from the CA, locate the server certificate in the base-64 encoded format.

  2. Copy the certificate.

    You need to copy the certificate including the marker lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----. The information you copied should look similar to the example below:

    -----BEGIN CERTIFICATE-----

    MIIBbTCB1wIBADAuMRMwEQYKCZImiZPyLGQBGRYDY29tMRcwFQYKCZImiZPy
    LGQBGRYHaVBsYW5ldDCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA62HO
    /EPT51PEOXdEnxcjVyPOLEbjgTV4D+9F8WOlnYN8aEAMWf8VshP9HcdMUUfG
    wqYtuXk1cmG8kDMWOsrtjsb7MsA2MJADdm0QYHj1DFUpcdo2Yutha9gs7AGm
    o2zjtMqlxT/4Mo16YWKK2zr8hu/F6d7xSHrFmJehoM4JcCAwEAAaAAMA0GCS
    qGSIb3DQEBBAUAA4GBAHcBoLa3Bi3o+HblCIkD6Rx29gShL
    -----END CERTIFICATE-----

  3. Create a text file, for example, idar-cert.txt.

  4. Paste the certificate you copied to the text file and save.

  5. Put the file in a location that's accessible and readable by iDAR. Also note the file path. You will be required to specify the path later.


Step E. Copy the CA Certificate Chain to a Text File

If you set up iDAR for SSL-client authenticated communication with LDAP servers or SSL-server authenticated communication with LDAP clients, those applications will need to trust the CA that signed the iDAR's server certificate. (If this CA is subordinate to another trusted root CA, then the applications will need to trust the root CA.)

To establish trust between the said applications and iDAR, you (or the administrators of those applications) will need to install the CA certificate chain in appropriate LDAP clients' and LDAP servers' certificate databases.

The instructions in this step will help you save the CA certificate chain to a file for later use.

  1. Locate the CA certificate and/or CA certificate chain in its base-64 encoded format.

    Some CAs send it along with the certificate, where as some CAs might make it available on the CA site. Check the notification you received from the CA when you got the server certificate.

  2. Create a text file, for example, idar-cachain.txt.

  3. Copy the root certificate to the text file and save.

  4. If required, send the file to LDAP client and server administrators.


Step 2. Set Up SSL Connections Between iDAR and Clients

To set up SSL connections between iDAR and LDAP clients, follow these steps:


Step A. Create a File with CA Certificates in PEM Format

This step is required if you want iDAR to verify the certificates presented to it by the clients after they establish an SSL session (see Figure 5-2).

  1. Create a text file.

  2. Copy the trusted root certificates of CAs that iDAR can trust.

    The certificates must be in the Privacy Enhanced Message (PEM) format, including the markers as shown in the example below:

    -----BEGIN CERTIFICATE-----

    MIIDkjCCAnqgAwIBAgIBADANBgkqhkiG9w0BAQUFADCBgzELMAkGA1UEBhMCVVM
    xCzAJBgNVBAgTAkRDMRMwEQYDVQQHEwpXYXNoaW5ndG9uMRcwFQYDVQQKEw5BQk
    EuRUNPTSwgSW5jLjEZMBcGA1UEAxMQQUJBLkVDT00gUm9vdCBDQTEeMBwGCSqGS
    Ib3DQEJARYPa2RhZ3Vpb0BhYmEuY29tMB4XDTk4MDcyOTE2NTk1MloXDTA1MDcy
    NzE2NTk1MlowgYMxCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJEQzETMBEGA1UEBxM
    VFzaGluZ3RvbjEXMBUGA1UEChMOQUJBLkVDT00sIEluYy4xGTAXBgNVBMTEEFCQ
    S5FQ09NIFJvb3QgQ0ExHjAcBgkqhkiG9w0BCQEWD2tkYWd1aW9AYWJhLmNvbTCC
    ASIwDQYJKoZIhvcNAQEBBhuruhtAQoCggEBMae3L3cDgkaUcaSm5lrjGmJvhvFo
    hFOhGYNmfH/H5mhM9a0kouli57Wp5EybSBGp6HUP9zVqdtEFsIE6asCKkaIHIaD
    zN0sVixVm81Nj0zXpPjmgK1obfxzEFNQ3Xo

    -----END CERTIFICATE-----

    For more information, check the sample file available at this location: <server-root>/idar-<hostname>/etc/rootcerts.pem

  3. Save the file.

    This file must contain all the CA certificates in the PEM format.

  4. Make sure iDAR has read permission to the file. Also note the file path as you'll be required to specify this information later.


Step B. Add iDAR CA Certificate to Clients' Trust Databases

When iDAR presents its certificate to an LDAP client, the client tries to verify the validity of the certificate. As a part of this verification process, the client checks whether the CA that has issued the certificate is trusted by the client. For this reason, the root certificate of the CA that issued iDAR's server certificate must be installed in the client's trust database.

In the last step of installing iDAR's server certificate, you copied the iDAR's CA certificate to a text file. Follow the documentation for each client application, and install the CA certificate in its trust database.


Step C. Make Changes to the iDAR System Configuration

The Settings and Encryption tabs in the System Configuration window enable you to define SSL-enabled communication criteria for iDAR. For details, see Creating System Configuration Objects.



Make the following changes to the appropriate system configuration objects, and save your changes.

  • In the Settings tab, specify a value in the "SSL port" field. iDAR will listen on the port number you specify for LDAPS (LDAP over SSL) connections. By default, iDAR does not listen for connections from LDAPS clients. This value must be present to enable LDAPS connections from clients that use the alternative port 636 method to establish TLS/SSL. This value must be different from the value in the Port field. (This option also requires TLS/SSL configuration found on the Encryption tab.)

    If you need description for the parameters, click the Help button or check Step 5 of Creating System Configuration Objects.

  • In the Encryption tab, specify all the required information.

    If you need description for the parameters, click the Help button or check Step 6 of Creating System Configuration Objects.


Step D. Make Changes to the iDAR Network Groups

iDAR uses network groups to identify clients and determine their access privileges to the information contained in an LDAP directory; for details, see Chapter 6 "Creating and Managing Groups."



In each group that you've configured, set the appropriate options in the Encryption tab to indicate whether you want to force the client to start a TLS session before sending any LDAP operation, leave the decision to the client, or disallow the client to start a TLS session. For example, you might want to enable "SSL is available" and "Clients MUST establish an SSL session" options. For more information about the options presented in the Encryption tab, see Step 9 of Chapter 6 "Creating and Managing Groups."

If referral following is enabled, you should check the Referral SSL Policy. Referral following is enabled by selecting Referrals in the list on the left side of the window.


Step 3. Set Up SSL Connections Between iDAR and LDAP Servers

To set up SSL connections between iDAR and LDAP servers, follow these steps:


Step A. Create a File With CA Certificates in PEM Format

This step is required if you want iDAR to verify the certificate presented to it by an LDAP server. If you've already created a file with the trusted CA certificates of the CAs that issued the LDAP client certificates, add the CA certificates of the LDAP servers to the same file. For details, see Step A. Create a File with CA Certificates in PEM Format.


Step B. Add iDAR CA Certificate to the LDAP Servers' Trust Databases

When iDAR presents its certificate to an LDAP server, the server tries to verify the validity of the certificate. As a part of this verification process, the server checks whether the CA that has issued iDAR's certificate is trusted by the server. For this reason, the root certificate of the CA that issued iDAR's server certificate must be installed in the LDAP server's trust database.

In the last step of installing iDAR's server certificate, you copied the iDAR's CA certificate to a text file. Follow the documentation for each LDAP server, and install the CA certificate in its trust database. If you're using iPlanet Directory Server, you can use the Manage Certificates Wizard, which can be launched from the Tasks tab of the Directory Server Console, to add the CA certificate to the Directory Server's trust database.


Step C. Make Changes to the LDAP Server Properties

The Encryption tab in the LDAP Server Property window enables you to define SSL-enabled communication criteria for each LDAP server. For details, see Creating LDAP Server Property Objects.



Make the following changes to the appropriate LDAP Server property objects, and save your changes.

  • Set the "Security policy" option to an appropriate value so that iDAR will always establish SSL/TLS to the backend server, never establish TLS/SSL to the backend server, or only establish SSL/TLS with the backend server when the client does the same to iDAR.

  • Set the "X.509 certificate subject DN" field to the LDAP server's certificate subject name (the subject attribute in the X.509 certificate). If specified, iDAR will attempt to match the certificate subject with the subject present on the LDAP server's certificate and will reject a TLS session if there is a mismatch. (This attribute allows iDAR to authenticate the LDAP server to which it is connecting. iDAR accepts any name if this attribute is not set.)


Previous     Contents     Index     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated July 26, 2001