IBM Support

Configure PBKDF2 password encryption mechanism with Security Directory Server

How To


Summary

This document provides required details for the configuration of PBKDF2 password encryption mechanism with Security Directory Server (SDS) 6.4. This feature is first introduced in the fix level of SDS 6.4.0.16.

Environment

Prerequisites :

  1. Install or Upgrade to SDS 6.4.0.16 or later fix levels. - Available on Fix Central.
  2. Install or Upgrade to GSKit 8.0.50.88 or later - With SDS 6.4.0.16, GSKit verion 8.0.50.89 is provided on Fix Central.
  3. Also refer and install latest recommended fix levels of SDS and GSKit.

Refrence : Install/Update instructions
 

Notes:

  1. If GSKit version is older than 8.0.50.88, then, a message is printed in traceibmslapd.log file that, Upgrade GSKit version to 8.0.50.88 or later to use any of PBKDF2 encryption mechanism.
  2. If ibm-slapdPwEncryption is set to PBKDF2 algorithm, and GSKit version is older than, 8.0.50.88, then, server will start in configuration only mode with ERROR message in ibmslapd.log and on console that, upgrade GSKit to 8.0.50.88 or later to set PBKDF2 algorithm for ibm-slapdPwEncryption.

Steps

  1. Create and configure a directory server instance. More Info
  2. Stop directory server(ibmslapd) and admin server(ibmdiradm) processes.
  3. Enable the PBKDF2 encryption option in IBM Security Directory Server (SDS) instance via the following configuration attributes in "cn=Configuration" entry:
    ibm-slapdPwEncryption: <Digest_Type>>
    ibm-slapdUseNonFIPSCrypt: TRUE
  4. The ‘< Digest_Type>’ can have one of the following values:
    • pbkdf2-sha1
    • pbkdf2-sha224
    • pbkdf2-sha256
    • pbkdf2-sha384
    • pbkdf2-sha512
  5. These options are part of the server’s configuration backend and hence resides in the ibmslapd.conf file of the respective server instance.

  6. The Directory Administrator can set these values by directly editing the ibmslapd.conf file (when the ibmslapd/ibmdiradm processes are stopped), or by using the standard ldap modify operation as shown below:-
    /opt/ibm/ldap/V6.4/bin/idsldapmodify -h <hostname> -p <port> -D <adminDN> -w <admin_password> -i confupdate.ldif
          where contents of the confupdate.ldif are as below:
    dn: cn=Configuration
    changetype: modify
    replace: ibm-slapdPwEncryption
    ibm-slapdPwEncryption: PBKDF2-SHA256
    -
    replace: ibm-slapdUseNonFIPSCrypt
    ibm-slapdUseNonFIPSCrypt: TRUE

    Note:
    In case, ibm-slapdUseNonFIPSCrypt is missing(default) or not set to TRUE and ibm-slapdPwEncryption is set to any of PBKDF2 algorithm, then, server will start in configuration only mode with below ERROR message on console and in ibmslapd.log file:
    ERROR: Set ibm-slapdUseNonFIPSCrypt to TRUE in cn=Configuration entry to set any of PBKDF2 password encryption algorithm for ibm-slapdPwEncryption.

  7. Following new environment variable is supported to alter the number of iterations with PBKDF2 algorithms. This variable can be set in "cn=Front End, cn=Configuration" entry of ibmslapd.conf.
    ibm-slapdPBKDFNumIterations
        Default number of iterations is 10000.

    Note: When you use the ibm-slapdPBKDFNumIterations environment variable from the command line, enter in uppercase characters only. For example:
    env ‘IBM-SLAPDPBKDFNUMITERATIONS=25000’

    To set ibm-slapdPBKDFNumIterations in cn=Front End, cn=Configuration entry of ibmslapd.conf file with ibm-slapdSetenv attribute. The Directory Administrator can set this value by using the standard ldap modify operation as shown below:
    /opt/ibm/ldap/V6.4/bin/idsldapmodify -h <hostname> -p <port> -D <adminDN> -w <admin_password> -i confupdate2.ldif
       where contents of the confupdate2.ldif are as below:
    dn: cn=Front End, cn=Configuration
    changetype: modify
    add: ibm-slapdSetEnv
    ibm-slapdSetEnv: ibm-slapdPBKDFNumIterations=20000

    Minimum allowed value for ibm-slapdPBKDFNumIterations is 1000 and Maximum allowed value for ibm-slapdPBKDFNumIterations is 10000000.
    Server sets default value of 10000, if provided value is invalid or is not in allowed limit. Server will print a WARNING message on console and in ibmslapd.log file about usage of default value.
    The server must be restarted after this operation for the new values of ibm-slapdPwEncryption, ibm-slapdUseNonFIPSCrypt and ibm-slapdPBKDFNumIterations to take effect.
  8. Start directory server and admin server.

Additional Information

Notes:

  1. Only ibm-slapdPwEncryption attribute can be dynamically updated with idsldapexop operation, other attributes ibm-slapdUseNonFIPSCrypt and environment variable ibm-slapdPBKDFNumIterations require server restart when their values are updated. Only positive values must be given for environment variable ibm-slapdPBKDFNumIterations. Minimum allowed value for ibm-slapdPBKDFNumIterations is 1000 and Maximum allowed value for ibm-slapdPBKDFNumIterations is 10000000.
     
  2. How and when passwords gets updated to use newly configured PBKDF2 method ?
    When an instance gets configured with PBKDF2 algorithm, all the existing users will continue to have existing encrypted passwords without any change. In other words, configuration change will not update all users to update the userpassword with newly configured encryption methods. As users keep changing their passwords the userpassword's encrypted gets updated. If there is a need to update all of the user's passwords to use PBKDF2, administrator need to take actions to ask users to update their passwords or administratively reset the passwords.
     
  3. The following table displays random generated salt length for each of the supported PBKDF2 encryption methods, (the random salt gets generated when a password update takes place):
    Encryption Method Salt Length (Bytes)
    PBKDF2-SHA1 20
    PBKDF2-SHA224 28
    PBKDF2-SHA256 32
    PBKDF2-SHA384 48
    PBKDF2-SHA512 64
  4. Guidelines to set iterations based on operationResponseTime for Bind, higher the iterations count, the longer time is taken for the bind operations, based on your system specifications the operationRespnoseTime may differ. The table below is included to give an idea on how the iterations count will affect the bind performance:
    Encryption Method Iterations operationResponseTime for Bind from Audit.log (milliseconds)
    PBKDF2-SHA512 1000 50
    PBKDF2-SHA512 10000 78
    PBKDF2-SHA512 100000 212
    PBKDF2-SHA512 1000000 1542
    PBKDF2-SHA512 10000000 14358


Known Issues

  1. Replication and Distributed Directory (Proxy ldap server) Support: When PBKDF2 is desired to be used in a replicated or distributed directory environment, all the servers MUST be updated to use same configuration as described in "steps to configure" section above by setting ibm-slapdPwEncryption to one of PBKDF2 algorithm and ibm-slapdUseNonFIPSCrypt to TRUE in cn=Configuration entry of ibmslapd.conf file. Failing to update the configuration would result in unstable passwords across different ldap servers in topology.
    1. Following replication topologies are not supported with PBKDF2:
      • Master - Forwarder - Replica
      • Gateway to Gateway
    2. Supported replication topologies for PBKDF2 are:
      • Master - Replica
      • Peer to Peer
  2. Passwords with special characters must be passed as parameters with single quotes around it. For example, 
    idsldapsearch -p 389 -D cn=user1,o=sample -w 'Passw0Rd$678' -b o=sample -s sub objectclass=*
    This is applicable to all supported older algorithms too.
  3. Changing the encryption method from PBKDF2-SHA* to aes256 : If ibm-slapdUseNonFIPSCrypt is set to false or removed altogether from the ibmslapd.conf file, then the bind with valid credentials for an existing user whose password is still encrypted using PBKDF2* methods will fail.
  4. Migration from SDS 6.4 to IBM Security Directory Suite Virtual Appliance 8.0.1:
    Migration from SDS 6.4 to ISDS VA 8.0.1 with PBKDF2 encryption mechanism set in configuration file is not supported. Server may not start or migration might not work at all. idsimigr command might fail.
  5. Web Admin Tool support:
    Configuring PBKDF2 password encryption mechanism is not supported through Web Admin Tool. Command idsldapmodify can be used to configure PBKDF2 password encryption mechanism.
  6. Attribute encryption support:
    Attribute encryption is not supported with PBKDF2 encryption mechanism. PBKDF2 mechanism is supported only for password encryption.

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSVJJU","label":"IBM Security Directory Server"},"Component":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"6.4","Edition":"","Line of Business":{"code":"LOB24","label":"Security Software"}}]

Document Information

Modified date:
20 December 2020

UID

ibm10718779

Page Feedback