Default implementation of CredentialEncoder is DatabaseReadingSaltEncoder. It uses password hashing with a SHA-256 algorithm, and salting with random salts. Those salted hashes are then stored in the database.

If starting from fresh database (no migration from a previous portal release), it is sufficient to keep the default choice provided by DatabaseReadingSaltEncoder, or possibly switch to FileReadingSaltEncoder.

The implementation of CredentialEncoder is configured in Picketlink IDM configuration file JPP_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/picketlink-idm/picketlink-idm-config.xml.

Usually the most important are options of realm idm_portal starting with prefix credentialEncoder. Possible implementations are HashingEncoder, DatabaseReadingSaltEncoder, and FileReadingSaltEncoder.

This implementation uses only hashing of passwords with MD5 algorithm without salting. It is not the safest solution but it is backward compatible with the previous portal releases, so there are no issues with database migration. The configuration is as follows:

​
​<option>
​  <name>credentialEncoder.class</name>
​  <value>org.picketlink.idm.impl.credential.HashingEncoder</value>
​</option>
​<option>
​  <name>credentialEncoder.hashAlgorithm</name>
​  <value>MD5</value>
​</option>

This is the default choice. This implementation provides salting of password in addition to hashing. The salt is unique for each user, so it is much more complicated to decrypt password via brute force, if an attacker steals encoded passwords from your database. The salt is generated randomly for each user and stored in the PicketLink IDM database as an attribute. Random generation of salt ensures that all users have different salts, so even if two users have the same password, the encoded password in database will be different for them. Here is configuration example, which is using SHA-256 algorithm for hashing (more secure than MD5) and algorithm SHA1PRNG for generation of random salts.

​
​<option>
​  <name>credentialEncoder.class</name>
​  <value>org.picketlink.idm.impl.credential.DatabaseReadingSaltEncoder</value>
​</option>
​<option>
​  <name>credentialEncoder.hashAlgorithm</name>
​  <value>SHA-256</value>
​</option>
​<option>
​  <name>credentialEncoder.secureRandomAlgorithm</name>
​  <value>SHA1PRNG</value>
​</option>

The FileReadingSaltEncoder also uses hashing and salting, so it is similar to the previous encoder. Theoretically it is even more secure, because salts are not stored in the PicketLink IDM database together with passwords. Salt for each user is generated from saltPrefix and the user's user name. saltPrefix is read from a file on the host computer.

​
​
​<option>
​  <name>credentialEncoder.class</name>
​  <value>org.picketlink.idm.impl.credential.FileReadingSaltEncoder</value>
​</option>
​<option>
​  <name>credentialEncoder.hashAlgorithm</name>
​  <value>SHA-256</value>
​</option>
​<option>
​  <name>credentialEncoder.fileLocation</name>
​  <value>/salt/mysalt.txt</value>
​</option>

The FileReadingSaltEncoderis arguably the most secure of all options, but in addition to DatabaseReadingSaltEncoder, you need to set the file with salt.

The /salt/mysalt.txt file must exist and must be readable by the user who starts the portal. The file must be properly secured so that it is not readable by every user. The content of the file can be a random phrase, such as a4564dac2aasddsklklkajdgnioiow.

As mentioned previously, our current default implementation DatabaseReadingSaltEncoder is not compatible with previous releases of GateIn Portal. In GateIn Portal 3.5 and older, we used MD5 hashing without salts. So to be backwards compatible, you will need to switch from default implementation of DatabaseReadingSaltEncoder and configure HashingEncoder with MD5 hashes. Without this change, your users cannot login into GateIn Portal because their passwords are stored in Picketlink IDM database as MD5 hashes, but current default encoder is using SHA-256 and salts, so comparisons will be different.

We decided to do this change and switch default algorithm, because MD5 is nowadays not treated as very secure solution.