IDM 7.3.0

Encode attribute values

There are two ways to encode attribute values for managed objects—reversible encryption and salted hashing algorithms. Attribute values that might be encoded include passwords, authentication questions, credit card numbers, and social security numbers. If passwords are already encoded on the external resource, they are generally excluded from the synchronization process. For more information, refer to Passwords.

You configure attribute value encoding, per schema property, in the managed object configuration. The following sections show how to use reversible encryption and salted hash algorithms to encode attribute values.

Reversible encryption

The following managed object configuration encrypts and decrypts the password attribute using the default symmetric key:

{
    "objects" : [
        {
            "name" : "user",
            ...
            "schema" : {
                ...
                "properties" : {
                    ...
                    "password" : {
                        "title" : "Password",
                        ...
                        "encryption" : {
                            "purpose" : "idm.password.encryption"
                        },
                        "scope" : "private",
                    }
            ...
        }
    ]
}

The settings for reversible encryption depend on the encryption capabilities of the underlying JVM. refer to the explanations in javax.crypto.Cipher. You can accept the default settings, or specify the cipher and the keySize, for example:

...
    "encryption" : {
        "purpose": "idm.password.encryption",
        "cipher": "AES/GCM/NoPadding",
        "keySize": 128
},

The syntax for the cipher is algorithm/mode/padding, for example, "cipher" : "AES/CBC/PKCS5Padding":

  • The cipher algorithm defines how the plaintext is encrypted and decrypted.

    The default algorithm is the Advanced Encryption Standard (AES).

  • The cipher mode defines how a block cipher algorithm transforms data larger than a single block.

    The default cipher mode is cipher block chaining (CBC).

  • The cipher padding defines how to pad the plaintext to reach the appropriate size for the algorithm.

    The default cipher padding is PKCS#5 padding.

  • The cipher key size determines the encryption strength, where longer key lengths strengthen encryption at the cost of lower performance.

    The default keySize is 16.

If you change the default cipher, you must specify the algorithm, mode, and padding. If the algorithm does not require a mode, use NONE. If the algorithm does not require padding, use NoPadding.

To encrypt attribute values from the command-line, refer to encrypt.

Configure encryption using the admin UI

  1. Select Configure > Managed Objects, and select the object type whose property values you want to encrypt (for example, User).

  2. On the Properties tab, select the property whose value should be encrypted and select the Encrypt checkbox.

Salted hash algorithms

To encode attribute values with salted hash algorithms, add the secureHash property to the attribute definition and define the hashing configuration. The configuration depends on the algorithm that you choose.

If you do not specify an algorithm, SHA-256 is used by default. MD5 and SHA-1 are supported for legacy reasons, but should not be used in production environments.

Supported Hashing Algorithms and Configuration Properties
Algorithm Config Property and Description

BCRYPT

cost

Value between 4 and 31. Default is 13.

PBKDF2

hashLength

Byte-length of the generated hash. Default is 16.

saltLength

Byte-length of the salt value. Default is 16.

iterations

Number of cryptographic iterations. Default is 20000.

hmac

HMAC algorithm. Default is SHA3-256.

Supported values:

  • SHA-224

  • SHA-256

  • SHA-384

  • SHA-512

  • SHA3-224

  • SHA3-256

  • SHA3-384

  • SHA3-512

SCRYPT

hashLength

Byte-length of the generated hash, must be greater than or equal to 8. Default is 16.

saltLength

Byte-length of the salt value. Default is 16.

n

CPU/Memory cost. Must be greater than 1, a power of 2, and less than 2^(128 * r / 8). Default is 32768.

p

Parallelization. Must be a positive integer less than or equal to Integer.MAX_VALUE / (128 * r * 8). Default is 1.

r

Block size. Must be greater than or equal to 1. Default is 8.

SHA-256

saltLength

Byte-length of the salt value. Default is 16.

This is the default hashing.

SHA-384

saltLength

Byte-length of the salt value. Default is 16.

SHA-512

saltLength

Byte-length of the salt value. Default is 16.

The following list displays supported hash algorithms and example configurations:

SHA-256
"secureHash" : {
    "algorithm" : "SHA-256",
    "saltLength" : 16
}
SHA-384
"secureHash" : {
    "algorithm" : "SHA-384",
    "saltLength" : 16
}
SHA-512
"secureHash" : {
    "algorithm" : "SHA-512",
    "saltLength" : 16
}
Bcrypt
"secureHash" : {
    "algorithm" : "BCRYPT",
    "cost" : 16
}
Scrypt
"secureHash" : {
    "algorithm" : "SCRYPT",
    "hashLength" : 16,
    "saltLength" : 16,
    "n" : 32768,
    "r" : 8,
    "p" : 1
}
Password-Based Key Derivation Function 2 (PBKDF2)
"secureHash" : {
    "algorithm" : "PBKDF2",
    "hashLength" : 16,
    "saltLength" : 16,
    "iterations" : 10,
    "hmac" : "SHA-256"
}

Some one-way hash functions are designed to be computationally expensive. Functions such as PBKDF2, Bcrypt, and Scrypt are designed to be relatively slow even on modern hardware. This makes them generally less susceptible to brute force attacks. However, computationally expensive functions can dramatically increase response times. If you use these functions, be aware of the performance impact and perform extensive testing before deploying your service in production. Do not use functions like PBKDF2 and Bcrypt for any accounts that are used for frequent, short-lived connections.

Hashing is a one-way operation, such that the original value cannot be recovered. Therefore, if you hash the value of any property, you cannot synchronize that property value to an external resource. For managed object properties with hashed values, you must either exclude those properties from the mapping or set a random default value if the external resource requires the property.

The following excerpt of a managed object configuration shows that values of the password attribute are hashed using the SHA-256 algorithm:

{
    "objects" : [
        {
            "name" : "user",
            ...
            "schema" : {
                ...
                "properties" : {
                    ...
                    "password" : {
                        "title" : "Password",
                        ...
                        "secureHash" : {
                            "algorithm" : "SHA-256"
                        },
                        "scope" : "private",
                    }
            ...
        }
    ]
}

To hash attribute values from the command-line, refer to secureHash.

Configure hashing using the admin UI

You can set a property hash algorithm using the admin UI. However, only some algorithms and none of the enhanced configuration options are supported.

Show Me
Admin UI hash property
  1. Select Configure > Managed Objects, and select an object type (for example, User).

  2. On the Properties tab, select a property to hash.

  3. On the Property Name page, click the Privacy & Encryption tab, and select Hashed.

  4. From the adjacent drop-down menu, select an algorithm.

  5. Click Save.

Copyright © 2010-2023 ForgeRock, all rights reserved.