credcheck

Overview

Version

Install

You can install credcheck directly. First, make sure the PGDG repository is added and enabled:

pig repo add pgdg -u          # Add PGDG repo and update cache

Install the extension using pig or apt/yum/dnf:

pig install credcheck;          # Install for current active PG version

pig ext install -y credcheck -v 18  # PG 18
pig ext install -y credcheck -v 17  # PG 17
pig ext install -y credcheck -v 16  # PG 16
pig ext install -y credcheck -v 15  # PG 15
pig ext install -y credcheck -v 14  # PG 14

dnf install -y credcheck_18       # PG 18
dnf install -y credcheck_17       # PG 17
dnf install -y credcheck_16       # PG 16
dnf install -y credcheck_15       # PG 15
dnf install -y credcheck_14       # PG 14

apt install -y postgresql-18-credcheck   # PG 18
apt install -y postgresql-17-credcheck   # PG 17
apt install -y postgresql-16-credcheck   # PG 16
apt install -y postgresql-15-credcheck   # PG 15
apt install -y postgresql-14-credcheck   # PG 14

Preload:

shared_preload_libraries = 'credcheck';

Create Extension:

CREATE EXTENSION credcheck;

Usage

Sources:

• v5.0 README
• v5.0 changelog
• SQL objects 5.0.0
• Password history WAL implementation
• Login-event setup

credcheck enforces username and plaintext-password rules during role creation, password changes and role renames. It also tracks password reuse, bans repeated authentication failures and can require a password change at first login. Configure policy as a superuser; the defaults do not enforce a comprehensive password-strength policy.

Enable and Set Policy

Add the library to the existing preload list and restart PostgreSQL. Install SQL objects in each database where administrators need its views and reset functions:

shared_preload_libraries = 'credcheck'
credcheck.password_min_length = 12
credcheck.password_contain_username = on
credcheck.password_reuse_history = 2
credcheck.password_reuse_interval = 365

CREATE EXTENSION credcheck;
CREATE ROLE app_user LOGIN PASSWORD 'example-Strong-Pass#123';
SELECT rolename, password_date FROM pg_password_history;

The interval is in days. Installing the SQL extension is separate from loading the server-wide hooks. Upstream release 5.0 uses SQL extension version 5.0.0; installing upgraded files requires a restart to reload the library.

Policy Index

CrackLib strength checking is available only when the library was built with that support and its dictionary is available.

Password History and Replication

History contains SHA-256 password hashes, is shared across databases, and is persisted in $PGDATA/pg_password_history. Include that file in backup planning and protect access to the SQL history view, which is granted to PUBLIC by default. credcheck.history_max_size changes the shared-memory capacity and requires a restart.

Version 5.0 replicates history changes through custom WAL resource manager ID 150 on PostgreSQL 15 and later. Keep the matching library preloaded on replicas and recovery servers that replay its WAL. Earlier PostgreSQL versions retain the file-backed history path without this replication support. History-reset and timestamp-test functions reject execution during recovery.

SELECT pg_password_history_reset('app_user');

Resetting history removes reuse protection for those records; reserve it for administrators.

Authentication and Password Changes

credcheck.max_auth_failure = 3
credcheck.auth_delay_ms = 1000
credcheck.whitelist_auth_failure = 'service_user'
credcheck.password_change_first_login = true

SELECT * FROM pg_banned_role;
SELECT pg_banned_role_reset('app_user');
ALTER ROLE app_user SET credcheck_internal.force_change_password = true;

Bans remain until reset and their cache is lost at restart. credcheck.reset_superuser provides the documented superuser recovery path; credcheck.auth_failure_cache_size requires a restart.

Use the actual parameter credcheck.disallow_change_password to prohibit password changes. Even superusers are affected unless they enable credcheck.superuser_nocheck in their session. This exemption bypasses all corresponding role checks and must be controlled.

credcheck.password_valid_warning needs PostgreSQL 17 or later and the official login event trigger installed separately in every relevant database; SQL extension creation does not install that trigger.

Plaintext Boundary

Strength and reuse checks need plaintext at password-change time. Already hashed passwords are rejected by default, including passwords sent by psql’s \password. Setting credcheck.encrypted_password_allowed accepts them without providing equivalent plaintext checks. Protect the password-change connection and do not assume existing credentials are scanned retroactively. Username checks are skipped when creating a role without a password or renaming a role with no password.