Skip to content

DOCS-functions-codeclean #343

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 16, 2025
Merged

DOCS-functions-codeclean #343

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b7877c1
Updated functions.md
Andriciuc May 16, 2025
448ec85
last updates to code formatting
Andriciuc May 16, 2025
5997da9
Merge branch 'TDE_REL_17_STABLE' into docs-functions-update
Andriciuc May 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 89 additions & 26 deletions contrib/pg_tde/documentation/docs/functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,15 +76,39 @@ The Vault provider connects to a HashiCorp Vault or an OpenBao server, and store
Use the following functions to add the Vault provider:

```sql
SELECT pg_tde_add_database_key_provider_vault_v2('provider-name','secret_token','url','mount','ca_path');
SELECT pg_tde_add_global_key_provider_vault_v2('provider-name','secret_token','url','mount','ca_path');
SELECT pg_tde_add_database_key_provider_vault_v2(
'provider-name',
'secret_token',
'url','mount',
'ca_path'
);

SELECT pg_tde_add_global_key_provider_vault_v2(
'provider-name',
'secret_token',
'url','mount',
'ca_path'
);
```

These functions change the Vault provider:

```sql
SELECT pg_tde_change_database_key_provider_vault_v2('provider-name','secret_token','url','mount','ca_path');
SELECT pg_tde_change_global_key_provider_vault_v2('provider-name','secret_token','url','mount','ca_path');
SELECT pg_tde_change_database_key_provider_vault_v2(
'provider-name',
'secret_token',
'url',
'mount',
'ca_path'
);

SELECT pg_tde_change_global_key_provider_vault_v2(
'provider-name',
'secret_token',
'url',
'mount',
'ca_path'
);
```

where:
Expand All @@ -93,11 +117,12 @@ where:
* `url` is the URL of the Vault server
* `mount` is the mount point on the Vault server where the key provider should store the keys
* `secret_token` is an access token with read and write access to the above mount point
* [optional] `ca_path` is the path of the CA file used for SSL verification
* **[optional]** `ca_path` is the path of the CA file used for SSL verification

All parameters can be either strings, or JSON objects [referencing remote parameters](how-to/external-parameters.md).

**Never specify the secret token directly, use a remote parameter instead.**
!!! important
Never specify the secret token directly, use a remote parameter instead.

#### Adding or modifying KMIP providers

Expand Down Expand Up @@ -155,7 +180,8 @@ where:
* `client-certificate` is the path to the client certificate.
* `client-key` is the path to the client key.

The specified access parameters require permission to read and write keys at the server.
!!! note
The specified access parameters require permission to read and write keys at the server.

All parameters can be either strings, or JSON objects [referencing remote parameters](how-to/external-parameters.md).

Expand All @@ -165,28 +191,44 @@ This provider manages database keys using a local keyfile.

This function is intended for development or quick testing, and stores the keys unencrypted in the specified data file.

**It is not recommended for production.**
!!! important
Local keyfile providers are **not recommended** for production environments, they lack the security and manageability of external key management systems.

Add a local keyfile provider:

```sql
SELECT pg_tde_add_database_key_provider_file('provider-name','/path/to/the/key/provider/data.file');
SELECT pg_tde_add_global_key_provider_file('provider-name','/path/to/the/key/provider/data.file');
SELECT pg_tde_add_database_key_provider_file(
'provider-name',
'/path/to/the/key/provider/data.file'
);

SELECT pg_tde_add_global_key_provider_file(
'provider-name',
'/path/to/the/key/provider/data.file'
);
```

Change a local keyfile provider:

```sql
SELECT pg_tde_change_database_key_provider_file('provider-name','/path/to/the/key/provider/data.file');
SELECT pg_tde_change_global_key_provider_file('provider-name','/path/to/the/key/provider/data.file');
SELECT pg_tde_change_database_key_provider_file(
'provider-name',
'/path/to/the/key/provider/data.file'
);

SELECT pg_tde_change_global_key_provider_file(
'provider-name',
'/path/to/the/key/provider/data.file'
);
```

where:

* `provider-name` is the name of the provider. You can specify any name, it's for you to identify the provider.
* `/path/to/the/key/provider/data.file` is the path to the key provider file.

All parameters can be either strings, or JSON objects [referencing remote parameters](how-to/external-parameters.md).
!!! note
All parameters can be either strings, or JSON objects [referencing remote parameters](how-to/external-parameters.md).

### Delete a provider

Expand All @@ -206,7 +248,8 @@ These functions list the details of all key providers for the current database o
* `pg_tde_list_all_database_key_providers()`
* `pg_tde_list_all_global_key_providers()`

**All configuration values include possibly sensitive values, such as passwords. Never specify these directly, use the remote configuration option instead.**
!!! important
All configuration values include possibly sensitive values, such as passwords. **Never** specify these directly, use the remote configuration option instead.

## Principal key management

Expand All @@ -219,7 +262,11 @@ Princial keys are stored on key providers by the name specified in this function
Creates or rotates the principal key for the current database using the specified database key provider and key name.

```sql
SELECT pg_tde_set_key_using_database_key_provider('name-of-the-key','provider-name','ensure_new_key');
SELECT pg_tde_set_key_using_database_key_provider(
'name-of-the-key',
'provider-name',
'ensure_new_key'
);
```

The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
Expand All @@ -233,7 +280,11 @@ SELECT pg_tde_set_key_using_database_key_provider('name-of-the-key','provider-na
Creates or rotates the global principal key using the specified global key provider and the key name. This key is used for global settings like WAL encryption.

```sql
SELECT pg_tde_set_key_using_global_key_provider('name-of-the-key','provider-name','ensure_new_key');
SELECT pg_tde_set_key_using_global_key_provider(
'name-of-the-key',
'provider-name',
'ensure_new_key'
);
```

The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
Expand All @@ -247,7 +298,11 @@ Creates or rotates the global principal key using the specified global key provi
Creates or rotates the server principal key using the specified global key provider. Use this function to set a principal key for WAL encryption.

```sql
SELECT pg_tde_set_server_key_using_global_key_provider('name-of-the-key','provider-name','ensure_new_key');
SELECT pg_tde_set_server_key_using_global_key_provider(
'name-of-the-key',
'provider-name',
'ensure_new_key'
);
```

The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
Expand All @@ -263,7 +318,11 @@ Creates or rotates the default principal key for the server using the specified
The default key is automatically used as a principal key by any database that doesn't have an individual key provider and key configuration.

```sql
SELECT pg_tde_set_default_key_using_global_key_provider('name-of-the-key','provider-name','ensure_new_key');
SELECT pg_tde_set_default_key_using_global_key_provider(
'name-of-the-key',
'provider-name',
'ensure_new_key'
);
```

The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
Expand All @@ -283,13 +342,17 @@ tables and indexes.
To verify that a table is encrypted, run the following statement:

```sql
SELECT pg_tde_is_encrypted('table_name');
SELECT pg_tde_is_encrypted(
'table_name'
);
```

You can also verify if the table in a custom schema is encrypted. Pass the schema name for the function as follows:

```sql
SELECT pg_tde_is_encrypted('schema.table_name');
SELECT pg_tde_is_encrypted(
'schema.table_name'
);
```

This can additionally be used to verify that indexes and sequences are encrypted.
Expand All @@ -299,23 +362,23 @@ This can additionally be used to verify that indexes and sequences are encrypted
Displays information about the principal key for the current database, if it exists.

```sql
SELECT pg_tde_key_info()
SELECT pg_tde_key_info();
```

### pg_tde_server_key_info

Displays information about the principal key for the server scope, if exists.

```sql
SELECT pg_tde_server_key_info()
SELECT pg_tde_server_key_info();
```

### pg_tde_default_key_info

Displays the information about the default principal key, if it exists.

```sql
SELECT pg_tde_default_key_info()
SELECT pg_tde_default_key_info();
```

### pg_tde_verify_key
Expand All @@ -331,7 +394,7 @@ This function checks that the current database has a properly functional encrypt
If any of the above checks fail, the function reports an error.

```sql
SELECT pg_tde_verify_key()
SELECT pg_tde_verify_key();
```

### pg_tde_verify_server_key
Expand All @@ -347,7 +410,7 @@ This function checks that the server scope has a properly functional encryption
If any of the above checks fail, the function reports an error.

```sql
SELECT pg_tde_verify_server_key()
SELECT pg_tde_verify_server_key();
```

### pg_tde_verify_default_key
Expand All @@ -363,5 +426,5 @@ This function checks that the default key is properly configured, which means:
If any of the above checks fail, the function reports an error.

```sql
SELECT pg_tde_verify_default_key()
SELECT pg_tde_verify_default_key();
```
Loading