# Trusted Language Extensions for PostgreSQL のフックリファレンス
<a name="PostgreSQL_trusted_language_extension-hooks-reference"></a>

Trusted Language Extensions for 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` 関数は、パスチェックフックが有効かどうかを制御します。パスチェックフックには 3 種類の設定があります。
+ `off` – `passcheck` パスワードチェックフックをオフにします。これは、デフォルト値です。
+ `on` – `passcode` パスワードチェックフックをオンにして、パスワードとテーブルを照合します。
+ `require` – パスワードチェックフックを定義する必要があります。

### 使用に関する注意事項
<a name="passcheck_hook-usage"></a>

`passcheck` フックをオンまたはオフにするには、Aurora PostgreSQL DB クラスターのライターインスタンス、のカスタム DB パラメータグループを変更する必要があります。

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