<option> <name>credentialEncoder.class</name> <value>org.picketlink.idm.impl.credential.HashingEncoder</value> </option> <option> <name>credentialEncoder.hashAlgorithm</name> <value>MD5</value> </option>
GateIn Portal is using Picketlink IDM framework to store information about identity objects (users/groups/memberships) and more info about this is in PicketLink IDM integration . For better security, Picketlink IDM does not save user passwords into database in plain-text, but it uses CredentialEncoder, which encode password and save the encoded form into Picketlink IDM database.
Later when user want to authenticate, he needs to provide his password in plain-text via web login form. Provided password is then encoded and compared with encoded password from Picketlink IDM database. GateIn Portal is then able to authenticate user based on this comparison.
Default implementation of CredentialEncoder is DatabaseReadingSaltEncoder. It's using password hashing with SHA-256 algorithm and salting with random salts. Those salted hashes are then stored in database.
The default DatabaseReadingSaltEncoder is safe solution, but it's not backward compatible with previous releases of GateIn Portal before version 3.6. So if you migrate from older release of GateIn Portal, you will need to switch to HashingEncoder and configure it. See Migration from previous releases for more info.
However if you are starting from fresh database (no migration from previous GateIn Portal release), it's sufficient to stick with default choice provided by DatabaseReadingSaltEncoder or possibly switch to FileReadingSaltEncoder. See below for details about various implementations of CredentialEncoder.
The implementation of CredentialEncoder is configured in Picketlink IDM configuration file, which is usually in location GATEIN_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/picketlink-idm/picketlink-idm-config.xml (It could be different location if you are using LDAP. See PicketLink IDM integration and/or LDAP integration for more info).
Usually the most important are options of realm idm_portal starting with prefix credentialEncoder.. Possible implementations are:
It uses only hashing of passwords with MD5 algorithm without salting. As mentioned previously, it's not safest solution but it's backward compatible with previous GateIn Portal releases, so there are no issues with database migration from previous release. Configuration looks like this:
<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's much more complicated to decrypt password via brute force, if some attacker steal encoded passwords from your database. The salt is generated randomly for each user and stored in Picketlink IDM database as attribute. Random generation of salt ensure that all users have different salts, so even if two users have 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>
For random generating of password salts, we are using SecureRandom object, but initialization of this object may be slower on some operating systems. So we are leveraging SecureRandomService, which is used on other places in GateIn Portal . If you don't want to use this service and rather always create new instance of SecureRandom object during each encoding request, you can switch option useSecureRandomService to false in file GATEIN_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/idm-configuration.xml. Default value is true:
<value-param> <name>useSecureRandomService</name> <value>true</value> </value-param>
It also uses hashing and salting, so it's similar like previous encoder. But it's theoretically even more secure, because salts are not stored in Picketlink IDM database together with passwords. Salt of each user is generated from saltPrefix and user's username. And saltPrefix is read from some file in your filesystem. Configuration can look like this:
<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>
Please note that specified file /salt/mysalt.txt must exist and must be readable by user, which executed GateIn Portal. But file should be properly secured to not be readable by every user of your OS. The file can have some random content phrase, for example a4564dac2aasddsklklkajdgnioiow .
So the FileReadingSaltEncoder is probably most secure of all options, but in addition to DatabaseReadingSaltEncoder you need to set the file with salt.
The CredentialEncoder from above is actually used only for encoding of passwords in Picketlink IDM database. It's not used for LDAP. Picketlink IDM LDAP implementation (LDAPIdentityStore) is sending passwords to LDAP server in plain form, because password encoding is usually provided by LDAP server itself. For example OpenDS 2 is using SHA1 based hashing of passwords with random generation of user salt (so actually something similar to our DatabaseReadingSaltEncoder implementation).
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 as described here. Without this change, your users won't be able to 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.