Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Update docs for change to set_key functions #433

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 1 commit into from
Jun 16, 2025
Merged

Update docs for change to set_key functions #433

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
17 changes: 11 additions & 6 deletions contrib/pg_tde/documentation/docs/architecture/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -276,15 +276,19 @@ pg_tde_REVOKE_database_key_management_FROM_role

### Creating and rotating keys

Principal keys can be created or rotated using the following functions:
Principal keys can be created using the following functions:

```sql
pg_tde_set_key_using_(global/database)_key_provider('key-name', 'provider-name', ensure_new_key)
pg_tde_set_server_key_using_(global/database)_key_provider('key-name', 'provider-name', ensure_new_key)
pg_tde_set_default_key_using_(global/database)_key_provider('key-name', 'provider-name', ensure_new_key)
pg_tde_create_key_using_(global/database)_key_provider('key-name', 'provider-name')
```

`ensure_new_key` is a boolean parameter defaulting to false. If it is `true` the function might return an error instead of setting the key if it already exists on the provider.
Principal keys can be used or rotated using the following functions:

```sql
pg_tde_set_key_using_(global/database)_key_provider('key-name', 'provider-name')
pg_tde_set_server_key_using_(global/database)_key_provider('key-name', 'provider-name')
pg_tde_set_default_key_using_(global/database)_key_provider('key-name', 'provider-name')
```

### Default principal key

Expand All @@ -296,7 +300,8 @@ With this feature, it is possible for the entire database server to easily use t

You can manage a default key with the following functions:

* `pg_tde_set_default_key_using_global_key_provider('key-name','provider-name','true/false')`
* `pg_tde_create_key_using_global_key_provider('key-name','provider-name')`
* `pg_tde_set_default_key_using_global_key_provider('key-name','provider-name')`
* `pg_tde_delete_default_key()`

!!! note
Expand Down
69 changes: 31 additions & 38 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 @@ -230,85 +230,78 @@ These functions list the details of all key providers for the current database o

## Principal key management

Use these functions to create a new principal key for a specific scope such as a current database, a global or default scope. You can also use them to start using a different existing key for a specific scope.
Use these functions to create a new principal key at a given keyprover, and to use those keys for a specific scope such as a current database, a global or default scope. You can also use them to start using a different existing key for a specific scope.

Princial keys are stored on key providers by the name specified in this function - for example, when using the Vault provider, after creating a key named "foo", a key named "foo" will be visible on the Vault server at the specified mount point.

### pg_tde_set_key_using_database_key_provider
### pg_tde_creates_key_using_database_key_provider

Creates or reuses a principal key for the **current** database, using the specified local key provider. It also rotates internal encryption keys to use the specified principal key.
Creates a principal key at a database local key provider with the given name. For later use with pg_tde_set_key_using_database_key_provider().

This function is typically used when working with per-database encryption through a local key provider.
```sql
SELECT pg_tde_create_key_using_database_key_provider(
'key-name',
'provider-name'
);
```
### pg_tde_create_key_using_global_key_provider

Creates a principal key at a global key provider with the given name. For later use with pg_tde_set_ series of functions.

```sql
SELECT pg_tde_set_key_using_database_key_provider(
SELECT pg_tde_create_key_using_global_key_provider(
'key-name',
'provider-name',
'false' -- or 'true'
'provider-name'
);
```

For the third parameter (`true`, `false`, or omitted):
### pg_tde_set_key_using_database_key_provider

Sets the principal key for the **current** database, using the specified local key provider. It also rotates internal encryption keys to use the specified principal key.

* `true`: Requires the key to be newly created. If a key with the same name already exists, the function fails.
* `false` (default if omitted): Reuses the existing key with that name, if present. If the key does not exist, a new key is created.
This function is typically used when working with per-database encryption through a local key provider.

```sql
SELECT pg_tde_set_key_using_database_key_provider(
'key-name',
'provider-name'
);
```
### pg_tde_set_key_using_global_key_provider

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.
Sets 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(
'key-name',
'provider-name',
'ensure_new_key'
'provider-name'
);
```

The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:

* If set to `true`, a new key must be unique.
If the provider already stores a key by that name, the function returns an error.
* If set to `false` (default), an existing principal key may be reused.

### pg_tde_set_server_key_using_global_key_provider

Creates or rotates the server principal key using the specified global key provider. Use this function to set a principal key for WAL encryption.
Sets 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(
'key-name',
'provider-name',
'ensure_new_key'
'provider-name'
);
```

The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:

* If set to `true`, a new key must be unique.
If the provider already stores a key by that name, the function returns an error.
* If set to `false` (default), an existing principal key may be reused.

### pg_tde_set_default_key_using_global_key_provider

Creates or rotates the default principal key for the server using the specified global key provider.
Sets or rotates the default principal key for the server using the specified global key provider.

The default key is automatically used as a principal key by any database that doesn't have an individual key provider and key configuration.
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(
'key-name',
'provider-name',
'ensure_new_key'
'provider-name'
);
```

The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:

* If set to `true`, a new key must be unique.
If the provider already stores a key by that name, the function returns an error.
* If set to `false` (default), an existing principal key may be reused.

## Encryption status check

### pg_tde_is_encrypted
Expand Down
27 changes: 19 additions & 8 deletions ...g_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,34 @@ You can configure a default principal key using a global key provider. This key

## Create a default principal key

To create a global principal key, run:

```sql
SELECT pg_tde_create_key_using_global_key_provider(
'key-name',
'global_vault_provider'
);
```

## Configure a default principal key

To configure a global principal key, run:

```sql
SELECT pg_tde_set_default_key_using_global_key_provider(
'key-name',
'global_vault_provider',
'false' -- or 'true', or omit entirely
'global_vault_provider'
);
```

## Parameter description

* `key-name` is the name under which the principal key is stored in the provider.
* `global_vault_provider` is the name of the global key provider you previously configured.
* Third parameter (optional):
* `true` requires the key to be newly created. If the key already exists, the function fails.
* `false` or omitted (default), allows reuse of an existing key if it exists. If not, a new key is created under the specified name.

## How key generation works

If the specified key does **not** exist, a new encryption key is created under the given name. In this case, the key material (actual cryptographic key) is auto-generated by `pg_tde` and stored securely by the configured provider.
The key material (actual cryptographic key) is auto-generated by `pg_tde` and stored securely by the configured provider.

!!! note
This process sets the **default principal key** for the server. Any database without its own key configuration will use this key.
Expand All @@ -34,10 +41,14 @@ If the specified key does **not** exist, a new encryption key is created under t
This example is for testing purposes only. Replace the key name and provider name with your values:

```sql
SELECT pg_tde_create_key_using_global_key_provider(
'test-db-master-key',
'file-vault'
);

SELECT pg_tde_set_key_using_global_key_provider(
'test-db-master-key',
'file-vault',
'false'
'file-vault'
);
```

Expand Down
35 changes: 25 additions & 10 deletions contrib/pg_tde/documentation/docs/how-to/multi-tenant-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Load the `pg_tde` at startup time. The extension requires additional shared memo

!!! tip

You can have the `pg_tde` extension automatically enabled for every newly created database. Modify the template `template1` database as follows:
You can have the `pg_tde` extension automatically enabled for every newly created database. Modify the template `template1` database as follows:

```sh
psql -d template1 -c 'CREATE EXTENSION pg_tde;'
Expand All @@ -57,8 +57,8 @@ You must do these steps for every database where you have created the extension.
=== "With KMIP server"

Make sure you have obtained the root certificate for the KMIP server and the keypair for the client. The client key needs permissions to create / read keys on the server. Find the [configuration guidelines for the HashiCorp Vault Enterprise KMIP Secrets Engine](https://developer.hashicorp.com/vault/tutorials/enterprise/kmip-engine).
For testing purposes, you can use the PyKMIP server which enables you to set up required certificates. To use a real KMIP server, make sure to obtain the valid certificates issued by the key management appliance.

For testing purposes, you can use the PyKMIP server which enables you to set up required certificates. To use a real KMIP server, make sure to obtain the valid certificates issued by the key management appliance.

```sql
SELECT pg_tde_add_database_key_provider_kmip('provider-name','kmip-addr', 5696, '/path_to/client_cert.pem', '/path_to/client_key.pem', '/path_to/server_certificate.pem');
Expand All @@ -85,9 +85,9 @@ You must do these steps for every database where you have created the extension.

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

where:
where:

* `url` is the URL of the Vault server
* `mount` is the mount point where the keyring should store the keys
Expand All @@ -113,25 +113,40 @@ You must do these steps for every database where you have created the extension.
```sql
SELECT pg_tde_add_database_key_provider_file('file-keyring', '/tmp/pg_tde_test_local_keyring.per');
```

2. Add a principal key

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

SELECT pg_tde_create_key_using_database_key_provider('name-of-the-key', 'provider-name');
```

where:

* `name-of-the-key` is the name of the principal key. You will use this name to identify the key.
* `provider-name` is the name of the key provider you added before. The principal key will be associated with this provider.
* `ensure_new_key` defines if a principal key must be unique. The default value `true` means that you must speficy a unique key during key rotation. The `false` value allows reusing an existing principal key.

<i warning>:material-information: Warning:</i> This example is for testing purposes only:

```sql
SELECT pg_tde_set_key_using_database_key_provider('test-db-master-key','file-vault','ensure_new_key');
SELECT pg_tde_create_key_using_database_key_provider('test-db-master-key', 'file-vault');
```

!!! note
The key is auto-generated.

3. Use the key as principal key
```sql

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

where:

* `name-of-the-key` is the name of the principal key. You will use this name to identify the key.
* `provider-name` is the name of the key provider you added before. The principal key will be associated with this provider.

<i warning>:material-information: Warning:</i> This example is for testing purposes only:

```sql
SELECT pg_tde_set_key_using_database_key_provider('test-db-master-key','file-vault');
```