credcheck

概览

版本

安装

您可以直接安装 credcheck 扩展包的预置二进制包，首先确保 PGDG 仓库已经添加并启用：

pig repo add pgdg -u          # 添加 PGDG 仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展：

pig install credcheck;          # 当前活跃 PG 版本安装

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

预加载配置：

shared_preload_libraries = 'credcheck';

创建扩展：

CREATE EXTENSION credcheck;

用法

来源：

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

credcheck 在角色创建、密码修改和角色重命名时检查用户名与明文密码，还能限制密码重用、封禁多次认证失败的用户，并要求首次登录修改密码。策略由超级用户配置；默认值不构成完整的密码强度策略。

启用和设置策略

将库加入现有预加载列表并重启 PostgreSQL。在管理员需要视图和重置函数的各数据库中安装 SQL 对象：

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;

时间间隔单位为天。安装 SQL 扩展与加载服务器范围的钩子是两个步骤。上游发布版 5.0 使用 SQL 扩展版本 5.0.0；安装升级文件后需要重启，以重新加载库。

策略索引

CrackLib 强度检查仅在库编译时启用相应支持且字典可用时生效。

密码历史与复制

历史记录保存 SHA-256 密码散列，在数据库间共享，并持久化到 $PGDATA/pg_password_history。应将该文件纳入备份，并保护 SQL 历史视图的访问权限；该视图默认向 PUBLIC 授予查询权限。credcheck.history_max_size 改变共享内存容量，需要重启。

5.0 在 PostgreSQL 15 及以上通过编号 150 的自定义 WAL 资源管理器复制历史变化。重放这些 WAL 的副本和恢复服务器应预加载匹配的库。较早 PostgreSQL 版本保留文件持久化历史，但没有这项复制支持。历史重置和时间戳测试函数在恢复期间拒绝执行。

SELECT pg_password_history_reset('app_user');

重置历史会移除相应记录的密码重用保护，应仅由管理员操作。

认证与密码修改

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;

封禁持续到记录被重置，其缓存会在重启时丢失。credcheck.reset_superuser 提供上游说明的超级用户恢复入口；credcheck.auth_failure_cache_size 需要重启。

禁止修改密码的实际参数是 credcheck.disallow_change_password。超级用户也受其影响，除非在会话中启用 credcheck.superuser_nocheck。这个豁免会绕过相应的全部角色检查，应严格控制。

credcheck.password_valid_warning 要求 PostgreSQL 17 及以上，并需在每个相关数据库单独安装官方登录事件触发器；创建 SQL 扩展不会安装该触发器。

明文边界

强度与重用检查需要在修改密码时获得明文。默认拒绝已计算散列的密码，包括 psql 的 \password 提交的密码。启用 credcheck.encrypted_password_allowed 可以接受它们，但不会提供等效的明文检查。应保护密码修改连接，也不要假设扩展会追溯扫描已有凭证。创建无密码角色，或重命名没有密码的角色时，会跳过用户名检查。