--- title: Secure sensitive values description: There are two ways to encode attribute values for managed objects—reversible encryption and salted hashing algorithms. Examples of encoded attribute values 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 Manage password policies. component: pingidm version: 8.1 page_id: pingidm:security-guide:encoding-attribute-values canonical_url: https://docs.pingidentity.com/pingidm/8.1/security-guide/encoding-attribute-values.html keywords: ["Security", "Password", "Encryption", "Salted Hash", "Algorithms", "HMAC", "SHA-256", "SHA-384", "SHA-512"] section_ids: encoding-encryption: Reversible encryption encrypt-ui: Configure encryption using the admin UI encoding-salted-hash: Salted hash algorithms secure-hash-ui: Configure hashing using the admin UI --- # Secure sensitive values There are two ways to encode attribute values for managed objects—reversible encryption and salted hashing algorithms. Examples of encoded attribute values 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 [Manage password policies](passwords.html). You configure attribute value encoding, per schema property, in the managed object configuration *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint, or directly in the conf/managed.json file.)*. The following sections show how to use reversible encryption and salted hash algorithms to encode attribute values. ## Reversible encryption Reversible encryption secures your data by encrypting it with a key. You should use encryption in cases where you need to decrypt the sensitive data to synchronize it or provide it to another system. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Encryption keys are mapped to *purposes* in your project's `conf/secrets.json` file. For more information, refer to [Secret stores](secret-stores.html). | The following managed object configuration *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint, or directly in the conf/managed.json file.)* encrypts and decrypts the `password` attribute using the default `idm.password.encryption` purpose: ```json { "objects" : [ { "name" : "user", ... "schema" : { ... "properties" : { ... "password" : { "title" : "Password", ... "encryption" : { "purpose" : "idm.password.encryption" }, "scope" : "private", } ... } ] } ``` You specify the encryption cipher or keysize by specifying a `cipher` property of the related `encryption` object in your configuration. The `cipher` property must be a valid *transformation* string as described in the [javax.crypto.Cipher reference](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/javax/crypto/Cipher.html). The following example demonstrates using the transformation `AES/GCM/NoPadding`: ```json ... "encryption" : { "purpose": "idm.password.encryption", "cipher": "AES/GCM/NoPadding" }, ``` By default, IDM uses `AES/CBC/PKCS5Padding`—the Advanced Encryption Standard (AES) algorithm with cipher block chaining, PKCS#5 padding, and a key size of 128. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | 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](../setup-guide/chap-cli.html#cli-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`\[[1](#_footnotedef_1 "View footnote.")] | * `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`\[[1](#_footnotedef_1 "View footnote.")] | * `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` ```json "secureHash" : { "algorithm" : "SHA-256", "saltLength" : 16 } ``` * `SHA-384` ```json "secureHash" : { "algorithm" : "SHA-384", "saltLength" : 16 } ``` * `SHA-512` ```json "secureHash" : { "algorithm" : "SHA-512", "saltLength" : 16 } ``` * `Bcrypt`\[[1](#_footnotedef_1 "View footnote.")] ```json "secureHash" : { "algorithm" : "BCRYPT", "cost" : 16 } ``` * `Scrypt`\[[1](#_footnotedef_1 "View footnote.")] ```json "secureHash" : { "algorithm" : "SCRYPT", "hashLength" : 16, "saltLength" : 16, "n" : 32768, "r" : 8, "p" : 1 } ``` * Password-Based Key Derivation Function 2 (`PBKDF2`) ```json "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: ```json { "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](../setup-guide/chap-cli.html#cli-secure-hash). ### 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. > **Collapse: Show Me** > > ![Admin UI hash property](_images/Admin-UI-hash-property.gif) 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. *** [1](#_footnoteref_1). This hashing algorithm is not supported by [Bouncy Castle FIPS](security-bouncy-castle-fips.html)