Configuring Password Encryption Algorithms and Stored Password Formats

Liferay encrypts passwords using an algorithm that aligns with the recommendations from the OWASP Password Storage Cheat Sheet. The default implementation uses a PBKDF2-based configuration (PBKDF2WithHmacSHA1/160/1300000) that reflects the guidance in the cheat sheet and evolves to follow updates in OWASP’s recommendations.

When validating existing passwords or switching algorithms, you can configure the hash size, iteration count, active encryption algorithm, and the legacy algorithm.

See Portal Properties and Passwords to learn more.

Setting the Active Encryption Algorithm

Liferay supports multiple encryption algorithms. Set the active algorithm in portal-ext.properties:

passwords.encryption.algorithm=[Encryption Algorithm]

Replace the placeholder with one of the supported algorithms.

Note

This setting applies only before the first startup of the portal. For changes after the first startup, follow the steps in Migrating from an Existing Algorithm.

Migrating from an Existing Algorithm

When switching algorithms or upgrading from older versions, designate the legacy algorithm so Liferay can validate existing password hashes.

During migration,

New passwords use the new algorithm (set in the portal properties).
Existing passwords continue to validate with the legacy algorithm.
Users migrate to the new algorithm after logging in or updating their password.

Set the legacy algorithm in portal-ext.properties:

passwords.encryption.algorithm.legacy=[Legacy Encryption Algorithm]

Replace the placeholder with one of the supported algorithms.

Supported Algorithms

Available encryption algorithms include:

BCRYPT
MD2
MD5
NONE
PBKDF2WithHmacSHA1/160/1300000 or PBKDF2WithHmacSHA1/[Key Size]/[rounds]
SHA
SHA-256
SHA-384
SSHA
UFC-CRYPT

Warning

The NONE algorithm stores plain text passwords. This is a severe security risk.

Stored Password Format

Liferay stores PBKDF2-encrypted passwords as a Base64-encoded binary structure. The encoded data contains the key size, iteration count, salt, and derived key.

The binary layout is

4 bytes: key size (in bits)
4 bytes: iteration count
16 bytes: salt
N bytes: derived key (Key Size / 8 bytes; 20 bytes for HMAC-SHA1)

The key size and number of rounds are configurable. For example: PBKDF2WithHmacSHA1/256/2000000 or PBKDF2WithHmacSHA1/192/1000000.

Note

You can lower the number of rounds if needed (for example, on slower production hardware). However, the default value (1,300,000) is recommended for HMAC-SHA1 according to the OWASP Password Storage Cheat Sheet.

The standard algorithm’s (PBKDF2WithHmacSHA1/160/1300000) stored value includes