# 适用于 PostgreSQL 的可信语言扩展的挂钩参考
<a name="PostgreSQL_trusted_language_extension-hooks-reference"></a>

适用于 PostgreSQL 的可信语言扩展支持 PostgreSQL 挂钩。*挂钩*是一种内部回调机制，可供开发人员扩展 PostgreSQL 的核心功能。通过使用挂钩，开发人员可以实现自己的函数或过程以在各种数据库操作中使用，从而以某种方式修改 PostgreSQL 的行为。例如，您可以使用 `passcheck` 挂钩自定义 PostgreSQL 如何处理在为用户（角色）创建或更改密码时提供的密码。

查看以下文档，了解可用于 TLE 扩展的 passcheck 钩子。要了解有关可用钩子（包括客户端身份验证钩子）的更多信息，请参阅 [Trusted Language Extensions hooks](https://github.com/aws/pg_tle/blob/main/docs/04_hooks.md)。

## 密码检查挂钩（passcheck）
<a name="passcheck_hook"></a>

`passcheck` 挂钩用于在以下 SQL 命令和 `psql` 元命令的密码检查过程中自定义 PostgreSQL 行为。
+ `CREATE ROLE username ...PASSWORD` – 有关更多信息，请参阅 PostgreSQL 文档中的 [CREATE ROLE](https://www.postgresql.org/docs/current/sql-createrole.html)。
+ `ALTER ROLE username...PASSWORD` – 有关更多信息，请参阅 PostgreSQL 文档中的 [ALTER ROLE](https://www.postgresql.org/docs/current/sql-alterrole.html)。
+ `\password username` – 此交互式 `psql` 元命令在透明地使用 `ALTER ROLE ... PASSWORD` 语法之前，通过对密码进行哈希处理来安全地更改指定用户的密码。元命令是 `ALTER ROLE ... PASSWORD` 命令的安全包装器，因此挂钩适用于 `psql` 元命令的行为。

有关示例，请参阅[密码检查挂钩代码列表](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md#PostgreSQL_trusted_language_extension-example-hook_code_listing)。

**Contents**
+ [函数原型](#passcheck_hook-prototype)
+ [参数](#passcheck_hook-arguments)
+ [配置](#passcheck_hook-configuration)
+ [使用说明](#passcheck_hook-usage)

### 函数原型
<a name="passcheck_hook-prototype"></a>

```
passcheck_hook(username text, password text, password_type pgtle.password_types, valid_until timestamptz, valid_null boolean)
```

### 参数
<a name="passcheck_hook-arguments"></a>

`passcheck` 挂钩函数采用以下参数。
+ `username` – 设置密码的角色（用户名）的名称（文本）。
+ `password` – 纯文本或哈希处理的密码。输入的密码应与在 `password_type` 中指定的类型相匹配。
+ `password_type` – 指定密码的 `pgtle.password_type` 格式。此格式可能是以下选项之一。
  + `PASSWORD_TYPE_PLAINTEXT` – 纯文本密码。
  + `PASSWORD_TYPE_MD5` – 已使用 MD5（消息摘要 5）算法进行哈希处理的密码。
  + `PASSWORD_TYPE_SCRAM_SHA_256` – 已使用 SCRAM-SHA-256 算法进行哈希处理的密码。
+ `valid_until` – 指定密码变为失效的时间。此参数是可选的。如果使用此参数，请将时间指定为 `timestamptz` 值。
+ `valid_null` – 如果此布尔值设置为 `true`，则 `valid_until` 选项设置为 `NULL`。

### 配置
<a name="passcheck_hook-configuration"></a>

函数 `pgtle.enable_password_check` 控制 passcheck 挂钩是否处于活动状态。passcheck 挂钩有三种可能的设置。
+ `off` – 关闭 `passcheck` 密码检查挂钩。这是默认值。
+ `on` – 打开 `passcode` 密码检查挂钩，以便对照表检查密码。
+ `require` – 需要定义密码检查挂钩。

### 使用说明
<a name="passcheck_hook-usage"></a>

要打开或关闭 `passcheck` 挂钩，您需要修改 RDS for PostgreSQL 数据库实例的自定义数据库参数组。

对于 Linux、macOS 或 Unix：

```
aws rds modify-db-parameter-group \
    --region aws-region \
    --db-parameter-group-name your-custom-parameter-group \
    --parameters "ParameterName=pgtle.enable_password_check,ParameterValue=on,ApplyMethod=immediate"
```

对于：Windows

```
aws rds modify-db-parameter-group ^
    --region aws-region ^
    --db-parameter-group-name your-custom-parameter-group ^
    --parameters "ParameterName=pgtle.enable_password_check,ParameterValue=on,ApplyMethod=immediate"
```