Product Documentation

Appearance

All platforms

Password Encryption ​

When a local database user is given a password, Yellowbrick does not store the password itself. It stores a one-way verifier derived from the password. The algorithm used to derive that verifier is controlled by the password_encryption configuration parameter.

This applies only to local database users whose credentials are stored in the database. Users authenticated externally, for example through LDAP, do not have a stored password.

Supported Algorithms ​

Yellowbrick supports two password hashing algorithms:

  • MD5 — the default, used by all earlier releases. Maintained for backward compatibility.
  • SCRAM-SHA-256 — a challenge-response mechanism (RFC 7677) that uses only FIPS-approved primitives (SHA-256, HMAC, and PBKDF2). Introduced in this release.

By default, password_encryption is set to md5. Existing deployments are unaffected by this release: passwords continue to be stored and verified exactly as before unless you explicitly opt in to SCRAM-SHA-256.

When to Use SCRAM-SHA-256 ​

MD5 is not permitted in FIPS-enabled environments. A client running on a FIPS-enabled operating system cannot compute an MD5 password hash, so any attempt to authenticate a local account whose password is stored with MD5 fails. For example, a libpq-based client reports:

txt
connection failed: could not encrypt password: unsupported

SCRAM-SHA-256 avoids MD5 entirely, allowing clients in FIPS-enabled environments to authenticate with local database accounts.

Enabling SCRAM-SHA-256 ​

A password verifier is computed at the moment the password is set, so changing password_encryption affects only passwords that are created or changed after the change. Setting the parameter does not re-encrypt existing passwords.

For a Single User ​

Any user with the privilege to alter the account can convert it without changing the system default:

sql
SET password_encryption = 'scram-sha-256';
ALTER USER analyst1 PASSWORD 'new_password';

The account's stored verifier is now SCRAM-SHA-256, and no other account is affected.

For All New Passwords ​

A superuser can change the default for the whole system:

sql
ALTER SYSTEM SET password_encryption = 'scram-sha-256';

-- Reload the configuration for the change to take effect

After the change, every newly set or changed password is stored using SCRAM-SHA-256. Existing passwords remain stored with MD5 until each user resets their password.

Migrating Existing Users ​

An MD5 verifier cannot be converted to SCRAM-SHA-256, because the original password cannot be recovered from an MD5 hash. To move an existing account to SCRAM-SHA-256, set its password again — to the same value or a new one — while password_encryption is set to scram-sha-256.

A typical migration is:

  1. Set password_encryption to scram-sha-256, per session or system-wide.
  2. Have each affected user reset their password.

Accounts that are not reset continue to work with MD5.

Backward Compatibility ​

  • No authentication configuration change is required. Yellowbrick selects the authentication mechanism automatically for each account based on how its password is stored: accounts stored with MD5 continue to use MD5, and accounts stored with SCRAM-SHA-256 use SCRAM-SHA-256. The two can coexist.
  • Existing clients are unaffected for MD5 accounts. A client only needs to support SCRAM to authenticate an account whose password is stored with SCRAM-SHA-256. Current PostgreSQL-compatible drivers and libpq-based clients, including the Yellowbrick client tools (as of 7.4.5), support SCRAM. A client old enough to support only MD5 cannot authenticate a SCRAM-SHA-256 account.

Limitations ​

  • Channel binding (SCRAM-SHA-256-PLUS) is not supported. A client that requires channel binding cannot connect; clients that prefer it or do not request it are unaffected.
  • Setting a password from an already-encrypted SCRAM-SHA-256 verifier bypasses the password-reuse history check. Because each verifier uses a random salt, the server cannot compare a supplied verifier against previously used passwords, so the MAX_REUSE policy is not enforced for that change. Set passwords as a plain text literal to have the reuse policy applied. See Password Policies.