Configuration

This chapter describes how to configure DirX Directory for CSP, including how to configure:

  • SSL/TLS protection for X.500 protocols

  • Replication

  • Authentication-related attributes and policies

  • LDAP servers

Configuring Encrypted X.500 Protocols

DirX Directory supports performing the X.500 protocol exchanges over a secure IDM stack (IDMS), where the SSL/TLS protocols are applied over the transport layer.This mechanism affects the DAP protocol exchanges initiated by the DUAs (the dirxcp client application or the LDAP server process) as well as the DSA-to-DSA protocol exchanges for replication (DISP) and chaining (DSP).

While SSL/TLS allows performing a mutual authentication of the communication peers, the goal of using IDMS in DirX Directory is the encryption of the protocol data exchanged.

Configuring IDMS includes the following tasks:

  • Using the addressing in PSAPs to activate IDMS

  • Installing individual IDMS key material (optional)

Setting up IDMS Addressing

In DirX Directory, the DNS component of a PSAP address contains the information about whether DAP, DISP or DSP is performed over plain IDM or over protected IDMS.

Initializing IDMS

The DNS subcomponent in each communicating process’s own address is used to initialize IDMS. This address is defined by:

  • The environment variable DIRX_OWN_PSAP for the DSA

  • The SELF entry in dirxcl.cfg and dirxldap.cfg for the DUAs

If the address contains an SSLPORT with a value greater than zero, the IDMS stack is initialized. In the DSA process, IDMS starts a communication listener on the port specified in SSLPORT.

The MODE keyword has no meaning in the address and can therefore be omitted.

For example, to initialize the IDMS stack in the LDAP server process on the master directory server host, the LDAP server’s dirxldap.cfg configuration file must contain a SELF address with an SSLPORT:

Self TS=Client1,NA='TCP/IP_IDM!internet=1.2.3.4+port=1111',DNS='(HOST=hostM,SSLPORT=21201,PLAINPORT=21200)'

Connecting to Communication Peers via IDMS

To connect to a peer DSA, the initiator of the connection uses the DNS subcomponent of the remote DSA’s address and its own initialization state.

The remote address is defined by:

  • The PSAP from the CK for a shadow supplier DSA as an initiator.

  • The PSAP from the SUK for a shadow consumer DSA as an initiator.

  • The PSAP from the XR, SUBR or SUPR for a DSA in a distributed directory as an initiator.

  • The contact DSA entry in dirxldap.cfg for the DUA in the LDAP server process.

  • The named DSA entries in dirxcl.cfg for the DUA in dirxcp.

The relevant parts of the remote DSA’s DNS are the MODE and the SSLPORT. If the MODE is set to SSL and the SSLPORT has a value greater than zero, the process connects via IDMS to the specified port of the peer.

For example, to connect securely via IDMS to the DSA, the LDAP server process on the master directory server host must have the following entry in its dirxldap.cfg configuration file as the contact DSA:

/CN=masterDSA TS=DSA1,NA='TCP/IP_IDM!internet=1.2.3.4+port=21200',DNS='(HOST=hostM,SSLPORT=21201,PLAINPORT=21200,MODE=SSL)'

For more examples of how the DNS component controls IDMS usage, see the section “Setting up Replication”.

Installing IDMS Key Material

IDMS is based on the SSL/TLS security protocols, which require suitable cryptographic key material in order to function.

The DirX Directory product setup installs sample key material that allows for performing IDMS-protected X.500 protocols out of the box. However, users may wish to install their own individual key material.

The client, ldap and server subfolders of the DirX Directory installation folder contain a configuration file named idmssl.cfg with the names and locations of the files containing the necessary key material. Here is the content of idmssl.cfg as installed:

#########################################
# SSL Configuration file for IDM protocol
# each line contains a token and a value
#########################################

# the pathname of the file containing the own private key and
# certificate chain in PEM format
idm_ssl_own_pse_file $DIRINST/conf/IdmPSE.pem

# the pathname of the password file for accessing the private key
idm_ssl_pwd_file $DIRINST/conf/IdmPSE.pwd

# the pathname of the PEM file that contains trusted CA certificates
# the file may contain multiple CA certificates in PEM format.
# In client mode, these CA certs are used to verify the certificate
# received from the server.
idm_ssl_trusted_ca_cert_file $DIRINST/conf/testCA.pem

# security protocol to be used - one of: SSLv3, TLSv1, TLSv11, TLSv12
idm_ssl_protocol TLSv12

#  ciphers to use (names must be compatible with OpenSSL naming schema)
idm_ssl_ciphers HIGH

# max wait time in seconds in SSL I/O
idm_ssl_io_timeout 10

# SSL log level (0=off,1=low)
#  0 = off
#  1 = low    (SSL function calls)
#  2 = medium ( == low + select/poll eventing )
#  3 = high   ( == medium + I/O data )
idm_ssl_logging 0

#########################################

The variable $DIRXINST shown in the example is replaced with the actual installation path during installation time.

Exchanging the installed example key material with individual keys can be done on a per-host basis; for example, by placing a suitable PEM file with its own private key and the certificate chain in the conf subfolder of the installation path for use by all DirX Directory processes (like the sample key material setup).Alternatively, each DirX Directory process type (dirxcp, dirxldapv3 and dirxdsa) can access individual key material files.

Setting up Replication

Setting up distributed DirX Directory service replication in the CSP environment includes the following tasks:

  • Setting up DSA names and PSAP addresses

  • Setting up shadowing agreements

  • Configuring attribute indexes

  • Configuring the CSP frontend/portal application for LDAP server support

The next sections describe these tasks in more detail.

Specifying PSAP Addresses and DSA Names

Each DSA must have a DN and a PSAP address that identifies the DSA remotely and detects its role in a distributed replication scenario. Both of these elements are configured as variables in the file:

install_path/conf/dirxenv.ini.

The following excerpt of a configuration file shows the respective lines for the shadow supplier DSA:

# DSA name and PSAP address
set DIRX_DSA_NAME=cn=masterDSA
set DIRX_OWN_PSAP=TS=DSA,NA='TCP/IP_IDM!internet=1.2.3.4+port=21200'
,DNS=’(HOST=hostM,PLAINPORT=21200,SSLPORT=21201,MODE=SSL)’

The following excerpt of a configuration file shows the respective lines for one of the shadow consumer DSAs:

# DSA name and PSAP address
set DIRX_DSA_NAME=cn=consumerDSA1
set DIRX_OWN_PSAP=TS=DSA,NA='TCP/IP_IDM!internet=1.2.3.4+port=21200'
,DNS=’(HOST=hostC1,PLAINPORT=21200,SSLPORT=21201,MODE=SSL)’
The syntactically correct (but unknown) value 1.2.3.4 is specified for the NA component of the Presentation-Address structured attribute because X.500 defines the NA component as mandatory. DirX Directory has added support for the DNS component, which is used with priority. If the DNS component is present in a PSAP, DirX Directory uses the hostname specified and resolves it by means of the DNS to a network address, and uses it together with the (plain or SSL) port to connect. Correct DNS configuration is therefore a prerequisite for using the DNS component in PSAP addresses.

Creating the Shadowing Agreements

The floating master setup with multiple hot-standby consumer DSAs ensures high availability of the service for retrieval operations and allows for shutting down servers for maintenance reasons without interrupting the service. In the worst case – a crash of the shadow supplier server – one of the shadow consumer DSAs can take over the supplier role via the emergency switch command.

Using only the DNS component of the PSAP addresses of the participating DSAs creates a central administration point (the DNS server or the /etc/hosts file) that defines the physical endpoints of a communication. This setup allows for easily moving a server from one host to another and avoids having to reconfigure clients with the address of the shadow supplier DSA.

Shadowing agreements are administered using the dirxadm sob commands. The commands are performed on the shadow supplier DSA. The shadow configuration is stored in a special subentry named cn=cooperating-dsas-subentry, which contains entries for all participating DSAs with their DNs, their PSAPs, and their roles in the system.

The following dirxadm sob create operation creates the replication setup between the master DSA and consumer DSA 1, as shown in "Figure 1: Network Hosts and Applications".

dirxadm> sob create -supplier {/cn=masterDSA} –supplierpsap \ "TS=DSA,NA='TCP/IP_IDM!internet=1.2.3.4+port=21200',DNS=(HOST=hostM,PLAINPORT=21200,SSLPORT=21201,MODE=SSL)’" \
 -consumer {/cn=consumerDSA1} –consumerpsap \ "TS=DSA,NA='TCP/IP_IDM!internet=1.2.3.4+port=21200',DNS=’(HOST=hostC1,PLAINPORT=21200,SSLPORT=21201,MODE=SSL)’"\
 -consumerkind CENTRALADMIN \
 -agreementid 1 -status cooperative \
 -pol {CONS={REPLS=TRUE}} \
 -agreement "SS={AREA={CP={/O=My-Company},RA={DEF=TRUE}}, \
          ATT={DEF=TRUE}}, \
          UM={SI={OC=TRUE}}" \

This operation creates the shadowing agreement with the agreementID 1, which specifies the shadowing agreement from the master DSA to the consumer DSA 1: The policy option (-pol) allows the consumer DSA to become the master via the sob switch operation. The agreement is specified as a full shadow, which means that all entries are replicated with all their attributes immediately after the entry is modified on the master DSA to the consumer DSA. The agreement is created with the status cooperative, which means that after completing the command, the supplier starts sending the whole directory tree to the consumer (DISP total update). By specifying MODE=SSL in consumerPSAP, the agreement is set up to communicate over IDMS.

According to the example in "Figure 1: Network Hosts and Applications", agreements 2 and 3 must be created with analogous dirxadm operations.

Configuring the Index

Index setup for shadow suppliers is different from the setup for shadow consumers. On the shadow supplier, an attribute index is not needed or is even inappropriate because the index would need to be updated after the attribute is modified. On the shadow consumer, the attribute index is needed because this is where the search operations are performed. Consequently, the administrator should create the indexes for the userCertificate attribute only on the shadow consumer DSAs.

Use the dirxadm db attrconfig operation to perform attribute index configuration. The following operation creates suitable indexes for certificate searches. The command must be performed on all three consumer DSAs.

dirxadm> db attrconfig uc -index INITIAL ANY

Configuring the CSP Application for LDAP Servers

The administrator needs to set up and configure the CSP frontend/portal application so that the LDAP read requests issued on behalf of public users are directed to one of the LDAP servers connected to a consumer DSA.The administrator can use an LDAP load balancer to achieve this configuration; for example, by configuring the list of the IP addresses of Host C1, Host C2 and Host C3 with their respective ports as the addresses to use.These LDAP servers can be configured as read-only servers via their LDAP configuration subentries.

Write access to the directory server should be directed to the LDAP server(s) connected to the shadow supplier DSA.

Configuring Authentication-related Attributes and Policies

This section describes how to configure authentication-related attributes and policies.

Configuring Administrators

Administrators in DirX Directory are represented by entries that contain a userPassword attribute as the credential for the simple LDAP bind operation.Alternatively, the administrators can perform strong authentication (LDAP Simple Authentication and Security Layer (SASL) binds with the mechanism type “EXTERNAL”) based on their Personal Security Environments (PSEs).

The access control items of access control subentries control the administrative privileges of administrators that are needed to perform LDAP operations.There are two other places where privileges must be administered:

  1. DirxAdministrators

    The DirxAdministrators (DADM) attribute of the root DSE (/) controls which authenticated users are allowed to execute operations via the dirxadm administrative client operation.

    Adding DNs to the DADM attribute is performed via dirxadm as part of the bootstrap process.

    Here is an example of how to add the administrator to the DADM attribute:

    dirxadm> modify / -add DADM=/O=My-Company/ou=admins/cn=admin

  2. ldapExtOpAdmins

    The ldapExtOpAdmins attribute of the LDAP configuration subentry controls which authenticated users are allowed to perform LDAP extended operations. LDAP extended operations allow retrieving configuration and state information about the DirX Directory server processes and performing administrative tasks; for example, enabling and disabling auditing and caching. The dirxextop command performs LDAP extended operations.

    Adding DNs to the ldapExtOpAdmins attribute is performed via LDAP. DirX Directory also provides more fine-grained access rights to LDAP extended operations. (See section “Attributes Controlling LDAP Extended Operations” of chapter “DirX Directory Attributes” in the DirX Directory Administrations Reference for details.)

    Here is an example of how to add an administrator to the ldapExtOpAdmins attribute with the dirxcp command:

    dirxcp> modify CN=ldapConfiguration,O=My-Company \
  -add ldapextopadmins=CN=admin,OU=Admins,O=My-Company

Configuring DSA Policy

The DirX Directory DSA policy describes - among other options - the authentication methods and the DSA passwords used for the DSA-to-DSA bind operations occurring in the replication protocol (DISP) and in the chaining protocol (DSP). The DSA policy is stored in the DSA-Policy attribute (DSAP) of the X.500 root entry (/) and is administered with the dirxadm command.

In the context of CSP operation, we recommend that all DSAs perform binds with individual DSA passwords using the Simple-Protected X.500-defined mechanism.

The following set of dirxadm operations instantiates the DSA policies. It must be applied to all participating DSAs (master and all consumer DSAs):

dirxadm> modify / -add DSAP={DSA={/CN=MasterDSA},            \
                             AP={AMB={AM=SIMPLE-PROTECTED},  \
                                 PWD=masterPWD             \
                                }                            \
                            };

dirxadm> modify / -add DSAP={DSA={/CN=ConsumerDSA1},         \
                             AP={AMB={AM=SIMPLE-PROTECTED},  \
                                 PWD=consumer1PWD             \
                                }
                            };

dirxadm> modify / -add DSAP={DSA={/CN=ConsumerDSA2},         \
                             AP={AMB={AM=SIMPLE-PROTECTED},  \
                                 PWD=consumer2PWD             \
                                }                            \
                            };
The DSA policy should be configured before the shadow agreements are established as part of the replication setup.

Configuring User Policy

The DirX Directory user policy describes the authentication methods allowed for particular users, expressed by subtrees or specific DNs. The user policy is stored in the User-Policy attribute (USP) of the X.500 root entry (/) and is administered with the dirxadm command.

In the context of CSP operation, the user policy forces particular users to perform strong authentication methods when binding to the DirX Directory service.

The following dirxadm modify operation provides an example of how the certificate administrator can be forced to authenticate using a strong bind method.

dirxadm> modify / -add USP={USN={/O=My-Company/CN=certAdmin}, \ AP={AMB={AM=STRONG}}}

The effect of this command is that the user named CN=certAdmin,O=My-Company is unable to bind to the directory unless he uses the SSL/TLS client authentication, which is the only bind mechanism supported by DirX Directory with a STRONG authentication level. This method requires that the user owns a Personal Security Environment (PSE) and that the issuer of the PSE is trusted by the DirX Directory server. (See the description of the LDAP server SSL configuration attribute ldapTrustedCACerts in section 3.4.3, "Configuring the Additional LDAP Server on the Master" for details.) The following dirxcp bind operation provides an example for an SSL/TLS client authentication:

dirxcp> bind -prot ldapv3 -sasl -mech EXTERNAL -certsub certAdmin
-key3pass PSE-passwphrase -address localhost:1636

When this user policy is applied, any other type of bind will not succeed for the user with the DN CN=certAdmin,O=My-Company, while other users are unaffected.

Configuring Password Policy

DirX Directory password policy supports the users and administrators in choosing secure bind passwords. The password aging feature ensures that passwords are changed within the specified time frame. The account-locking feature is intended to prevent dictionary attacks on passwords. Password policies are stored as special X.500 subentries in DirX Directory. They can be created using the dirxcp obj create operation.

The following dirxcp create operation creates an example password policy subentry:

dirxcp> create CN=CSP-PwdPol,O=My-Company -attr \
{subtreeSpecification;binary=MIAAAA==} \
{ocl=pwdPolicy;subEntry} pwdMinAge=3600 pwdMaxAge=15552000
pwdInHistory=10 pwdCheckQuality=2 pwdMinLength=8 \
pwdMinSpecialChar=2 pwdMaxLength=10 pwdExpireWarning=864000 \
pwdLockout=TRUE pwdMaxFailure=3 \
pwdFailureCountInterval=120 pwdMustChange=TRUE \
pwdExclusions=CN=admin,O=My-Company \

The effect of this subentry is reported by the DirX Directory DSA during startup of the service by the following message:

DSA Password Policy Info:
Password Policy Settings:
Relevant Subentry: cn=CSP-PwdPol,o=My-Company
 Password Syntax check:    Enabled, reject hashed Passwords
  Minimal Password Length:  8
  Minimal Number of specials: 2
  Maximal Password Length:  10
  Password History Size:   10
 Password Aging:
  Password expires after:   15552000 sec (180 days)
  Warning sent before Expiry: 864000 sec (10 days)
  Grace Logins after Expiry: None
  Minimal Password Age:    3600 sec (1 hours)
 Account Lockout:       Enabled
  Lockout Duration:      Forever (until reset by admin)
  Account locked after:    3 consecutive failed logins
                within 120 sec
 Password Change after Reset: Required
 Password Policy Exclusions:  1 Entry/Node
  DN: CN=admin,O=My-Company

That is, all users that perform password-based bind operations with the exception of the administrator named CN=admin,O=My-Company must change their passwords every 180 days, the password must be conform to the syntax rules and the 10 most recent passwords must not be used. Three attempts to bind with incorrect passwords within 120 seconds cause the account to be locked. The administrator must unlock the account explicitly.

Disabling External Authentication

DirX Directory can be configured to forward incoming simple authenticated bind operations over LDAP to an external authentication service such as the Windows Domain Controller or to an external LDAP server.Bind forwarding should not be used in the context of a CSP.

To disable external authentication, the configuration file

install_path/server/conf/dirxextauth.cfg

must not exist.This is the default condition after installing the product.

Configuring the LDAP Servers

A set of subentries specifies the configuration of the DirX Directory LDAP server.Unless default values should be used, each LDAP server process needs the following types of subentries:

  • A subentry with the objectClass ldapConfiguration.This subentry stores the LDAP server’s general configuration and contains attributes that control, for example, the ports on which the LDAP server listens, the serviceControls applied to the DAP requests sent to the DSA, properties like read-only, LDAP client IP addresses and users denied or allowed to bind to the server and many more.

  • A subentry with the objectClass ldapSSLConfiguration.This subentry stores the LDAP server’s SSL/TLS security configuration; for example, the LDAP server’s own key material and whether or not the LDAP server requires SSL/TLS client authentication.

  • A subentry with the objectClass ldapAuditConfiguration.This subentry stores the LDAP server’s auditing configuration; for example, the strategy to be applied after an audit file exceeds its maximum size or the degree of detail of the audit records.

Because the LDAP server configuration subentries are subject to replication (as is every entry or subentry within a replication area), the administrator only needs to administer the configuration subentries on the master server.The replication process then distributes all subentries to all consumer servers.

In the context of the scenario shown in Figure 1: Network Hosts and Applications, a single ldapAuditConfiguration subentry controls the audit configuration of all the LDAP servers because there is no need to have a different audit behavior.See section 5.1.2 "Enabling LDAP Audit" for details on creating the LDAP audit subentry.

For the general configuration and the SSL aspects of the LDAP servers, there are different requirements on the particular hosts. Therefore there are individual sets for ldapConfigurations and ldapSSLConfigurations. The LDAP server processes on the hosts will find their individual configuration by matching the commonName of the ldapConfiguration subentry with the value of the environment variables

DIRX_DEFAULT_LDAP_SERVER or DIRX_ADDITIONAL_LDAP_SERVERS

Configuring the Shadow Servers

The shadow server hosts are “HostC1” and “HostsC3”. Configuring these servers means specifying the attributes and values of the configuration subentries cn=lcfgShadow and cn=lcfgSSLShadow. The configuration specifies read-only LDAP servers listening on ports 389 (LDAP) and 636 (LDAPS). LDAP extended operations are prohibited. The SSL/TLS-secured access does not require client authentication via the LDAP SASL bind.

By setting the following variable in the configuration file install_path/conf/dirxenv.ini:

set DIRX_DEFAULT_LDAP_SERVER=lcfgShadow

the LDAP server process on these hosts use the individual configuration subentries.

In detail, the configuration subentries are created with the following dirxcp (LDAP) operations:

dirxcp> create CN=lcfgShadow,O=My-Company -attr \
{subtreeSpecification;binary=MIAAAA==} \
{ocl=ldapConfiguration;subentry} \
ldapPortNumber=389 \
ldapSecurePortNumber=636 \
ldapReadOnlyServer=TRUE \
ldapExtOpAdmins=none \
ldapSSLCfgSubentryCN=ldapSSLConfiguration \
ldapAuditCfgSubentryCN=CommonldapAudit

dirxcp> create CN=ldapSSLConfiguration,O=My-Company -attr \
{subtreeSpecification;binary=MIAAAA==} \
{ocl=ldapSSLConfiguration;subentry} \
supportedEncryptionStrength=HIGH
{supportedSecurityProtocols=SSLV3.0;TLS1.0}
requireSSLClientAuth=FALSE \
ldapOwnKeyMaterialPEM_FILE=url of the PEM file with key material
The supportedSecurityProtocol setting depends on the capabilities of the LDAP client—the CSP Front End/Portal application—that connects to the LDAP server; for example, JRE 7-based LDAP client applications support newer versions of TLS, like TLSv1.1.

Configuring the Default LDAP Server on the Master

The default LDAP server runs on the host “HostM”. Configuring the default LDAP server means specifying the attributes and values of the default configuration subentries cn=ldapConfiguration and cn=ldapSSLConfiguration. The configuration specifies a read-write LDAP server listening on ports 389 (LDAP) and 636 (LDAPS). The entry named CN=admin,OU=Admins,O=My-Company is allowed to perform LDAP extended operations. The SSL/TLS secured access does not require client authentication via the LDAP SASL bind.

Because the default subentries are used, no environment variable must be set to publish the common name of the configuration subentry.

In detail, the configuration subentry is created with the following dirxcp (LDAP) operation:

dirxcp> create CN=ldapConfiguration,O=My-Company -attr \
{subtreeSpecification;binary=MIAAAA==} \
{ocl=ldapConfiguration;subentry} \
ldapPortNumber=389 \
ldapSecurePortNumber=636 \
ldapReadOnlyServer=FALSE \
ldapExtOpAdmins=CN=admin,OU=Admins,O=My-Company \
ldapSSLCfgSubentryCN=ldapSSLConfiguration \
ldapAuditCfgSubentryCN=CommonldapAudit

Configuring the Additional LDAP Server on the Master

An additional LDAP server process is to be started on host “HostM” that requires SSL client authentication. This configuration is achieved by exporting the following environment variable that publishes the name of the configuration subentry for the additional LDAP server:

set DIRX_ADDITIONAL_LDAP_SERVERS=lcfgSasl+7999

The corresponding subentries are named cn=lcfgSasl and cn=lcfgSSLSasl. The configuration specifies a read-write LDAP server listening only on the LDAPS port 1636. LDAP extended operations are prohibited. The SSL/TLS secured access requires client authentication via the LDAP SASL bind.

This LDAP server is intended to perform the operations initiated by the certificate administrator named CN=certAdmin,OU=Admins,O=My-Company.

In detail, the configuration subentries are created with the following dirxcp (LDAP) operations:

dirxcp> create CN=lcfgSasl,O=My-Company -attr \
{subtreeSpecification;binary=MIAAAA==} \
{ocl=ldapConfiguration;subentry} \
ldapPortNumber=0 \
ldapSecurePortNumber=1636 \
ldapReadOnlyServer=FALSE \
ldapExtOpAdmins=none \
ldapSSLCfgSubentryCN=lCfgSSLSasl \
ldapAuditCfgSubentryCN=CommonldapAudit

dirxcp> create CN= lCfgSSLSasl,O=My-Company -attr \
{subtreeSpecification;binary=MIAAAA==} \
{ocl=ldapSSLConfiguration;subentry} \
supportedEncryptionStrength=HIGH
{supportedSecurityProtocols=SSLV3.0;TLS1.0}
requireSSLClientAuth=TRUE \
ldapOwnKeyMaterialPEM_FILE=url to the PEM file with key material \
ldapTrustedCACerts_FILE=url to CA certificate file trusted to issue user certs