Configuring for encryption or hashing

The LDAP server allows the userPassword, secretKey, replicaCredentials, ibm-replicaKeyPwd, ibm-slapdAdminPw, and ibm-slapdMasterPw attribute values to be encrypted or hashed when stored in the directory. This prevents clear data from being accessed by users, including the system administrators. An administrator may configure the server to encrypt or hash userPassword or ibm-slapdAdminPw attribute values in either a one-way hashing format or a two-way symmetric encryption format. secretKey, replicaCredentials, ibm-replicaKeyPwd, and ibm-slapdMasterPw attribute values can only be encrypted in a two-way symmetric encryption format. Besides encryption or hashing, access to data stored in the directory can be protected by the directory access control mechanism.

One-way hashing formats

The one-way hashing algorithms supported by the LDAP server are crypt, MD5, SHA, Salted SHA (SSHA), SHA-2 and Salted SHA-2. The SHA-2 and Salted SHA-2 hashing algorithms consists of the following methods: SHA224, SSHA224 (Salted SHA224), SHA256, SSHA256 (Salted SHA256), SHA384, SSHA384 (Salted SHA384), SHA512, and SSHA512 (Salted SHA512). If the LDAP server is configured to use any SHA-2 or Salted SHA-2 hashing method, the server compatibility must be 7 or greater and ICSF must be installed because the LDAP server uses the ICSF PKCS #11 omnipresent token to perform the SHA-2 and Salted SHA-2 hashing. See z/OS Cryptographic Services ICSF Overview for more information about ICSF. The user ID that runs the LDAP server must have READ access to the CSFPOWH profile in the CSFSERV class to perform the SHA-2 or Salted SHA-2 hashing. See Additional setup for using SHA-2 or Salted SHA-2 hashing for more information.

During a simple bind, the bind password is hashed using the appropriate algorithm and compared with the stored hashed userPassword or ibm-slapdAdminPw attribute value. Assuming that a client is authorized using directory access controls to see the userPassword or ibm-slapdAdminPw attribute values on a search, the values are returned to the client in one of the following manners:

If the pwSearchOutput configuration option is set to binary and the userPassword or ibm-slapdAdminPw attribute value is hashed in MD5 or SHA, the LDAP server returns the encryption tag (either {MD5} or {SHA}) in UTF-8 followed by the binary hash.
If the pwSearchOutput configuration option is set to base64 and the userPassword or ibm-slapdAdminPw attribute value is hashed in MD5 or SHA, the LDAP server returns the encryption tag (either {MD5} or {SHA}) in UTF-8 followed by the base64-encoded binary hash.
If the userPassword or ibm-slapdAdminPw attribute value is hashed in crypt, the LDAP server returns the encryption tag ({crypt}) in UTF-8 followed by the binary hash and sent over the wire in UTF-8. The pwSearchOutput configuration option has no bearing on the retrieval of crypt hashed password values.
If the userPassword or ibm-slapdAdminPw attribute value is hashed in SHA-2 (SHA224, SHA256, SHA384, or SHA512), the LDAP server returns the encryption tag (for example, {SHA224}) in UTF-8 followed by the base64-encoded binary hash. The pwSearchOutput configuration option has no bearing on the retrieval of SHA-2 hashed password values.
If the userPassword or ibm-slapdAdminPw attribute value is hashed in Salted SHA (SSHA) or Salted SHA-2 (SSHA224, SSHA256, SSHA384, or SSHA512), the LDAP server returns the encryption tag (for example, {SSHA}) in UTF-8 followed by the base64-encoded binary hash and salt value. The pwSearchOutput configuration option has no bearing on the retrieval of Salted SHA (SSHA) or Salted SHA-2 hashed password values.

The following are examples of retrieving the same SHA hashed userPasword attribute value, using the ldapsearch client utility with the -L option specified. For additional information about the ldapsearch client utility, see z/OS IBM Tivoli Directory Server Client Programming for z/OS.

When the pwSearchOutput configuration option is set to binary, the SHA hashed userPassword value is displayed by ldapsearch as follows:

userpassword:: e1NIQX2pmT42RwaBaro+JXF4UMJsnNDYnQ==

The userPassword attribute value that is returned above contains both the UTF-8 encryption tag, {SHA}, and the binary hashed data, but they have been base64-encoded by the ldapsearch client utility to present the value in a printable format.

When the pwSearchOutput configuration option is set to base64, the SHA hashed userPassword value is displayed by ldapsearch as follows:

userpassword: {SHA}qZk+NkcGgWq6PiVxeFDCbJzQ2J0=

The userPassword attribute value that is returned above is displayed as sent to the ldapsearch client utility because the hashed binary data after the {SHA} encryption tag has already been base64-encoded by the LDAP server.

For applications requiring retrieval of clear text passwords or data, such as middle-tier authentication agents, the directory administrator must configure the LDAP server to perform either a two-way encryption or no encryption of user passwords or data.

Two-way encryption formats

The supported two-way encryption formats include DES and AES. Two-way encryption allows the values of the userPassword, secretKey, replicaCredentials, ibm-replicaKeyPwd, ibm-slapdAdminPw, or ibm-slapdMasterPw attributes to be retrieved as part of an entry in the original clear format. Some applications, such as middle-tier authentication servers, require passwords to be retrieved in clear text while installation security policies might prohibit storing clear passwords in secondary permanent storage. This option satisfies both requirements. An encrypted password can be used for password matching on a simple bind and can be decrypted for return as clear text on a search request. During simple bind, the stored encrypted userPassword or ibm-slapdAdminPw attribute values are decrypted and compared with the bind password. During a search, if the client is authorized using directory access controls to see the userPassword, secretKey, replicaCredentials, ibm-replicaKeyPwd, ibm-slapdAdminPw, or ibm-slapdMasterPw attribute values, then they are decrypted and returned as clear text.

Symmetric encryption keys

The DES and AES encryption format use symmetric encryption keys. DES uses 56-bit (single length), 112-bit (double length), or 168-bit (triple length) keys while AES uses 128-bit, 192-bit, or 256-bit keys. DES or AES keys are stored in the ICSF CKDS or in a sequential or partitioned data set referenced by the LDAPKEYS DD statement. For AES keys, the LDAPKEYS data set only allows 256-bit keys.

The ICSF KGUP utility is used to store an AES or DES key in the CKDS. See the Key Generator Utility Program in z/OS Cryptographic Services ICSF Administrator's Guide for instructions on how to generate and store a key in the CKDS.

The AES and DES keys supported by the LDAP server depends on the underlying hardware and ICSF support. AES and DES keys can be stored in the clear or encrypted in the CKDS. See z/OS Cryptographic Services ICSF Overview for more information about the AES and DES keys that are supported for your hardware and ICSF level.

DES and AES keys can be stored in a sequential or partitioned data set referenced by the LDAPKEYS DD statement. The LDAPKEYS data set should be used with caution as all AES and DES keys are stored in the clear. The data set consists of fixed-length or variable-length records with a maximum record length of 255. The records are assumed to be in the IBM-1047 code page. Comment records begin with ’#’ or ’*’ and blank records are ignored. Each record in the data set defines a single key and has the following format:

key-label key-part-1 key-part-2 key-part-3 key-part-4

The fields are separated by one or more blanks. Each key part consists of 16 hexadecimal characters representing 8 bytes of the key. A DES key requires the key label and the one, two or three key parts while an AES key requires the key label and all four key parts. In a DES key, the low-order bit in each byte is a parity bit. The parity bit must be set so that there is an odd number of 1s in each byte, but the bit is not used for encryption. Therefore, DES uses 56-bits out of each 8-byte key part for encryption. An AES key does not use parity bits, therefore, the entire key (256 bits) is used for encryption.

The LDAP server checks the LDAPKEYS data set first when looking for a key label. If the key label is not found, then the LDAP server attempts to locate an AES or DES key in the ICSF CKDS.