# Referência de ganchos para Trusted Language Extensions para PostgreSQL
<a name="PostgreSQL_trusted_language_extension-hooks-reference"></a>

O Trusted Language Extensions para PostgreSQL é compatível com ganchos do PostgreSQL. Um *gancho* é um mecanismo interno de retorno de chamada disponível para que os desenvolvedores estendam a funcionalidade principal do PostgreSQL. Usando ganchos, os desenvolvedores podem implementar suas próprias funções ou procedimentos para uso durante várias operações de banco de dados, modificando assim o comportamento do PostgreSQL de alguma forma. Por exemplo, você pode usar um gancho `passcheck` para personalizar a forma como o PostgreSQL manipula as senhas fornecidas ao criar ou alterar senhas para usuários (funções).

Veja a documentação a seguir para saber mais sobre o hook passcheck disponível para as extensões TLE. Para saber mais sobre os hooks disponíveis, incluindo o hook de autenticação do cliente, consulte [Trusted Language Extensions hooks](https://github.com/aws/pg_tle/blob/main/docs/04_hooks.md).

## Gancho de verificação de senha (passcheck)
<a name="passcheck_hook"></a>

O gancho `passcheck` é usado para personalizar o comportamento do PostgreSQL durante o processo de verificação de senha para os comandos SQL e o metacomando `psql` a seguir.
+ `CREATE ROLE username ...PASSWORD`: para obter mais informações, consulte [CREATE ROLE](https://www.postgresql.org/docs/current/sql-createrole.html) na documentação do PostgreSQL.
+ `ALTER ROLE username...PASSWORD`: para obter mais informações, consulte [ALTER ROLE](https://www.postgresql.org/docs/current/sql-alterrole.html) na documentação do PostgreSQL.
+ `\password username`: esse metacomando interativo `psql` altera com segurança a senha do usuário especificado usando o hash da senha antes de usar a sintaxe `ALTER ROLE ... PASSWORD` de forma transparente. O metacomando é um invólucro seguro para o comando `ALTER ROLE ... PASSWORD`, portanto, o gancho se aplica ao comportamento do metacomando `psql`.

Para ver um exemplo, consulte [Lista de códigos do gancho de verificação de senha](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md#PostgreSQL_trusted_language_extension-example-hook_code_listing).

**Contents**
+ [Protótipo de função](#passcheck_hook-prototype)
+ [Argumentos](#passcheck_hook-arguments)
+ [Configuração](#passcheck_hook-configuration)
+ [Observações de uso](#passcheck_hook-usage)

### Protótipo de função
<a name="passcheck_hook-prototype"></a>

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

### Argumentos
<a name="passcheck_hook-arguments"></a>

A função de gancho `passcheck` usa os seguintes argumentos:
+ `username`: o nome (como texto) da função (nome de usuário) que está definindo uma senha.
+ `password`: o texto simples ou a senha com hash. A senha digitada deve corresponder ao tipo especificado em `password_type`.
+ `password_type`: especifique o formato `pgtle.password_type` da senha. Esse formato pode ser uma das opções a seguir.
  + `PASSWORD_TYPE_PLAINTEXT`: uma senha de texto simples.
  + `PASSWORD_TYPE_MD5`: uma senha que foi criptografada usando o algoritmo MD5 (resumo de mensagens 5).
  + `PASSWORD_TYPE_SCRAM_SHA_256`: uma senha que foi criptografada usando o algoritmo SCRAM-SHA-256.
+ `valid_until`: especifique a hora em que a senha se torna inválida. Esse argumento é opcional. Se você usar esse argumento, especifique a hora como um valor `timestamptz`.
+ `valid_null`: se esse valor booliano estiver definido como `true`, a opção `valid_until` será definida como `NULL`.

### Configuração
<a name="passcheck_hook-configuration"></a>

A função `pgtle.enable_password_check` controla se o gancho passcheck está ativo. O gancho passcheck tem três configurações possíveis.
+ `off`: desativa o gancho de verificação de senha `passcheck`. Este é o valor padrão.
+ `on`: ativa o gancho de verificação de senha `passcode` para que as senhas sejam conferidas na tabela.
+ `require`: requer que um gancho de verificação de senha seja definido.

### Observações de uso
<a name="passcheck_hook-usage"></a>

Para ativar ou desativar o gancho `passcheck`, você precisa modificar o grupo de parâmetros de banco de dados personalizado para a instância de banco de dados do RDS para PostgreSQL.

Para Linux, macOS ou 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"
```

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