open-dsi
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

DOCS-functions-codeclean (#343)

Browse Source 
Initial update as I apply code formatting and improving important
information using note and important markers.
pull/230/head
Dragos Andriciuc 4 months ago committed by GitHub
parent 2ca6bb5a22
commit 4affafc273
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 89 additions and 26 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 115
      contrib/pg_tde/documentation/docs/functions.md

115
contrib/pg_tde/documentation/docs/functions.md
Unescape View File

@ -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: Use the following functions to add the Vault provider:
```sql ```sql
SELECT pg_tde_add_database_key_provider_vault_v2('provider-name','secret_token','url','mount','ca_path'); SELECT pg_tde_add_database_key_provider_vault_v2(
SELECT pg_tde_add_global_key_provider_vault_v2('provider-name','secret_token','url','mount','ca_path'); '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: These functions change the Vault provider:
```sql ```sql
SELECT pg_tde_change_database_key_provider_vault_v2('provider-name','secret_token','url','mount','ca_path'); SELECT pg_tde_change_database_key_provider_vault_v2(
SELECT pg_tde_change_global_key_provider_vault_v2('provider-name','secret_token','url','mount','ca_path'); '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: where:
@ -93,11 +117,12 @@ where:
* `url` is the URL of the Vault server * `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 * `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 * `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). 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 #### Adding or modifying KMIP providers
@ -155,7 +180,8 @@ where:
* `client-certificate` is the path to the client certificate. * `client-certificate` is the path to the client certificate.
* `client-key` is the path to the client key. * `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). All parameters can be either strings, or JSON objects [referencing remote parameters](how-to/external-parameters.md).
@ -165,20 +191,35 @@ 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. 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: Add a local keyfile provider:
```sql ```sql
SELECT pg_tde_add_database_key_provider_file('provider-name','/path/to/the/key/provider/data.file'); SELECT pg_tde_add_database_key_provider_file(
SELECT pg_tde_add_global_key_provider_file('provider-name','/path/to/the/key/provider/data.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: Change a local keyfile provider:
```sql ```sql
SELECT pg_tde_change_database_key_provider_file('provider-name','/path/to/the/key/provider/data.file'); SELECT pg_tde_change_database_key_provider_file(
SELECT pg_tde_change_global_key_provider_file('provider-name','/path/to/the/key/provider/data.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: where:
@ -186,7 +227,8 @@ where:
* `provider-name` is the name of the provider. You can specify any name, it's for you to identify the provider. * `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. * `/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 ### Delete a provider
@ -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_database_key_providers()`
* `pg_tde_list_all_global_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 ## Principal key management
@ -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. Creates or rotates the principal key for the current database using the specified database key provider and key name.
```sql ```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: The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
@ -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. 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 ```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: The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
@ -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. 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 ```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: The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
@ -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. 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 ```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: The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
@ -283,13 +342,17 @@ tables and indexes.
To verify that a table is encrypted, run the following statement: To verify that a table is encrypted, run the following statement:
```sql ```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: You can also verify if the table in a custom schema is encrypted. Pass the schema name for the function as follows:
```sql ```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. This can additionally be used to verify that indexes and sequences are encrypted.
@ -299,7 +362,7 @@ 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. Displays information about the principal key for the current database, if it exists.
```sql ```sql
SELECT pg_tde_key_info() SELECT pg_tde_key_info();
``` ```
### pg_tde_server_key_info ### pg_tde_server_key_info
@ -307,7 +370,7 @@ SELECT pg_tde_key_info()
Displays information about the principal key for the server scope, if exists. Displays information about the principal key for the server scope, if exists.
```sql ```sql
SELECT pg_tde_server_key_info() SELECT pg_tde_server_key_info();
``` ```
### pg_tde_default_key_info ### pg_tde_default_key_info
@ -315,7 +378,7 @@ SELECT pg_tde_server_key_info()
Displays the information about the default principal key, if it exists. Displays the information about the default principal key, if it exists.
```sql ```sql
SELECT pg_tde_default_key_info() SELECT pg_tde_default_key_info();
``` ```
### pg_tde_verify_key ### pg_tde_verify_key
@ -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. If any of the above checks fail, the function reports an error.
```sql ```sql
SELECT pg_tde_verify_key() SELECT pg_tde_verify_key();
``` ```
### pg_tde_verify_server_key ### pg_tde_verify_server_key
@ -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. If any of the above checks fail, the function reports an error.
```sql ```sql
SELECT pg_tde_verify_server_key() SELECT pg_tde_verify_server_key();
``` ```
### pg_tde_verify_default_key ### pg_tde_verify_default_key
@ -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. If any of the above checks fail, the function reports an error.
```sql ```sql
SELECT pg_tde_verify_default_key() SELECT pg_tde_verify_default_key();
``` ```

Write Preview
Loading…
Cancel
Save