DirX Identity Program Files

The command-line programs metacp, metacpdump and metahubdump use the following files:

  • The DirX Identity client log and trace message configuration files (install_path/client/conf/dirxlog.*). The logging configuration files control the trace and exception messages that metacp logs. The metacpdump program is used to interpret the trace message section of the generated log files. The default location of the generated log files is install_path/client/log.

  • The Directory client configuration file (dirxcl.cfg). The metacp program uses this file to locate Identity stores during a bind operation.

  • The Identity controller (metacp) SSL/TLS certificate database (cert8.db). The metacp program uses this file to determine whether it can trust certificates sent from directory server when a bind operation specifies the use of SSL/TLS protocol. This file also contains the user certificates sent from directory clients when a bind operation specifies the use of certificate-based client authentication (SASL EXTERNAL).

  • The Identity controller (metacp) SSL/TLS key database (key3.db). The metacp program uses this file to access its private key when a bind operation specifies the use of certificate-based client authentication (SASL EXTERNAL).

  • IDMS configuration and key material files. The IDMS configuration and key material files contain the parameters for SSL/TLS initialization when the DirX DSA, LDAP server or metacp program use the encrypted variant of the X.500 protocols over IDM (IDMS) and the necessary key material files.

This chapter describes these files.

Logging Configuration Files for metacp

dirxlog.on
dirxlog.off
dirxlog.cfg

Purpose

Logging configuration files define the messages to be logged and how and where the logs should be written.Two types of messages can be logged:

  • Exception Messages - ASCII format messages that are human-readable. The directory service always logs exception messages for both servers and clients.

  • Trace Messages - Binary format messages that must be read by the metacpdump command. Trace logging can be turned on and off explicitly.

Description

DirX Identity client logging (for example, metacp) is controlled by the specifications contained in the install_path/client/conf/dirxlog.cfg file. When DirX Identity is installed, the following configuration files specifying default values are installed for client logging:

install_path/client/conf/dirxlog.cfg

(enables only client exception logging)

install_path/client/conf/dirxlog.on

(enables default client trace and exception logging)

install_path/client/conf/dirxlog.off

(enables only client exception logging)

The client log files are written to the directory install_path/client/log.

Enabling Logging

  • Enable client logging:

    Before starting the application, copy the configuration file install_path/client/conf/dirxlog.on to the file install_path/client/conf/dirxlog.cfg.

  • Disable client logging:

    Before starting the application, copy the configuration file install_path/client/conf/dirxlog.off to the file install_path/client/conf/dirxlog.cfg.

The .on and .off files for DirX Identity client logging are installed in install_path/client/conf.

You can modify the .on and .off files to define your desired logging parameters, and you can create additional files that function in a manner similar to the .on and .off files and manually maintain the copy from dirxlog.cfg to these files.

You can override the default file name for the logging configuration file by setting the DIRX_LOGCFG_FILE environment variable to the full pathname of the file. This is NOT recommended because metacp, the Server (IDS-C) and the DirX dirextory server will read the same logging configuration file if they are restarted.

Use the logging configuration .on and .off files to perform the following tasks:

For trace logging:

Turn on client trace logging and specify the traces to be logged and the destinations for the log files

Turn off client trace logging for all or selected directory subcomponents

For exception logging:

Override the default exceptions logged for clients and the default destination for the log file

Turn client exception logging off for all or selected directory subcomponents

File Formats

All logging configuration files consist of two sections: one that defines trace logging and one that defines exception logging. The following subsections describe the format of the trace logging and exception logging sections.

The Trace Logging Section

The trace logging section defines the component and subcomponents for which to capture trace messages and the debug level of the traces to log. It consists of a line in the format:

component:subcomponent.level,[…​]:
process.max_num_files.max_num_entries:_file_name_

where:

component

Is the name of the component to log. All directory log file entries are currently associated with the dir component name. All DirX Identity log file entries are currently associated with the mdi component name.

subcomponent

Is the name of the subcomponent to log and the debug level of the traces to capture. The valid values for subcomponent are listed in the table that follows.

You can use a wildcard character (*) to specify all subcomponents. In this case, however, the debug levels you specify with level are used for all subcomponents.

The mdi component supports the following DirX Identity subcomponent names:

Value Meaning

meta

Dir Identity client interface

The dir component supports the following directory subcomponent names:

Value Meaning

adm

Administration

api

Application interface

bth

Bind table handling

ctx

Context-specific memory interface

icom

Internal thread communication interface

osi

OSI communication

ros

Remote operation service

sock

Socket interface

sys

System call interface

util

Utility functions

vthr

Virtual thread interface
level

Specifies the debug level of the traces to log. Level is an integer or list of integers ranging from 0 through 9. You can specify debug levels:

  • As a range. For example, 1-5 indicates debug levels 1 through 5 inclusive

  • As individual levels separated by a period. For example, 1.3.4.5 indicates levels 1, 3, 4, and 5

  • As a combination of ranges and individual levels. For example 1.3-5 indicates level 1, 3, 4, 5.

The integers 0 and 9 have special meanings. Level 0 disables logging for the subcomponent. (Not listing the subcomponent at all has the same effect.) Level 9 causes the structures in a trace function to also be evaluated for each log level specified; that is, the contents of the interface parameters defined as structures are also logged. (Note that the structure logging can create extremely large log files.) You can turn on level 9 for each valid value for level.

Levels 1-8 log the contents of the other parameters. Level 1 logs the top-level functions, while the higher log levels determine the depth of the internal functions that are logged. For example, level 6 traces the function call foo with parameters. If levels 6 and 9 are specified, function call foo is traced with parameters and with the structures of those parameters.

You can specify multiple subcomponent*.level entries, separating each with a comma and using a backslash (\) to continue the line. Without the backslash, the *NEWLINE character terminates the line.

There are the following level values for the component mdi:

Sub-com-ponent Valid value for level Usage

meta

1

2

Interface functions of the DirX Identity client interfaces

Internal interface functions of the DirX Identity client interfaces

There are the following level values for the component dir:

Sub-com-ponent Valid value for level Usage

adm

1

2

4

5

6

7

8

metacp (Administration) translator functions

metacp internal functions for abandon operation

LDAP client functions, such as BIND, SEARCH, CREATE etc.

LDAP functions for extracting names/attributes from a search result

LDAP functions for freeing internally used LDAP memory

OCL functions (OSS Convenience library, string parsing)

DAM functions (dir abbreviation module, that is functions for reading and writing the abbreviation file and validation of abbreviations)

api

1-2

Interface functions and internal functions of application interface

bth

1

2

3

4

5

6

Bind table handling functions (binding entries handling)

Operation entries handling

Subscriber handling

lock / unlock functions

resume_info handling

bind_waiter handling

ctx

1

2

3-6

CTX package (context-specific memory) interface functions related to context creation/deletion

CTX package interface functions related to context memory allocation/release

CTX package internal functions

osi

1

3

Incoming/outgoing event-handling functions

TP routines

ros

1

3

4

6

7-8

RTROS interface functions

RTROS internal functions

CMX interface functions

AMS compiler logging

AMS (NDS) library functions

sock

1

2

3

4

Socket interface functions (connection establishment)

Data transfer

Event generation

Name handling and utility functions

sys

1

2

3

4

System calls (2)

System library functions (3C)

System library functions (3C) related to memory allocation

WIN32 library functions

util

1

Utility functions

vthr

1

2-3

4

5

6

7

VT package (Virtual thread) interface functions related to threads creation/termination

VT package interface functions related to threads controlling

VT package interface functions related to mutexes

VT package interface functions related to condition variables

VT package interface functions related to thread specific data

VT package internal functions
process

Indicates how to store the log entries. Valid values for process are:

DISCARD - Do not write any log entries.

BINFILE - Write entries to a binary file. You must supply the name of the file. (See the file_name parameter description.) BINFILE must be used for the dir component

TEXTFILE - Write entries to a human-readable text file. You must supply the name of the file. (See the file_name parameter description.)

STDOUT - Write entries in human-readable text to standard output.

STDERR - Write the entries in human-readable text to standard error.

GOESTO:severity…​-Write the entries to same destination as the messages of the specified component. You can specify multiple severities by separating each one with a comma. severity can be:

  • FATAL - Fatal errors

  • ERROR - Non-fatal errors

  • WARNING - Warnings

  • NOTICE - Informational notices

  • NOTICE VERBOSE - Verbose informational notices

max_num_files

The maximum number of log files to create (a number from 01 to 99 inclusive). When the first log file reaches its capacity (specified by max_num_entries), a second file is written and so on until the number of files specified by max_num_files is reached. When the maximum number of files is reached, the next file overwrites the first file, and the next the second file, and so on. If multiple files are written, the sequence number of the file (a number in the range 01 to the number specified by max_num_files) is appended to the file name.

max_num_entries

The maximum number of entries to write to the file.

file_name

The full pathname of the file in which to store the entries. You can use the %s variable to insert the pathname of the base directory in which DirX Identity is installed in the file name. (See the description of $DIRXMETAHUB_INST_PATH in the DirX Identity Environment Variables chapter for details.) You can use the %d variable to insert the ID of the currently running process in the file name. For example, LOG%d creates a file named LOG appended with the process ID. You must supply file_name only if you supply a process parameter of BINFILE, TEXTFILE, and FILE.

Sample Trace Section Lines

The following sample line uses the wildcard character to specify logging for all subcomponents. It captures debug messages of levels 1-5 and level 9. The %s variable is used to insert the base directory in which DirX Identity is installed, for example C:/Program Files/Atos/DirX Identity in the file name. The %d variable is used to store the log messages in a file named LOGprocess_id:

dir:*.9.1-5:BINFILE.2.200:%s/client/log/LOG%d

The following sample specifies the logging of level 1 messages from the adm and api subcomponents and of level 2 messages from the sys, vthr, and util components:

dir:adm.1,api.1,\
sys.2,vthr.2, util.2:\
BINFILE.2.200:C:/Program Files/Atos/DirX Identity/client/log/LOG%d

In both of the sample lines above, two binary log files are created. The first 200 log entries are written to the file C:/Program Files/Atos/DirX Identity/client/log/LOG*process_id.01* and the second 200 log entries are written to the file C:/Program Files/Atos/DirX Identity/client/log/LOG*process_id.02*. Then LOG*process_id.01* is overwritten with the next 200 log entries, then LOG*process_id.02* is overwritten and so on.

Depending on the logging configuration, the binary log files can become very big. It is recommended to configure only the log levels needed, for instance:

ros.4.9    in order to trace all DAP, DSP or DISP-PDUS
vthr.1    in order to trace the interthread communication
The Exception Logging Section

The exception logging section of the logging configuration files defines the severity of exceptions to log and how and where to log them. It consists of lines in the following format:

severity:process.max_num_files.max_num_entries:file_name

where:

severity

Specifies the severity of the exception to store. Valid values are:

FATAL - Fatal errors

ERROR - Non-fatal errors

WARNING - Warnings

NOTICE - Informational notices

NOTICE VERBOSE - Verbose informational notices

process

Indicates how to handle the log entries for the specified severity. Valid values, which can be used with any of the severities listed above, are:

DISCARD - Do not write any log entries.

BINFILE - Write entries to a binary file. You must supply the name of the file. (See the file_name parameter description.) BINFILE must be used for the dir component

TEXTFILE - Write entries to a human-readable text file. You must supply the name of the file. (See the file_name parameter description.)

STDOUT - Write entries in human-readable text to standard output.

STDERR - Write the entries in human-readable text to standard error.

GOESTO:severity_or_component…​-Write the entries to same destination as the entries of the specified severity or component. You can specify multiple severities or components by separating each one with a comma.

max_num_files

The maximum number of log files to create (a number from 01 to 99 inclusive). See the max_num_files parameter in "The Trace Logging Section" for more details.

max_num_entries

The maximum number of entries to write to the file.

file_name

The full pathname of the file in which to store the entries. See the file_name parameter in "The Trace Logging Section" for more details.

Sample Exception Lines

The following example specifies that:

  • Exceptions with severity of FATAL are stored in two places. The first is a text file with up to 100 entries named /usr/tmp /EXCprocess_id. Only one such file is created. When the file reaches 100 entries it is overwritten. The second is not shown in the example. It is the file where the traces for the dir components are stored.

  • Exceptions with a severity of ERROR are stored in three places. The first is a text file with up to 100 entries named /usr/tmp/USRprocess_id. Only one such file is created. When the file reaches 100 entries it is overwritten. The second is the same place where exceptions with a severity of FATAL are stored. The third is the same place where traces for the dir component are stored.

  • Messages with a severity of NOTICE are stored in the same place as messages with a severity of ERROR.

FATAL:TEXTFILE.1.100:/usr/tmp/EXC%d;GOESTO:dir
ERROR:TEXTFILE.1.100:/usr/tmp/USR%d;GOESTO:FATAL
NOTICE:GOESTO:ERROR

Examples

In the examples that follow, lines beginning with the # character are comment lines used to differentiate the trace logging section from the exception logging section.

The following is a sample dirxlog.on file.

# Trace Logging
dir:sys.1,sock.1.9,vthr.1,ctx.0,\
ros.1,\
bth.1,\
util.1-2:BINFILE.6.2000:/usr/tmp/LOG%d
#
# Exception Logging
FATAL:TEXTFILE.1.100:/usr/tmp/EXC%d;GOESTO:dir
ERROR:TEXTFILE.1.100:/usr/tmp/USR%d;GOESTO:FATAL
NOTICE:GOESTO:ERROR
WARNING:GOESTO:FATAL
NOTICE_VERBOSE:GOESTO:FATAL

The following is an example of a dirxlog.off file. Note that the first line of the file turns trace logging off for the dir component. (Exception logging is not disabled.) In addition, the dash is used as a placeholder and indicates an empty field.

# Trace Logging
dir::DISCARD:-
#
# Exception Logging
FATAL:TEXTFILE.1.100:/usr/tmp/EXC%d
ERROR:TEXTFILE.1.100:/usr/tmp/USR%d;GOESTO:FATAL
NOTICE:GOESTO:ERROR
WARNING:GOESTO:FATAL
NOTICE_VERBOSE:DISCARD:-

See Also

metacpdump

Directory Client Configuration File

dirxcl.cfg

Purpose

The directory client configuration file dirxcl.cfg, used by metacp, defines the Identity stores that are available to the meta controller.

Description

The default location for the dirxcl.cfg file is:

install_path/client/conf

You can override the default location by setting the DIRX_CLCFG_FILE environment variable to the full path name of the file.

In the directory client configuration file, comment lines are lines that begin with a # character in the first column and are ignored.

Other than comments, the file contains two types of lines, as follows:

  • A mandatory line for the address of the meta controller

  • Optional Identity store (LDAP server) address lines.

The meta controller address line starts with the word self (case insensitive), followed by the address of the meta controller in valid PSAP address format.

A Identity store address line is specified in the following format:

name address protocol

where:

name

is the symbolic name of the Identity store. This name is the name to be specified in the obj bind command in the -server option. (See the obj bind operation for details.)

address

is the real address of the Identity store in one of the following formats:

  • host[:port]

  • host1[:port1],host2[:port2][,…​]

where host or hostn is either an IP address or a DNS (domain name server) name and port or portn is a port number (<32767). 389 is used as the default port number.

If more than one real address is specified, an attempt is made to establish a connection using real addresses from left to right.

protocol

is the protocol to be used for the LDAP bind. Supply one of the following keywords (case-insensitive):

  • LDAPv2 - LDAP version 2

  • LDAPv3 - LDAP version 3

The protocol specification can be overridden by -protocol option in the obj bind command. (See the obj bind operation for details.)

The first Identity store address line identifies the default Identity store.

Anything following and separated from the protocol specification in a Identity store address line with a space is ignored.

If no Identity store address line is specified, the server address must be specified in the obj bind command in the -address option for an LDAP server. (See the obj bind operation for details.)

If LDAPv2 or LDAPv3 is specified in the -protocol option of an obj bind operation and no LDAP server address line is specified in the client configuration file dirxcl.cfg a bind to the local Identity store is established. (See the obj bind operation for details.)

If you use environment variables to override a dirxcl.cfg file entry and an error occurs (for example, if DIRX_CLCFG_FILE is set to a nonexistent file or is incorrectly specified), the meta controller reports the error, but makes no attempt to return to the overridden default. If errors occur, consult the exception log file for a description of the error.

Sample dirxcl.cfg File

# any line starting with '#' is a comment and is ignored
# any line starting with 'self' (case insignificant) contains
# the psap of the meta controller - there must be 1 such line
# further lines contain Identity store names and addresses;
# the first is the default
# the next line is the psap of the meta controller itself - can be first, # last or anywhere
Self TS=Client1,NA='TCP/IP!internet=139.23.81.32+port=2555'
# LDAPv3 Server
hawk hawk.virt.de.com LDAPv3
# LDAPv2 Server
eagle eagle.virt.de.com,hawk@virt.de.com LDAPv2

SSL/TLS Certificate Database

cert8.db

Purpose

The SSL/TLS certificate database, used by metacp, defines the server and certificate authority (CA) certificates that the meta controller is to trust when authenticating a server during a bind operation with SSL/TLS enabled.It also contains the client certificate that the meta controller is to use when authenticating clients during a bind operation with SASL EXTERNAL enabled.

Description

The default location for the cert8.db certificate database is:

install_path/client/conf

You can override the default location and file name by setting the DIRX_TRUSTED_CA environment variable to the full pathname of the file.

When an LDAP client connects to an LDAP server over SSL/TLS, the LDAP server authenticates itself by sending its certificate to the LDAP client. The LDAP client needs to determine whether the certificate authority (CA) that issued the certificate is trusted.

The LDAP client (metacp) uses the Mozilla SDK to implement SSL/TLS support. The security protocols and versions supported by the SDK are SSL V2 and SSL V3. The Identity store supports SSL V3 and TLS V1. Consequently, if metacp connects to an LDAPv3 server, the two programs will agree on SSL V3 during the negotiation of the security protocol to use.

The Mozilla SDK API requires a certificate database to hold the CA certificate. The prerequisites for connecting over SSL are as follows:

  1. The meta controller has access to a Mozilla certificate database. This database must be the cert8.db database file. Note that previous and later versions of these applications use different file formats for the certificate database. Attempting to use a different version of the certificate database will result in certificate database errors. The LDAP API function called by metacp uses this certificate database to determine if it can trust the certificate sent from the server.

  2. The certificate database that you are using can contain:

    • The certificate of the certificate authority (CA) that issued the LDAP server’s certificate

    • The certificates of all the CAs in the hierarchy, if the certificate authorities (CAs) are organized in a hierarchy

    • The certificate of the LDAP server

    • User certificates

  3. The CA certificate is marked as "trusted" in the certificate database.

When metacp sends an initial request to the secure LDAP server, the LDAP server sends its certificate back to metacp. metacp then determines which CA issued the LDAP server’s certificate and searches the certificate database (cert8.db) for the certificate of that CA.

If metacp cannot find a trusted certificate of the server or the issuer it refuses to connect to the server. It also refuses to connect if the LDAP server’s certificate has expired or if the certificate extension restricts the usage to client usage only. The latter applies if the LDAP server sends a browser certificate instead a server certificate.

The DirX Identity installation contains an example cert8.db file containing the CA certificate of the "Test CA" that issued all test keymaterial. It includes also the user certificate for cn=mayer,ou=sales,o=my-company for the purpose of testing SASL binds.

Certificate Administration

metacp clients use the Mozilla LDAP SDK to implement the LDAP stub and the SSL Security support.In order to manipulate the certificate databases read by metacp you need to use the utility program certutil provided as part of the SDK.

You may download the sources and binaries from the Mozilla web site

https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS

For a complete documentation on the certutil command line tool see

https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/tools/NSS_Tools_certutil

SSL/TLS Key Database

key3.db

Purpose

The key database, used by metacp when a SASL bind operation with the EXTERNAL mechanism is performed, contains the data required to access the private key that corresponds to the client certificate.

Description

The default location for the key3.db key database is:

install_path/client/conf

You can override the default location and file name by setting the DIRX_KEY3DB_FILE environment variable to the full pathname of the file.

When an LDAP client (in this case, metacp) binds to an LDAP server (in this case, the Identity store) using the ldap_sasl mechanism (see the obj bind operation for details), metacp accesses

  • the cert8.db certificate database in order to retrieve the client’s user certificate

  • the key3.db key database in order to retrieve the client’s private key.

Use the Mozilla command line tool certutil to add Client PSEs to the cert8.db database and to the key3.db key database files. Note: The newer certutil tool targets per default cert9.db and key4.db files.Use the option -d to work with cert8.db and key3.db files.See the given documentation link above.

The DirX Identity installation contains an example key3.db file containing a private key for testing purposes for the user with the nickname "mayer".It is protected with the passphrase "dirxdirx".See the description of the -sasl option of the metacp operation obj bind.

IDMS Configuration and Key Material Files

idmssl.cfg
own_keymaterial.pem
password_file.pwd
trustedCA.pem

Purpose

The encrypted IDM (IDMS) configuration file idmssl.cfg specifies the parameters for the SSL initialization that is needed to perform the X.500 protocols over IDMS, the encrypted variant of IDM.The *.pem and .pwd files contain the necessary key material.

Keep in mind that in DirX Identity installations, metacp normally uses LDAP protocol. The information about idmssl.cfg is only needed in the very rare case when a customer still runs workflows or any other Tcl scripts using DAP protocol (over IDMS rather than OSI). For more details (for example, on how to create the appropriate *.pem files), please refer to the DirX documentation.

Description

Each DirX process that uses IDMS has its own configuration file (idmssl.cfg) located in a specific configuration (/conf) folder:

  • For the DSA (dirxdsa process), the file is located in install_path/server/conf/idmssl.cfg. (This information is only given here for completeness.)

  • For the LDAP server (dirxldapv3 process), the file is located in install_path/ldap/conf/idmssl.cfg. (This information is only given here for completeness.)

  • For the DUA client metacp, the file is located in install_path/client/conf/idmssl.cfg (and its input should be derived from install_path/conf/idmssl.cfg.template).

If IDMS is enabled, the processes read the file at startup. To enable IDMS, the DirX process’s own PSAP address must contain a DNS component with an SSLPORT subcomponent value greater than 0. The DIRX_OWN_PSAP environment variable specifies the DSA process’s own PSAP address, whereas the LDAP server and the DUA client (metacp) get their own PSAP addresses from the SELF entry in the dirxldap.cfg or dirxcl.cfg configuration files.

The settings are used for the lifetime of the process; that is, a restart is required for changes to the configuration file to take effect.

The idmssl.cfg file contains the pathnames of the key material files used by the SSL/TLS library and configuration options for the security protocol, ciphers, wait time and logging level.

In the configuration file, comment lines begin with the hashtag character (#) in the first column and are ignored. The format of all other lines is:

keyword value

The following parameters (keyword) must be specified:

idm_ssl_own_pse_file

Specifies the fully-qualified name of the running process’s own PEM file. This PEM file must contain the following items:

  • The private key and the public key certificate representing the Personal Security Environment (PSE) of the running process.

  • The issuers' Certificate Authority (CA) certificates (chain of CA certificates of all intermediate CAs and the root CA).

The file must be accessible and readable for the started DirX process.

DirX Identity installs an example file IDMPSE.pem under install_path*/conf*. This file contains the demo PSE for /O=My-Company/OU=DirX-Example/OU=DirX8.2B/CN=dirxIDM issued by the testCA /O=My-Company/OU=DirX-Example/CN=test-CA. Note that these files match the content of the sample files provided by the DirX installation.

idm_ssl_pwd_file

Specifies the fully-qualified name of the file that contains the password for accessing the private key contained in the own PEM file. (See the idm_ssl_own_pse_file parameter for details.) The password must be the only content of this file. When creating the file, the password must be specified in plain ASCII format. When IDMS reads the password for the first time, it encrypts it and reuses the encrypted format in subsequent starts. (Similar to the handling of the LDAP server’s SSL password; see the description of the LDAP PKCS12 Password File attribute.) The file must be accessible and readable for the started process.

DirX Identity installs the file IDMPSE.pwd under install_path/conf. This file contains the clear text password dirxdirx, which is suitable for accessing the private key contained in the own PEM file. Note that these files match the content of the sample files provided by the Dir.X installation.

idm_ssl_trusted_ca_cert_file

Specifies the fully-qualified name of the PEM file of all trusted CAs. This PEM file contains the certificates of all CAs trusted to issue valid server certificates. In client mode, the certificate sent by the server is checked against the certificates contained in this file. The file must be accessible and readable for the started process.

DirX Identity installs an example file testCA.pem under install_path/conf. This file contains the CA certificate of the CA /O=My-Company/OU=DirX-Example/CN=test-CA as the trusted CA.

idm_ssl_protocol

Specifies the SSL protocol that IDM accepts for incoming and outgoing connections. The value must be one of SSLv3, TLSv1, TLSv11, TLSv12 or ALL (for all protocols). Both sides must accept the same protocol to establish an SSL connection. SSLv2 is considered to be unsafe and is therefore not supported.

idm_ssl_ciphers

Specifies the list of ciphers accepted for encryption. IDMS accepts all cipher names and shortcuts that OpenSSL supports.

To get a list of cipher names, see the OpenSSL documentation or start an OpenSSL-shell and perform a ciphers command to get a list of cipher names or cipher groups. In the following example, the list of RSA ciphers names and groups are read:

OpenSSL> ciphers RSA

The command output is as follows:

AES256-GCM-SHA384:AES256-SHA256:AES256-SHA:CAMELLIA256-SHA:DES-CBC3-SHA:DES-CBC3-MD5:AES128-GCM-SHA256:AES128-SHA256:AES128-SHA:SEED-SHA:CAMELLIA128-SHA:IDEA-CBC-SHA:IDEA-CBC-MD5:RC2-CBC-MD5:RC4-SHA:RC4-MD5:RC4-MD5:DES-CBC-SHA:DES-CBC-MD5:EXP-DES-CBC-SHA:EXP-RC2-CBC-MD5:EXP-RC2-CBC-MD5:EXP-RC4-MD5:EXP-RC4-MD5:NULL-SHA256:NULL-SHA:NULL-MD5

The cipher names can also be meta-names like RSA, MEDIUM or HIGH as supported by OpenSSL.

idm_ssl_io_timeout

Specifies the maximum time in seconds that IDMS is to wait while performing SSL_accept() to complete the initial SSL handshake. If this time period expires, the handshake is aborted and the TCP connection is disconnected.

If IDMS acts as a server (the DSA process), the initial SSL handshake requires both sides to exchange some messages (read/write) in order to establish an SSL connection. If the client does not send data within idm_ssl_io_timeout seconds, IDM will abort further data exchange and assume that the connection is broken.

While waiting for data, the corresponding IDM worker thread is blocked and does not service other requests. As a result, it is recommended not to configure this parameter in minutes or hours.

As IDMS is currently only used between DirX components that can be assumed to behave in a friendly manner, a timeout may indicate serious network problems or a third-party attack.

idm_ssl_logging

Specifies whether or IDM generates SSL logging. Use this option only for debugging. Specify one of the following values:

  • 0—Logging is turned off.

  • 1—Logging of SSL function calls (level low).

  • 2—Logging of SSL function calls and select and poll events (level medium).

  • 3—Logging of SSL function calls, select and poll events, and input / output data (level high).

If SSL logging is enabled, a log file is generated under install_path*/tmp*. The name of the log file is idmssl*pid**_id.txt*, where pid is the process identifier of the running process and id is either d (DSA), l (LDAP server, lower case l) or c (metacp).

Keep in mind that changing the logging status requires a restart of the process. A logging file grows endlessly. You can use logging, for example, to track down IDM SSL connection problems.

Although individual configuration is possible, the default IDMS configuration file that is installed with DirX provides the configuration settings shown below for all DirX processes using IDMS. All entities use the same key material: ($DIR identifies the DirX Identity installation directory).

#########################################
# 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 $DIR/conf/IdmPSE.pem
# the pathname of the password file for accessing the private key
idm_ssl_pwd_file $DIR/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 $DIR/conf/testCA.pem
# the security protocol to be used - one of: SSLv3, TLSv1, TLSv11, TLSv12
idm_ssl_protocol TLSv12
# the ciphers to use (names must be compatible with OpenSSL naming schema)
idm_ssl_ciphers RSA
# 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
#########################################