Configuring the LDAP plug-in modules

To configure the LDAP plug-in modules, you need to update your IBM® LDAP security plug-in configuration file to suit your environment. In most cases, you will need to consult with your LDAP administrator to determine the appropriate configuration values.

Warning:

In response to CVE-2023-32342, Db2 releases with KI DT223175 will use the non-FIPS IBM Crypto for C (ICC) for TLS ciphers that use RSA key exchange, as the FIPS certified IBM Crypto for C (ICC) is vulnerable to CVE-2023-32342. Customers with a requirement to use only FIPS 140 certified cryptographic modules must enable Strict FIPS mode.

In strict FIPS mode, Db2 releases with KI DT223175 will disable all TLS ciphers and versions that are vulnerable to CVE-2023-32342. Note: RSA certificates are not affected by CVE-2023-32342, and do not need to be changed.

Strict FIPS mode can be enabled for the LDAP plugins by setting the FIPS_MODE keyword to STRICT. When in strict FIPS mode, and the Db2 release contains KI DT223175, the LDAP plugins will use TLS 1.2 regardless of the SECURITY_PROTOCOL setting.

Additionally, ciphers that use RSA key exchange (TLS_RSA_) will be disabled, and the list of available ciphers will be restricted to those that use ECDHE key exchange (TLS_ECDHE_RSA_ and TLS_ECDHE_ECDSA_*).

For LDAP servers using RSA certificates, Db2 will automatically prefer TLS_ECDHE_RSA ciphers for TLS 1.2 and no certificate change is required.

Customers using an IBM LDAP sever such as IBM Security Verify Directory 10.0, IBM Security Directory Suite 8.0, or IBM Security Directory Server 6.4 must explicitly enableTLS_ECDHE_RSA_WITH_AES_* ciphers if using an RSA certificate, or TLS_ECDHE_ECDSA_WITH_AES_* ciphers if using an ECDSA certificate before upgrading Db2 to a release with a fix for CVE-2023-32342.

TLS 1.2 cipher settings can be found in the web administration tool under Server Administration > Manage Security Properties > Encryption.

Important: Use of versions 1.0 and 1.1 of the Transport Layer Security (TLS) protocol is deprecated. We recommend to use TLS version 1.2.

Note: If enabling this feature on AIX, review the following for performance considerations.

The default name and location for the IBM LDAP security plug-in configuration file is:

On UNIX: INSTHOME/sqllib/cfg/IBMLDAPSecurity.ini
On Windows: %DB2PATH%\cfg\IBMLDAPSecurity.ini

Optionally, you can specify the location of this file using the DB2LDAPSecurityConfig environment variable. On Windows, you should set DB2LDAPSecurityConfig in the global system environment, to ensure it is picked up by the Db2® service.

The following tables provide information to help you determine appropriate configuration values.

Table 1. Server-related values
Parameter	Description
LDAP_HOST	The name of your LDAP server(s). This is a space separated list of LDAP server host names or IP addresses, with an optional port number for each one. For example: `host1[:port] [host2:[port2] ... ]` The default port number is 389, or 636 if TLS is enabled.
ENABLE_SSL	To enable TLS support, set ENABLE_SSL to TRUE. This is an optional parameter; it defaults to FALSE (no TLS support).
SSL_KEYFILE	The path for the TLS keyring. A keyfile is only required if your LDAP server is using a certificate that is not automatically trusted by your IBM Global Security Kit (GSKit) installation. For example:`SSL_KEYFILE = /home/db2inst1/IBMLDAPSecurity.kdb`
SSL_PW	The TLS keyring password. For example: `SSL_PW = keyfile-password`
SECURITY_PROTOCOL	By default, SECURITY_PROTOCOL is not set. In Db2 11.5.9, this means TLS 1.2 is the only supported TLS version. In Db2 versions prior to 11.5.9, this means that TLS 1.0 and 1.1 are supported, and TLS 1.2 is not supported. To enable TLS 1.2 support in Db2 versions prior to 11.5.9, set SECURITY_PROTOCOL to TLSV12. To enable TLS 1.0, 1.1, and 1.2 support, set SECURITY_PROTOCOL to ALL.
SSL_EXTN_SIGALG	SSL_EXTN_SIGALG specifies a list of signature algorithms that will be supported for a TLS secured LDAP connection. When using TLS 1.2, a value for SSL_EXTN_SIGALG should be specified, otherwise the server may assume only RSA+SHA1 is supported. This is a problem with some LDAP servers because they require that all certificates be signed with SHA2 or better. SSL_EXTN_SIGALG can be set to one of the following values (multiple values can be specified, separated by commas): GSK_TLS_SIGALG_RSA_WITH_SHA224 GSK_TLS_SIGALG_RSA_WITH_SHA256 GSK_TLS_SIGALG_RSA_WITH_SHA384 GSK_TLS_SIGALG_RSA_WITH_SHA512 GSK_TLS_SIGALG_ECDSA_WITH_SHA224 GSK_TLS_SIGALG_ECDSA_WITH_SHA256 GSK_TLS_SIGALG_ECDSA_WITH_SHA384 GSK_TLS_SIGALG_ECDSA_WITH_SHA512
SASL_BIND	The SASL_BIND keyword is available starting in version 11.5.6. When SASL_BIND is set to true in the IBMLDAPSecurity.ini file, the LDAP plugin will add a `PasswordPolicyRequest` control when authenticating users. This indicates to the LDAP server that the LDAP plugin is requesting data about the state of a user's password, and that the server should respond with a `passwordPolicyResponse`. If a `passwordPolicyResponse` control is included in the response from the LDAP server, the LDAP plugin will examine the `passwordPolicyResponse` to determine the status of the user's password. If the `passwordPolicyResponse` indicates that the user's password is expired, or must change before the next logon, authentication will be denied.
FIPS_MODE	Note: The STRICT value for the FIPS_MODE keyword is available starting with KI DT223175. To enforce the use of FIPS 140 certified cryptographic modules for TLS support, in releases with KI DT223175 set FIPS_MODE to STRICT. In Db2 releases without KI DT223175, set FIPS_MODE to TRUE. To prefer the use of FIPS 140 certified cryptographic modules, but allow Db2 to use the uncertified module if an algorithm implementation is unavailable or has an identified vulnerability in the certified module, set FIPS_MODE to TRUE. This functionality available in releases that contain KI DT223175. To enforce the use of the uncertified cryptographic modules, set FIPS_MODE to FALSE. By default, FIPS_MODE is set to TRUE (Db2 will prefer the use of FIPS 140 certified modules, with the option for uncertified modules for algorithms not available in the certified modules). Note: In releases without KI DT223175, Db2 will enforce the use of FIPS 140 certified modules by default.

Table 2. User-related values
Parameter	Description
USER_ OBJECTCLASS	The LDAP object class used for users. Generally, set USER_OBJECTCLASS to `inetOrgPerson` (the user for Microsoft Active Directory) For example: `USER_OBJECTCLASS = inetOrgPerson`
USER_BASEDN	The LDAP base DN to use when searching for users. If not specified, user searches start at the root of the LDAP directory. Some LDAP servers require that you specify a value for this parameter. For example: `USER_BASEDN = o=ibm`
USERID_ ATTRIBUTE	The LDAP user attribute that represents the user ID. The USERID_ATTRIBUTE attribute is combined with the USER_OBJECTCLASS and USER_BASEDN (if specified) to construct an LDAP search filter when a user issues a Db2 CONNECT statement with an unqualified user ID. For example, if `USERID_ATTRIBUTE = uid`, then issuing this statement: `db2 connect to MYDB user bob using bobpass` results in the following search filter: `&(objectClass=inetOrgPerson)(uid=bob)`
AUTHID_ ATTRIBUTE	The LDAP user attribute that represents the Db2 authorization ID. Usually this is the same as the USERID_ATTRIBUTE. For example: `AUTHID_ATTRIBUTE = uid`

Table 3. Group-related values
Parameter	Description
GROUP_ OBJECTCLASS	The LDAP object class used for groups. Generally this is `groupOfNames` or `groupOfUniqueNames` (for Microsoft Active Directory, it is `group`) For example: `GROUP_OBJECTCLASS = groupOfNames`
GROUP_BASEDN	The LDAP base DN to use when searching for groups If not specified, group searches start at the root of the LDAP directory. Some LDAP servers require that you specify a value for this parameter. For example: `GROUP_BASEDN = o=ibm`
GROUPNAME_ ATTRIBUTE	The LDAP group attribute that represents the name of the group. For example: `GROUPNAME_ATTRIBUTE = cn`
GROUP_LOOKUP_ METHOD	Determines the method used to find the group memberships for a user. Possible values are: SEARCH_BY_DN Indicates to search for groups that list the user as a member. Membership is indicated by the group attribute defined as GROUP_LOOKUP_ATTRIBUTE (typically, `member` or `uniqueMember`). USER_ATTRIBUTE In this case, a user's groups are listed as attributes of the user object itself. This setting indicates to search for the user attribute defined as GROUP_LOOKUP_ATTRIBUTE to get the user's groups (typically `memberOf` for Microsoft Active Directory or `ibm-allGroups` for IBM Tivoli® Directory Server). For example:`GROUP_LOOKUP_METHOD = SEARCH_BY_DN` `GROUP_LOOKUP_METHOD = USER_ATTRIBUTE`
GROUP_LOOKUP_ ATTRIBUTE	Name of the attribute used to determine group membership, as described for GROUP_LOOKUP_METHOD. For example: `GROUP_LOOKUP_ATTRIBUTE = member` `GROUP_LOOKUP_ATTRIBUTE = ibm-allGroups`
NESTED_GROUPS	If NESTED_GROUPS is TRUE, the Db2 database manager recursively searches for group membership by attempting to look up the group memberships for every group that is found. Cycles (such as A belongs to B, and B belongs to A) are handled correctly. This parameter is optional, and defaults to FALSE.

Table 4. Miscellaneous values
Parameter	Description
SEARCH_DN, SEARCH_PW	If your LDAP server does not support anonymous access, or if anonymous access is not sufficient when searching for users or groups, then you can optionally define a DN and password that will be used to perform searches. For example: `SEARCH_DN = cn=root` `SEARCH_PW = rootpassword`
DEBUG	Set DEBUG to TRUE to write extra information to the db2diag log files to aid in debugging LDAP related issues. Most of the additional information is logged at DIAGLEVEL 4 (INFO). DEBUG defaults to false.