本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 適用於 PostgreSQL 的受信任語言延伸模組的掛鉤參考
<a name="PostgreSQL_trusted_language_extension-hooks-reference"></a>

適用於 PostgreSQL 的受信任語言延伸模組支援 PostgreSQL 掛鉤。*掛鉤*是開發人員可用於擴充 PostgreSQL 核心功能的內部回呼機制。透過使用掛鉤，開發人員可以實作自己的函數或程序，以在各種資料庫操作期間使用，從而以某種方式修改 PostgreSQL 的行為。例如，您可以使用 `passcheck` 掛鉤，來自訂 PostgreSQL 在為使用者 (角色) 建立或變更密碼時如何處理所提供的密碼。

檢視下列文件，以了解 TLE 延伸模組可用的 passcheck 勾點。若要進一步了解可用的勾點，包括用戶端驗證勾點，請參閱[受信任語言延伸模組勾點](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)
+ [Configuration](#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`。

### Configuration
<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"
```