From 0713078ef848dc70388a9793cc89651d7dd15fee Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Fri, 8 Nov 2024 16:15:19 -0500 Subject: [PATCH 1/6] Edits to TDE refresh PR6130 --- .../1/tde.mdx | 54 +++++++++---------- product_docs/docs/tde/15/about/index.mdx | 2 +- product_docs/docs/tde/15/about/what.mdx | 4 +- product_docs/docs/tde/15/about/why.mdx | 14 ++--- .../tde/15/enabling/enabling_tde_epas.mdx | 30 +++++------ product_docs/docs/tde/15/initdb_tde.mdx | 10 ++-- .../docs/tde/15/initdb_tde_options.mdx | 10 ++-- product_docs/docs/tde/15/overview.mdx | 25 ++++----- .../docs/tde/15/secure_key/disabling_key.mdx | 2 +- product_docs/docs/tde/15/secure_key/index.mdx | 19 +++---- .../docs/tde/15/secure_key/key_rotation.mdx | 6 +-- .../docs/tde/15/secure_key/key_store.mdx | 6 +-- product_docs/docs/tde/15/upgrading.mdx | 4 +- 13 files changed, 90 insertions(+), 96 deletions(-) diff --git a/product_docs/docs/postgres_distributed_for_kubernetes/1/tde.mdx b/product_docs/docs/postgres_distributed_for_kubernetes/1/tde.mdx index 419f2fb90d8..9761e45ad00 100644 --- a/product_docs/docs/postgres_distributed_for_kubernetes/1/tde.mdx +++ b/product_docs/docs/postgres_distributed_for_kubernetes/1/tde.mdx @@ -1,45 +1,45 @@ --- -title: 'Transparent Data Encryption (TDE)' +title: 'Transparent data encryption (TDE)' originalFilePath: 'src/tde.md' --- !!! Important TDE is available *only* for operands that support it: - EPAS versions 15 and newer, Postgres Extended versions 15 and newer. + EDB Postgres Advanced Server versions 15 and newer and EDB Postgres Extended versions 15 and newer. -Transparent Data Encryption, or TDE, is a technology used by several database -vendors to **encrypt data at rest**, i.e. database files on disk. -TDE does not however encrypt data in use. +Transparent data encryption, or TDE, is a technology used by several database +vendors to encrypt data at rest, that is, database files on disk. +However, TDE doesn't encrypt data in use. -TDE is included in EDB Postgres Advanced Server (EPAS) or EDB Postgres -Extended, starting with version 15, and it is supported by EDB Postgres +TDE is included in EDB Postgres Advanced Server or EDB Postgres +Extended, starting with version 15, and is supported by EDB Postgres Distributed for Kubernetes. !!! Important - Before you proceed, please take some time to familiarize with the - [TDE feature in the EPAS documentation](https://www.enterprisedb.com/docs/tde/latest/). + Before you proceed, take some time to familiarize with the + [TDE feature in the EDB Postgres Advanced Server documentation](/tde/latest/). -With TDE activated, both WAL files and files for tables will be encrypted. -Data encryption/decryption is entirely transparent to the user, as it is +With TDE activated, both WAL files and files for tables are encrypted. +Data encryption/decryption is entirely transparent to the user, as it's managed by the database without requiring any application changes or updated client drivers. The support for TDE on EDB Postgres Distributed for Kubernetes relies on the -implementation from EDB Postgres for Kubernetes (PG4K). Please refer to -[the PG4K documentation](https://www.enterprisedb.com/docs/postgres_for_kubernetes/latest/tde/) +implementation from EDB Postgres for Kubernetes (PG4K). See +[the PG4K documentation](/postgres_for_kubernetes/latest/tde/) for the full context. -We show now how to use TDE with a passphrase stored in a Kubernetes Secret, -which will be used to encrypt the EPAS binary key. +You can use TDE with a passphrase stored in a Kubernetes secret, +which is used to encrypt the EDB Postgres Advanced Server binary key. -!!! Seealso "EPAS documentation" - Please refer to [the EPAS documentation](https://www.enterprisedb.com/docs/tde/latest/secure_key/) - for details on the EPAS encryption key. +!!! Seealso "EDB Postgres Advanced Server documentation" + See [the EDB Posgres Advanced Server documentation](/tde/latest/secure_key/) + for details on the this encryption key. TDE on EDB Postgres Distributed for Kubernetes relies on the PG4K implementation. -To activate TDE on a cluster, we use the `epas` section of the manifest, -which is within the `cnp` section used for PG4K-level directives such as +Activating TDE on a cluster uses the `epas` section of the manifest, +which is in the `cnp` section used for PG4K-level directives such as storage. Use the `tde` stanza to enable TDE, and set the name of the Kubernetes secret holding the TDE encryption key. @@ -75,27 +75,27 @@ spec: size: 1Gi ``` -Again, please refer to [the PG4K documentation](https://www.enterprisedb.com/docs/postgres_for_kubernetes/latest/tde/) +Again, see [the PG4K documentation](/postgres_for_kubernetes/latest/tde/) for additional depth, including how to create the encryption secret and additional ways of using TDE. -As shown in the [TDE feature documentation](https://www.enterprisedb.com/docs/tde/latest/), -the information will be encrypted at rest. +As shown in the [TDE feature documentation](/tde/latest/), +the information is encrypted at rest. -For example, open a `psql` terminal into one of your data nodes. +For example, open a psql terminal into one of your data nodes. ```sh kubectl exec -ti -- psql app ``` -and create a new table including a text column. +Create a new table including a text column: ```sql create table foo(bar int, baz varchar); insert into foo(bar, baz) values (1, 'hello'), (2, 'goodbye'); ``` -And then verify the location where the newly defined table is stored on disk: +Verify the location where the newly defined table is stored on disk: ```sql select pg_relation_filepath('foo'); @@ -110,7 +110,7 @@ You can open a terminal on the same data node: kubectl exec -ti -- bash ``` -and verify the file has been encrypted. +There, you can verify the file was encrypted: ```sh cd $PGDATA/base/16385 diff --git a/product_docs/docs/tde/15/about/index.mdx b/product_docs/docs/tde/15/about/index.mdx index 6bf65301b0d..b3e9aedbdd6 100644 --- a/product_docs/docs/tde/15/about/index.mdx +++ b/product_docs/docs/tde/15/about/index.mdx @@ -1,6 +1,6 @@ --- title: About TDE -description: Learn about TDE, how it works, what it encrypts and why to use it. +description: Learn about TDE, how it works, what it encrypts, and why to use it. indexCards: simple --- diff --git a/product_docs/docs/tde/15/about/what.mdx b/product_docs/docs/tde/15/about/what.mdx index e478cf5821b..93e2689c6c2 100644 --- a/product_docs/docs/tde/15/about/what.mdx +++ b/product_docs/docs/tde/15/about/what.mdx @@ -5,9 +5,9 @@ description: Which data is encrypted when databases are initialized with TDE? TDE encrypts: -- The files underlying tables, sequences, indexes, including TOAST tables and system catalogs, and including all forks. These files are known as *data files*. +- The files underlying tables, sequences, and indexes, including TOAST tables and system catalogs and all forks. These files are known as *data files*. -- The write-ahead log (WAL). +- The write-ahead log (WAL). - Various temporary files that are used during query processing and database system operation. diff --git a/product_docs/docs/tde/15/about/why.mdx b/product_docs/docs/tde/15/about/why.mdx index 67395d2c6da..2539b411d18 100644 --- a/product_docs/docs/tde/15/about/why.mdx +++ b/product_docs/docs/tde/15/about/why.mdx @@ -5,18 +5,18 @@ description: Learn about some of the use cases for TDE encryption. TDE encryption ensures that user data remains protected from unauthorized access. -When configured with a [data encryption key securing mechanism](../secure_key/), data stored on the database server and in backup is only accessible by users and processes with decryption keys. +When configured with a [data encryption key securing mechanism](../secure_key/), data stored on the database server and in backup is accessible only by users and processes with decryption keys. -Some use cases include: +Some use cases include: -- **Protection of sensitive personal data:** Industries like finance, e-commerce, healthcare, and government organizations often deal with personally identifiable information that must be protected to comply with data privacy regulations such as GDPR, HIPPA, PCI DSS. +- **Protection of sensitive personal data.** Industries like finance, e-commerce, healthcare, and government organizations often deal with personally identifiable information that must be protected to comply with data privacy regulations such as GDPR, HIPPA, and PCI DSS. -- **Compliance with government standards:** Government institutions must comply with information processing standards like FIPS to ensure computer security and interoperability. +- **Compliance with government standards.** Government institutions must comply with information processing standards like FIPS to ensure computer security and interoperability. -- **Protection of transactional data:** Financial institutions deal with transaction, account, and payment data that must be protected to prevent fraud and financial losses. +- **Protection of transactional data.** Financial institutions deal with transaction, account, and payment data that must be protected to prevent fraud and financial losses. -- **Protection of intellectual property:** Organizations safeguard proprietary information, designs, and plans to keep their competitive advantage, support brand value, and foster innovation. +- **Protection of intellectual property.** Organizations safeguard proprietary information, designs, and plans to keep their competitive advantage, support brand value, and foster innovation. -- **Protection of data in cloud-based deployments and public web applications:** Encrypting a database's data provides an additional layer of security when infrastructure is shared, or when vulnerabilities could potentially infiltrate in an application's API. +- **Protection of data in cloud-based deployments and public web applications.** Encrypting a database's data provides an added layer of security when infrastructure is shared or when vulnerabilities could potentially infiltrate in an application's API. When your data is encrypted, it becomes unintelligible if it's stolen or misplaced. \ No newline at end of file diff --git a/product_docs/docs/tde/15/enabling/enabling_tde_epas.mdx b/product_docs/docs/tde/15/enabling/enabling_tde_epas.mdx index 769cd2e69a2..7356ad7dbe7 100644 --- a/product_docs/docs/tde/15/enabling/enabling_tde_epas.mdx +++ b/product_docs/docs/tde/15/enabling/enabling_tde_epas.mdx @@ -10,27 +10,27 @@ Create a new EDB Postgres Advanced Server cluster with TDE enabled and use `pg_upgrade` to transfer data from the existing source cluster to the new encrypted cluster. - [Prepare your upgrade](#preparing-your-upgrade) by performing a backup of the existing instance. -- [Create a new database server](#creating-an-encrypted-server) +- [Create a new database server](#creating-an-encrypted-server): - Create an empty directory for the new server and ensure `enterprisedb` owns it. - Set the environment variables to export the `wrap` and `unwrap` commands for encryption. - Initialize a server with encryption enabled. - Change the default port, so the new server is available at another port. - Start the database server. - - Connect to the database server and ensure it is functioning. -- [Upgrade to the encrypted server](#upgrading-to-the-encrypted-server) + - Connect to the database server and ensure it's functioning. +- [Upgrade to the encrypted server](#upgrading-to-the-encrypted-server): - Stop both the source and the new server. - - Use `pg_upgrade` with `--copy-by-block` option to copy data from the source server to the new server. Specify the source and target bin and data directories. - - Start the new encrypted databaser server. - - Connect to the encrypted database server and ensure the data was transfered. -- [Clean up and delete the source server](#cleaning-up-after-upgrade) + - Use `pg_upgrade` with the `--copy-by-block` option to copy data from the source server to the new server. Specify the source and target bin and data directories. + - Start the new encrypted database server. + - Connect to the encrypted database server and ensure the data was transferred. +- [Clean up and delete the source server](#cleaning-up-after-upgrade): - Clean up the database and its statistics. - - Remove the source EDB Postgres Advanced Server cluster with the script provided by `pg_upgrade`. + - Remove the source EDB Postgres Advanced Server cluster with the script provided by pg_upgrade. ## Worked example -This example enables Transparent Data Encryption on an EDB Postgres Advanced Server version 16 running on an Ubuntu 22.04 machine. +This example enables transparent data encryption on EDB Postgres Advanced Server version 16 running on an Ubuntu 22.04 machine. -A similar workflow applies to other versions of EDB Postgres Advanced Server and EDB Postgres Extended Server. Note that the location of the BIN and CONFIG directories differs depending on your operating system and the Postgres version. +A similar workflow applies to other versions of EDB Postgres Advanced Server and EDB Postgres Extended Server. The location of the bin and config directories differs depending on your operating system and the Postgres version. ### Preparing your upgrade @@ -44,7 +44,7 @@ Use [pg_dumpall](https://www.postgresql.org/docs/current/app-pg-dumpall.html), [ mkdir /var/lib/edb-as/16/TDE ``` -1. Ensure the `enterprisedb` user owns the directory: +1. Ensure the enterprisedb user owns the directory: ``` sudo chown enterprisedb /var/lib/edb-as/16/TDE @@ -69,7 +69,7 @@ Use [pg_dumpall](https://www.postgresql.org/docs/current/app-pg-dumpall.html), [ /usr/lib/edb-as/16/bin/initdb --data-encryption -D /var/lib/edb-as/16/TDE ``` - This command initializes a CONFIG directory with all configuration files for the encrypted server. + This command initializes a config directory with all configuration files for the encrypted server. 1. Modify the port number in the configuration file of the encrypted instance. Uncomment the line with `#port` and change the port number. For example: @@ -90,7 +90,7 @@ Use [pg_dumpall](https://www.postgresql.org/docs/current/app-pg-dumpall.html), [ ``` !!!note - If you're using two different Postgres versions, use the psql utility of the encrypted server. Otherwise, the system will attempt to use psql from the previous instance. + If you're using two different Postgres versions, use the psql utility of the encrypted server. Otherwise, the system attempts to use psql from the previous instance. 1. To ensure the new server is encrypted, [check for TDE presence](verifying_tde). @@ -148,7 +148,7 @@ Use [pg_dumpall](https://www.postgresql.org/docs/current/app-pg-dumpall.html), [ ### Cleaning up after upgrade -After you verify that `pg_upgrade` encrypted the data successfully, perform a cleanup. +After you verify that pg_upgrade encrypted the data successfully, perform a cleanup. 1. Clean up the database and its statistics: @@ -156,7 +156,7 @@ After you verify that `pg_upgrade` encrypted the data successfully, perform a cl /usr/lib/edb-as/16/bin/vacuumdb --all --analyze-in-stages ``` -1. Remove all data files of the unencrypted server with the script generated by `pg_upgrade`: +1. Remove all data files of the unencrypted server with the script generated by pg_upgrade: ``` ./delete_old_cluster.sh diff --git a/product_docs/docs/tde/15/initdb_tde.mdx b/product_docs/docs/tde/15/initdb_tde.mdx index 19a306435c7..0a96aa3c614 100644 --- a/product_docs/docs/tde/15/initdb_tde.mdx +++ b/product_docs/docs/tde/15/initdb_tde.mdx @@ -9,16 +9,16 @@ Initializing a TDE-enabled server requires two mandatory settings: one enables T To create a TDE-enabled database server, you must use the [`--data-encryption` option](initdb_tde_options/#option---data-encryption-or--y), which creates a data encryption key to encrypt your server. -If you want to copy a key from an existing cluster when preparing a new cluster as a target for pg_upgrade, additionally use the [`--copy-key-from=` option](initdb_tde_options/#option---copy-key-fromfile). +If you want to copy a key from an existing cluster when preparing a new cluster as a target for pg_upgrade, also use the [`--copy-key-from=` option](initdb_tde_options/#option---copy-key-fromfile). ## To protect the data encryption key -When creating a TDE-enabled database, TDE generates a data encryption key that is transparent to the user. +When creating a TDE-enabled database, TDE generates a data encryption key that's transparent to the user. -An additional protection mechanism in the form or a wrapping and an unwrapping command is required to wrap this key, which you must make available to the database server. +An added protection mechanism in the form or a wrapping and an unwrapping command is required to wrap this key, which you must make available to the database server. -See [Providing the wrapping and unwrapping commands to TDE](secure_key) for an overview of the available protection mechanism, and examples of how to provide this configuration to `initdb`. +See [Providing the wrapping and unwrapping commands to TDE](secure_key) for an overview of the available protection mechanism and examples of how to provide this configuration to `initdb`. ## Options reference -See [initdb TDE options](initdb_tde_options) for an overview of all mandatory and elective options and supported values. \ No newline at end of file +See [initdb TDE options](initdb_tde_options) for an overview of all mandatory and elective options and supported values. \ No newline at end of file diff --git a/product_docs/docs/tde/15/initdb_tde_options.mdx b/product_docs/docs/tde/15/initdb_tde_options.mdx index 785fdae0914..1f51008a641 100644 --- a/product_docs/docs/tde/15/initdb_tde_options.mdx +++ b/product_docs/docs/tde/15/initdb_tde_options.mdx @@ -21,9 +21,9 @@ Provides the wrapping/encryption command to protect the data encryption key. `` is customizable, but it must contain the placeholder `%p`. See [Wrapping commands](secure_key/#configuring-a-wrapping-and-unwrapping-command) for examples and information. See [Securing the data encryption key](secure_key) for an overview of available wrapping mechanisms. -If not specified, TDE falls back on the environment variable `PGDATAKEYWRAPCMD`. +If you don't specify a command, TDE falls back on the environment variable `PGDATAKEYWRAPCMD`. -Use `-` if you don't want to apply a wrapping mechanism. +If you don't want to apply a wrapping mechanism, Use `-`. ## Option: `--key-unwrap-command=` @@ -33,9 +33,9 @@ Provides the unwrapping/decryption command to access the data encryption key. `` is customizable, but it must contain the placeholder `%p`. See [Configuring wrapping commands](secure_key/#configuring-a-wrapping-and-unwrapping-command) for examples and information. -If not specified, TDE falls back on the environment variable `PGDATAKEYUNWRAPCMD`. +If you don't specify a command, TDE falls back on the environment variable `PGDATAKEYUNWRAPCMD`. -Use `-` if you didn't apply a wrapping mechanism. +If you didn't apply a wrapping mechanism, use `-` . ## Option: `--no-key-wrap` @@ -53,7 +53,7 @@ The `--no-key-wrap` option doesn't require specifying any values. ## Option: `--copy-key-from=` -Copies an existing data encryption key from the provided location. For example, when reusing a key from an existing server during an upgrade with pg_upgrade. +Copies an existing data encryption key from the provided location, for example, when reusing a key from an existing server during an upgrade with pg_upgrade. ### Supported values diff --git a/product_docs/docs/tde/15/overview.mdx b/product_docs/docs/tde/15/overview.mdx index b99f543cbf2..9e41aacb4a1 100644 --- a/product_docs/docs/tde/15/overview.mdx +++ b/product_docs/docs/tde/15/overview.mdx @@ -6,19 +6,19 @@ redirects: - /tde/latest/enabling_tde/ --- -If you want to start using Transparent Data Encryption (TDE) on your database, you either want to create a new TDE-enabled database server, or you want to migrate an existing database server to a TDE-enabled environment. It is not possible to enable TDE on existing instances. +If you want to start using transparent data encryption (TDE) on your database, you want to either create a TDE-enabled database server or migrate an existing database server to a TDE-enabled environment. It isn't possible to enable TDE on existing instances. -Regardless of whether you are creating a database server from scratch, or creating a new instance to migrate an existing database server, you have to create a TDE-enabled database by initializing a database cluster using [initdb](https://www.postgresql.org/docs/15/app-initdb.html). +Regardless of whether you're creating a database server from scratch or creating an instance to migrate an existing database server, you have to create a TDE-enabled database by initializing a database cluster using [initdb](https://www.postgresql.org/docs/15/app-initdb.html). ## Before you begin - Choose a method to [secure the data encryption key](secure_key) generated by TDE. - You can protect they key with a [passphrase](./secure_key/passphrase/), a wrapping key from a [key store](secure_key/key_store/) or choose [not protect the key](secure_key/disabling_key/) for testing purposes. + You can protect they key with a [passphrase](./secure_key/passphrase/) or a wrapping key from a [key store](secure_key/key_store/). Or you can choose to [not protect the key](secure_key/disabling_key/) for testing purposes. -- Review the [initdb TDE options](./initdb_tde_options/) to ensure you have all information required for the initialization of a TDE-enabled database cluster. +- Review the [initdb TDE options](./initdb_tde_options/) to ensure you have all information required for initializing a TDE-enabled database cluster. -- Review the [Limitations and TDE-specific options](./limitations/) to understand limitations and changes in the handling of PostgreSQL utilities when you enable TDE. +- Review [Limitations and TDE-specific options](./limitations/) to understand limitations and changes in the handling of PostgreSQL utilities when you enable TDE. - If you plan on migrating data from an existing database server, ensure you perform a backup of the source database server. @@ -38,15 +38,15 @@ See [Tutorials](#tutorials) for detailed initialization examples. ## Migrating data (for existing instances) -If you want to migrate data and objects from an existing database server, use `pg_upgrade` to copy data from an exiting instance: +If you want to migrate data and objects from an existing database server, use pg_upgrade to copy data from an existing instance. 1. Stop both the source and new server. -1. Use `pg_upgrade` with `--copy-by-block` option to copy data from the source server to the new server. Include other [TDE pg_upgrade options](pg_upgrade_arguments) as required. +1. Use pg_upgrade with the `--copy-by-block` option to copy data from the source server to the new server. Include other [TDE pg_upgrade options](pg_upgrade_arguments) as required. 1. Start the new encrypted database server. -1. Connect to the encrypted database server and ensure the data was transfered. +1. Connect to the encrypted database server and ensure the data was transferred. 1. Perform any required cleanup operations. @@ -58,9 +58,6 @@ See [Tutorials](#tutorials) for detailed migration examples. ## Tutorials -* [Creating a TDE-enabled database server](enabling/enabling_tde/). -* [Enabling TDE on an existing EDB Postgres Advanced Server database cluster](enabling/enabling_tde_epas/). -* [Upgrading a PostgreSQL database server to EDB Postgres Extended Server while enabling TDE](enabling/postgres_to_extended/). - - - +* [Creating a TDE-enabled database server](enabling/enabling_tde/) +* [Enabling TDE on an existing EDB Postgres Advanced Server database cluster](enabling/enabling_tde_epas/) +* [Upgrading a PostgreSQL database server to EDB Postgres Extended Server while enabling TDE](enabling/postgres_to_extended/) diff --git a/product_docs/docs/tde/15/secure_key/disabling_key.mdx b/product_docs/docs/tde/15/secure_key/disabling_key.mdx index 46c960241b1..a9f2d875b71 100644 --- a/product_docs/docs/tde/15/secure_key/disabling_key.mdx +++ b/product_docs/docs/tde/15/secure_key/disabling_key.mdx @@ -6,4 +6,4 @@ deepToc: true If you don't want key wrapping, for example for testing, then you must set the wrap and unwrap commands to the special value `-`. -This setting specifies to use the key from the file without further processing. This approach differs from not setting a wrap or unwrap command at all, and from setting either/both to an empty string. Having no wrap or unwrap command set when transparent data encryption is used leaves your data encryption key unsecured, and results in a fatal error when running an affected utility program. +This setting specifies to use the key from the file without further processing. This approach differs from not setting a wrap or unwrap command at all and from setting either/both to an empty string. Having no wrap or unwrap command set when transparent data encryption is used leaves your data encryption key unsecured and results in a fatal error when running an affected utility program. diff --git a/product_docs/docs/tde/15/secure_key/index.mdx b/product_docs/docs/tde/15/secure_key/index.mdx index 65627758901..4eb1a30238c 100644 --- a/product_docs/docs/tde/15/secure_key/index.mdx +++ b/product_docs/docs/tde/15/secure_key/index.mdx @@ -13,27 +13,27 @@ redirects: ## Data encryption key -The key for transparent data encryption (the data key) is generated by `initdb` and stored in a file `pg_encryption/key.bin` under the data directory. This file actually contains several keys that are used for different purposes at run time. The data key is a single sequence of random bytes in the file. +The key for transparent data encryption (the data key) is generated by `initdb` and stored in a file `pg_encryption/key.bin` under the data directory. This file actually contains several keys that are used for different purposes at runtime. The data key is a single sequence of random bytes in the file. Without any further action, this file contains the key in plaintext, which isn't secure. Anyone with access to the encrypted data directory has access to the plaintext key, which defeats the purpose of encryption. ## Choosing a mechanism to protect the data encryption key -To secure the data encryption key, you must specify a wrap and a unwrap command that provides TDE with a data encryption protection mechanism. You can set this parameter only at server start. +To secure the data encryption key, you must specify a wrap and an unwrap command that provides TDE with a data encryption protection mechanism. You can set this parameter only at server start. With the wrap and unwrap commands you can: - [Protect the data key with a passphrase](passphrase). A wrapping key is derived from the passphrase and used to encrypt the data key. -- [Protect the data key with a wrapping key stored in a Key Management System](key_store) or key store. This second key is also called the *key-wrapping key* or *master key*. +- [Protect the data key with a wrapping key stored in a key management system](key_store) or key store. This second key is also called the *key-wrapping key* or *master key*. -- You can also choose to [Disable the data encryption key wrapping](disabling_key). Do this only for test environments, as it leaves the TDE key unprotected. +- You can also choose to [disable the data encryption key wrapping](disabling_key). Do this only for test environments, as it leaves the TDE key unprotected. ## Configuring a wrapping and unwrapping command -After you have chosen a method to protect your key, you can create the wrapping/unwrapping commands. The configuration of these commands is left to the user, which allows tailoring the setup to local requirements and integrating with existing key management software or similar. - -The [Using a passphrase](passphrase) topic provides an example for wrapping/unwrapping commands using OpenSSL and a passphrase to secure the TDE data key. The [Using a key store](key_store) topic provides an example for wrapping/unwrapping commands using an external key store key to protect the TDE data key. +After you choose a method to protect your key, you can create the wrapping/unwrapping commands. The configuration of these commands is left to the user, which allows you to tailor the setup to local requirements and integrate with existing key management software or similar. + +[Using a passphrase](passphrase) provides an example for wrapping/unwrapping commands using OpenSSL and a passphrase to secure the TDE data key. [Using a key store](key_store) provides an example for wrapping/unwrapping commands using an external key store key to protect the TDE data key. When you initialize a server with TDE, the `initdb` command adds the `data_encryption_key_unwrap_command` parameter in the `postgresql.conf` configuration file. The string specified in `data_encryption_key_unwrap_command` is then able to unwrap (decrypt) the data encryption key. @@ -69,7 +69,7 @@ You must make the commands available to the TDE database server so it can wrap a
-- You can disable the protection of your data encryption key with `--no-key-wrap`. This leaves your key unprotected and is recommended for testing proposes only. +- You can disable the protection of your data encryption key with `--no-key-wrap`. Doing so leaves your key unprotected and we recommend it only for testing proposes.
Example @@ -79,6 +79,3 @@ You must make the commands available to the TDE database server so it can wrap a

- - - diff --git a/product_docs/docs/tde/15/secure_key/key_rotation.mdx b/product_docs/docs/tde/15/secure_key/key_rotation.mdx index f3d2968ae2d..197d5997688 100644 --- a/product_docs/docs/tde/15/secure_key/key_rotation.mdx +++ b/product_docs/docs/tde/15/secure_key/key_rotation.mdx @@ -4,7 +4,7 @@ description: Learn how to rotate your data encryption key. deepToc: true --- -To change the master key, manually run the unwrap command specifying the old key. Then feed the result into the wrap command specifying the new key. Equivalently, if the data key is protected by a passphrase, to change the passphrase, run the unwrap command using the old passphrase. Then feed the result into the wrap command using the new passphrase. You can perform these operations while the database server is running. The wrapped data key in the file is used only on startup. It isn't used while the server is running. +To change the master key, manually run the unwrap command, specifying the old key. Then feed the result into the wrap command specifying the new key. Equivalently, if the data key is protected by a passphrase, to change the passphrase, run the unwrap command using the old passphrase. Then feed the result into the wrap command using the new passphrase. You can perform these operations while the database server is running. The wrapped data key in the file is used only on startup. It isn't used while the server is running. ## Rotating the passphrase @@ -15,14 +15,14 @@ cd $PGDATA/pg_encryption/ openssl enc -d -aes-128-cbc -pbkdf2 -in key.bin | openssl enc -e -aes-128-cbc -pbkdf2 -out key.bin.new mv key.bin.new key.bin ``` -With this method, the decryption and the encryption commands ask for the passphrase on the terminal at the same time, which is awkward and confusing. An alternative is: +With this method, the decryption and the encryption commands ask for the passphrase on the terminal at the same time, which is awkward and confusing. An alternative is: ```shell cd $PGDATA/pg_encryption/ openssl enc -d -aes-128-cbc -pbkdf2 -in key.bin -pass pass:ACTUALPASSPHRASE | openssl enc -e -aes-128-cbc -pbkdf2 -out key.bin.new mv key.bin.new key.bin ``` -This technique leaks the old passphrase, which is being replaced anyway. openssl supports a number of other ways to supply the passphrases. +This technique leaks the old passphrase, which is being replaced anyway. OpenSSL supports a number of other ways to supply the passphrases. ## Rotating the key store wrapping key diff --git a/product_docs/docs/tde/15/secure_key/key_store.mdx b/product_docs/docs/tde/15/secure_key/key_store.mdx index 7fedbfe96c7..55396044979 100644 --- a/product_docs/docs/tde/15/secure_key/key_store.mdx +++ b/product_docs/docs/tde/15/secure_key/key_store.mdx @@ -32,7 +32,7 @@ PGDATAKEYWRAPCMD='aws kms encrypt --key-id alias/pg-tde-master-1 --plaintext fil PGDATAKEYUNWRAPCMD='aws kms decrypt --key-id alias/pg-tde-master-1 --ciphertext-blob fileb://"%p" --output text --query Plaintext | base64 -d' ``` !!! Note - Shell commands with pipes, as in this example, are problematic because the exit status of the pipe is that of the last command. A failure of the first, more interesting command isn't reported properly. Postgres handles this somewhat by recognizing whether the wrap or unwrap command wrote nothing. However, it's better to make this more robust. For example, use the `pipefail` option available in some shells or the `mispipe` command available on some operating systems. Put more complicated commands into an external shell script or other program instead of defining them inline. + Shell commands with pipes, as in this example, are problematic because the exit status of the pipe is that of the last command. A failure of the first, more interesting command isn't reported properly. Postgres handles this somewhat by recognizing whether the wrap or unwrap command wrote nothing. However, it's better to make this command more robust. For example, use the `pipefail` option available in some shells or the `mispipe` command available on some operating systems. Put more complicated commands into an external shell script or other program instead of defining them inline. ## Azure Key Vault example @@ -49,7 +49,7 @@ PGDATAKEYWRAPCMD='az keyvault key encrypt --name pg-tde-master-1 --vault-name pg PGDATAKEYUNWRAPCMD='az keyvault key decrypt --name pg-tde-master-1 --vault-name pg-tde --algorithm A256GCM --value @"%p" --data-type plaintext --only-show-errors --output json | jq -r .result' ``` !!! Note - Shell commands with pipes, as in this example, are problematic because the exit status of the pipe is that of the last command. A failure of the first, more interesting command isn't reported properly. Postgres handles this somewhat by recognizing whether the wrap or unwrap command wrote nothing. However, it's better to make this more robust. For example, use the `pipefail` option available in some shells or the `mispipe` command available on some operating systems. Put more complicated commands into an external shell script or other program instead of defining them inline. + Shell commands with pipes, as in this example, are problematic because the exit status of the pipe is that of the last command. A failure of the first, more interesting command isn't reported properly. Postgres handles this somewhat by recognizing whether the wrap or unwrap command wrote nothing. However, it's better to make this command more robust. For example, use the `pipefail` option available in some shells or the `mispipe` command available on some operating systems. Put more complicated commands into an external shell script or other program instead of defining them inline. ## Google Cloud KMS example @@ -89,7 +89,7 @@ PGDATAKEYUNWRAPCMD='vault write -field=plaintext transit/decrypt/pg-tde-master-1 ## Thales CipherTrust Manager example -See the [Using](/partner_docs/ThalesCipherTrustManager/05-UsingThalesCipherTrustManager/) section of the [Implementing Thales CipherTrust Manager](/partner_docs/ThalesCipherTrustManager/) documentation for instructions how to wrap the data encryption key with a key from the Thales key store. +See [Using](/partner_docs/ThalesCipherTrustManager/05-UsingThalesCipherTrustManager/) in the [Implementing Thales CipherTrust Manager](/partner_docs/ThalesCipherTrustManager/) documentation for instructions on how to wrap the data encryption key with a key from the Thales key store. ## Fortanix Data Security Manager example diff --git a/product_docs/docs/tde/15/upgrading.mdx b/product_docs/docs/tde/15/upgrading.mdx index 08fca739777..8ebb77df0a4 100644 --- a/product_docs/docs/tde/15/upgrading.mdx +++ b/product_docs/docs/tde/15/upgrading.mdx @@ -6,7 +6,7 @@ redirects: - /tde/latest/upgrade_use_cases/ #generated for TDE/refresh --- -You can use the [pg_upgrade](https://www.postgresql.org/docs/current/pgupgrade.html) with additional TDE-arguments to perform a number of upgrading and migrating operations. +You can use [pg_upgrade](https://www.postgresql.org/docs/current/pgupgrade.html) with additional TDE arguments to perform upgrading and migrating operations. This table provides an overview of supported use cases. | Use case | Source unencrypted server | Target encrypted server | @@ -17,7 +17,7 @@ This table provides an overview of supported use cases. | Maintain the Postgres distribution and rotate encryption keys | Encrypted EDB Postgres Advanced Server 15 | Encrypted EDB Postgres Advanced Server 15 with new encryption keys | !!! Important - Both source and target servers must be in the same Postgres major version. `pg_upgrade` only supports upgrades between minor versions. + Both source and target servers must be in the same Postgres major version. pg_upgrade only supports upgrades between minor versions. ## Tutorials From b885d551f2629d74964e2a8310519dad230d7c1b Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Mon, 11 Nov 2024 12:37:04 -0500 Subject: [PATCH 2/6] Edits to TDE refresh #6130 --- product_docs/docs/tde/15/about/index.mdx | 2 +- product_docs/docs/tde/15/about/what.mdx | 4 ++-- product_docs/docs/tde/15/about/why.mdx | 8 ++++---- product_docs/docs/tde/15/affected_commands.mdx | 2 +- .../docs/tde/15/enabling/enabling_tde.mdx | 8 ++++---- .../docs/tde/15/enabling/enabling_tde_epas.mdx | 16 ++++++++-------- product_docs/docs/tde/15/enabling/index.mdx | 2 +- .../tde/15/enabling/postgres_to_extended.mdx | 8 ++++---- product_docs/docs/tde/15/initdb_tde_options.mdx | 2 +- product_docs/docs/tde/15/overview.mdx | 6 +++--- .../docs/tde/15/secure_key/disabling_key.mdx | 4 ++-- product_docs/docs/tde/15/secure_key/index.mdx | 16 ++++++++-------- .../docs/tde/15/secure_key/key_rotation.mdx | 10 +++++++--- .../docs/tde/15/secure_key/passphrase.mdx | 5 ++--- product_docs/docs/tde/15/upgrading.mdx | 3 ++- 15 files changed, 50 insertions(+), 46 deletions(-) diff --git a/product_docs/docs/tde/15/about/index.mdx b/product_docs/docs/tde/15/about/index.mdx index b3e9aedbdd6..041ff148827 100644 --- a/product_docs/docs/tde/15/about/index.mdx +++ b/product_docs/docs/tde/15/about/index.mdx @@ -4,6 +4,6 @@ description: Learn about TDE, how it works, what it encrypts, and why to use it. indexCards: simple --- -Transparent data encryption (TDE) is an optional feature supported by EDB Postgres Advanced Server and EDB Postgres Extended Server from version 15. +Transparent data encryption (TDE) is an optional feature supported by EDB Postgres Advanced Server and EDB Postgres Extended Server in version 15 and later. It encrypts user data stored in the database system. \ No newline at end of file diff --git a/product_docs/docs/tde/15/about/what.mdx b/product_docs/docs/tde/15/about/what.mdx index 93e2689c6c2..dcf012a9a29 100644 --- a/product_docs/docs/tde/15/about/what.mdx +++ b/product_docs/docs/tde/15/about/what.mdx @@ -17,14 +17,14 @@ TDE encrypts: - A physical replica is necessarily encrypted (or not encrypted) in the same way and using the same keys as its primary server. - - If a server uses TDE, a base backup is automatically encrypted. + - If a server uses TDE, a base backup is encrypted. The following aren't encrypted or otherwise disguised by TDE: - Metadata internal to operating the database system that doesn't contain user data, such as the transaction status (for example, pg_subtrans and pg_xact). -- The file names and file system structure in the data directory. That means that the overall size of the database system, the number of databases, the number of tables, their relative sizes, as well as file system metadata such as last access time are all visible without decryption. +- The file names and file system structure in the data directory. That means that the overall size of the database system, the number of databases, the number of tables, their relative sizes, as well as file system metadata, such as last access time, are all visible without decryption. - Data in foreign tables. diff --git a/product_docs/docs/tde/15/about/why.mdx b/product_docs/docs/tde/15/about/why.mdx index 2539b411d18..24d2e36cd4f 100644 --- a/product_docs/docs/tde/15/about/why.mdx +++ b/product_docs/docs/tde/15/about/why.mdx @@ -9,14 +9,14 @@ When configured with a [data encryption key securing mechanism](../secure_key/), Some use cases include: -- **Protection of sensitive personal data.** Industries like finance, e-commerce, healthcare, and government organizations often deal with personally identifiable information that must be protected to comply with data privacy regulations such as GDPR, HIPPA, and PCI DSS. +- **Protection of sensitive personal data.** Industries like finance, e-commerce, healthcare, and government organizations often deal with personally identifiable information that must be protected to comply with data privacy regulations such as GDPR, HIPAA, and PCI DSS. - **Compliance with government standards.** Government institutions must comply with information processing standards like FIPS to ensure computer security and interoperability. -- **Protection of transactional data.** Financial institutions deal with transaction, account, and payment data that must be protected to prevent fraud and financial losses. +- **Protecting transactional data.** Financial institutions deal with transaction, account, and payment data that must be protected to prevent fraud and financial losses. -- **Protection of intellectual property.** Organizations safeguard proprietary information, designs, and plans to keep their competitive advantage, support brand value, and foster innovation. +- **Protecting intellectual property.** Organizations safeguard proprietary information, designs, and plans to keep their competitive advantage, support brand value, and foster innovation. -- **Protection of data in cloud-based deployments and public web applications.** Encrypting a database's data provides an added layer of security when infrastructure is shared or when vulnerabilities could potentially infiltrate in an application's API. +- **Protecting data in cloud-based deployments and public web applications.** Encrypting a database's data provides an added layer of security when infrastructure is shared or when vulnerabilities could potentially infiltrate in an application's API. When your data is encrypted, it becomes unintelligible if it's stolen or misplaced. \ No newline at end of file diff --git a/product_docs/docs/tde/15/affected_commands.mdx b/product_docs/docs/tde/15/affected_commands.mdx index 197c2ccf2ed..0da108edb2f 100644 --- a/product_docs/docs/tde/15/affected_commands.mdx +++ b/product_docs/docs/tde/15/affected_commands.mdx @@ -1,6 +1,6 @@ --- title: "Commands affected by TDE" -description: Some commands work differently when TDE is enabled. Learn about differences. +description: How TDE changes the behavior of some commands when enabled. --- When TDE is enabled, the following commands have TDE-specific options or read TDE settings in environment variables or configuration files: diff --git a/product_docs/docs/tde/15/enabling/enabling_tde.mdx b/product_docs/docs/tde/15/enabling/enabling_tde.mdx index 0f698e507cc..42d7d4dbdcf 100644 --- a/product_docs/docs/tde/15/enabling/enabling_tde.mdx +++ b/product_docs/docs/tde/15/enabling/enabling_tde.mdx @@ -12,7 +12,7 @@ Create a new EDB Postgres Advanced Server cluster with TDE enabled. ## Worked example -This example uses EDB Postgres Advanced Server 15 running on a Linux platform. It uses openssl to define the passphrase to wrap and unwrap the generated data encryption key. +This example uses EDB Postgres Advanced Server 15 running on a Linux platform. It uses OpenSSL to define the passphrase to wrap and unwrap the generated data encryption key. 1. Set the data encryption key (wrap) and decryption (unwrap) environment variables: @@ -21,12 +21,12 @@ This example uses EDB Postgres Advanced Server 15 running on a Linux platform. I export PGDATAKEYUNWRAPCMD='openssl enc -d -aes-128-cbc -pass pass:ok -in %p' ``` !!!note - - If you are on Windows you don't need the single quotes around the variable value. + - If you're on Windows, you don't need the single quotes around the variable value. - Ensure you replace `ok` with the passphrase you want to use to wrap the data encryption key. !!! -1. Initialize the cluster using `initdb` with encryption enabled. This command sets the `data_encryption_key_unwrap_command` parameter in the postgresql.conf file. +1. Initialize the cluster using `initdb` with encryption enabled. This command sets the `data_encryption_key_unwrap_command` parameter in the `postgresql.conf` file. ```shell /usr/edb/as15/bin/initdb --data-encryption -D /var/lib/edb/as15/data @@ -38,7 +38,7 @@ This example uses EDB Postgres Advanced Server 15 running on a Linux platform. I /usr/edb/as15/bin/pg_ctl -D /var/lib/edb/as15/data start ``` -1. Run grep on postgresql.conf to verify the setting of `data_encryption_key_unwrap_command`: +1. Run grep on `postgresql.conf` to verify the setting of `data_encryption_key_unwrap_command`: ```shell grep data_encryption_key_unwrap_command /var/lib/edb/as15/data/postgresql.conf diff --git a/product_docs/docs/tde/15/enabling/enabling_tde_epas.mdx b/product_docs/docs/tde/15/enabling/enabling_tde_epas.mdx index 7356ad7dbe7..612ef802116 100644 --- a/product_docs/docs/tde/15/enabling/enabling_tde_epas.mdx +++ b/product_docs/docs/tde/15/enabling/enabling_tde_epas.mdx @@ -1,25 +1,25 @@ --- -title: "Enabling TDE on an existing EDB Postgres Advanced Server" -description: Migrate your existing EDB Postgres Advanced Server to a new TDE-enabled database server. +title: "Enabling TDE on an existing EDB Postgres Advanced Server cluster" +description: Migrate your existing EDB Postgres Advanced Server cluster to a new TDE-enabled database server. deepToC: true redirects: - /tde/latest/enabling_tde_epas/ #generated for TDE/refresh --- -Create a new EDB Postgres Advanced Server cluster with TDE enabled -and use `pg_upgrade` to transfer data from the existing source cluster to the new encrypted cluster. +Create an EDB Postgres Advanced Server cluster with TDE enabled +and use pg_upgrade to transfer data from the existing source cluster to the new encrypted cluster. - [Prepare your upgrade](#preparing-your-upgrade) by performing a backup of the existing instance. - [Create a new database server](#creating-an-encrypted-server): - - Create an empty directory for the new server and ensure `enterprisedb` owns it. + - Create an empty directory for the new server and ensure enterprisedb owns it. - Set the environment variables to export the `wrap` and `unwrap` commands for encryption. - Initialize a server with encryption enabled. - - Change the default port, so the new server is available at another port. + - Change the default port so the new server is available at another port. - Start the database server. - Connect to the database server and ensure it's functioning. - [Upgrade to the encrypted server](#upgrading-to-the-encrypted-server): - Stop both the source and the new server. - - Use `pg_upgrade` with the `--copy-by-block` option to copy data from the source server to the new server. Specify the source and target bin and data directories. + - Use pg_upgrade with the `--copy-by-block` option to copy data from the source server to the new server. Specify the source and target bin and data directories. - Start the new encrypted database server. - Connect to the encrypted database server and ensure the data was transferred. - [Clean up and delete the source server](#cleaning-up-after-upgrade): @@ -90,7 +90,7 @@ Use [pg_dumpall](https://www.postgresql.org/docs/current/app-pg-dumpall.html), [ ``` !!!note - If you're using two different Postgres versions, use the psql utility of the encrypted server. Otherwise, the system attempts to use psql from the previous instance. + If you're using two different Postgres versions, use the psql utility of the encrypted server. Otherwise, the system will attempt to use psql from the previous instance. 1. To ensure the new server is encrypted, [check for TDE presence](verifying_tde). diff --git a/product_docs/docs/tde/15/enabling/index.mdx b/product_docs/docs/tde/15/enabling/index.mdx index 19f76c0cab8..7724197b18a 100644 --- a/product_docs/docs/tde/15/enabling/index.mdx +++ b/product_docs/docs/tde/15/enabling/index.mdx @@ -9,4 +9,4 @@ navigation: Create a TDE-enabled database server using `initdb`. -Or migrate an existing database instance by creating a TDE-enabled database server with `initdb` and then migrating data with `pg_upgrade`. \ No newline at end of file +Or migrate an existing database instance by creating a TDE-enabled database server with `initdb` and then migrating data with pg_upgrade. \ No newline at end of file diff --git a/product_docs/docs/tde/15/enabling/postgres_to_extended.mdx b/product_docs/docs/tde/15/enabling/postgres_to_extended.mdx index eee6d07c9ab..7a5f7ae65b3 100644 --- a/product_docs/docs/tde/15/enabling/postgres_to_extended.mdx +++ b/product_docs/docs/tde/15/enabling/postgres_to_extended.mdx @@ -10,25 +10,25 @@ redirects: Create a new EDB Postgres Extended Server cluster with TDE enabled and use pg_upgrade to transfer data from the existing PostgreSQL cluster to the new encrypted cluster. - [Prepare your upgrade](#preparing-your-upgrade) by performing a backup of the existing instance. -- [Create a new database server](#creating-an-encrypted-server). +- [Create a new database server](#creating-an-encrypted-server): - Create an empty directory for the new server and ensure the postgres user owns it. - Set the environment variables to export the `wrap` and `unwrap` commands for encryption. - Initialize a server with encryption enabled. - Change the default port so the new server is available at another port. - Start the database server. - Connect to the database server and ensure it's functioning. -- [Upgrade to the encrypted server](#upgrading-to-the-encrypted-server). +- [Upgrade to the encrypted server](#upgrading-to-the-encrypted-server): - Stop both the source and the new server. - Use pg_upgrade with the `--copy-by-block` option to copy data from the source server to the new server. Specify the source and target bin and data directories. - Start the new encrypted database server. - Connect to the encrypted database server and ensure the data was transferred. -- [Clean up and delete the source server](#cleaning-up-after-upgrade). +- [Clean up and delete the source server](#cleaning-up-after-upgrade): - Clean up the database and its statistics. - Remove the source PostgreSQL cluster with the script provided by pg_upgrade. ## Worked example -This example upgrades a PostgreSQL 16 instance to EDB Postgres Extended Server 16 while enabling Transparent Data Encryption on an Ubuntu 22.04 machine. The location of the bin and config directories differs depending on your operating system and Postgres versions. +This example upgrades a PostgreSQL 16 instance to EDB Postgres Extended Server 16 while enabling transparent data encryption on an Ubuntu 22.04 machine. The location of the bin and config directories differs depending on your operating system and Postgres versions. ### Preparing your upgrade diff --git a/product_docs/docs/tde/15/initdb_tde_options.mdx b/product_docs/docs/tde/15/initdb_tde_options.mdx index 1f51008a641..69261bbce15 100644 --- a/product_docs/docs/tde/15/initdb_tde_options.mdx +++ b/product_docs/docs/tde/15/initdb_tde_options.mdx @@ -42,7 +42,7 @@ If you didn't apply a wrapping mechanism, use `-` . Disables the key wrapping. The data encryption key is instead stored in plaintext in the data directory. (This option is a shortcut for setting both the wrap and the unwrap command to the special value `-`.) !!!Note - Using this option isn't secure. Use it only for testing purposes. + Using this option isn't secure. Only use it for testing purposes. !!! If you select data encryption and don't specify this option, then you must provide a key wrap and unwrap command. Otherwise, `initdb` terminates with an error. diff --git a/product_docs/docs/tde/15/overview.mdx b/product_docs/docs/tde/15/overview.mdx index 9e41aacb4a1..16b584159dc 100644 --- a/product_docs/docs/tde/15/overview.mdx +++ b/product_docs/docs/tde/15/overview.mdx @@ -6,7 +6,7 @@ redirects: - /tde/latest/enabling_tde/ --- -If you want to start using transparent data encryption (TDE) on your database, you want to either create a TDE-enabled database server or migrate an existing database server to a TDE-enabled environment. It isn't possible to enable TDE on existing instances. +If you want to start using transparent data encryption (TDE) on your database, you'll want to either create a TDE-enabled database server or migrate an existing database server to a TDE-enabled environment. It isn't possible to enable TDE on existing instances. Regardless of whether you're creating a database server from scratch or creating an instance to migrate an existing database server, you have to create a TDE-enabled database by initializing a database cluster using [initdb](https://www.postgresql.org/docs/15/app-initdb.html). @@ -14,7 +14,7 @@ Regardless of whether you're creating a database server from scratch or creating - Choose a method to [secure the data encryption key](secure_key) generated by TDE. - You can protect they key with a [passphrase](./secure_key/passphrase/) or a wrapping key from a [key store](secure_key/key_store/). Or you can choose to [not protect the key](secure_key/disabling_key/) for testing purposes. + You can protect the key with a [passphrase](./secure_key/passphrase/) or a wrapping key from a [key store](secure_key/key_store/). Or, for testing purposes, you can choose to [not protect the key](secure_key/disabling_key/). - Review the [initdb TDE options](./initdb_tde_options/) to ensure you have all information required for initializing a TDE-enabled database cluster. @@ -51,7 +51,7 @@ If you want to migrate data and objects from an existing database server, use pg 1. Perform any required cleanup operations. !!!note -See [TDE pg_upgrade use cases](upgrading) for an overview of the supported enablement and migration use cases. +See [TDE pg_upgrade use cases](upgrading) for an overview of the supported use cases for enabling and migrating. !!! See [Tutorials](#tutorials) for detailed migration examples. diff --git a/product_docs/docs/tde/15/secure_key/disabling_key.mdx b/product_docs/docs/tde/15/secure_key/disabling_key.mdx index a9f2d875b71..54f92af8819 100644 --- a/product_docs/docs/tde/15/secure_key/disabling_key.mdx +++ b/product_docs/docs/tde/15/secure_key/disabling_key.mdx @@ -1,9 +1,9 @@ --- title: Disabling the key wrapping -description: Learn how skip using a wrapping key. +description: Learn how to prevent using a wrapping key. deepToc: true --- If you don't want key wrapping, for example for testing, then you must set the wrap and unwrap commands to the special value `-`. -This setting specifies to use the key from the file without further processing. This approach differs from not setting a wrap or unwrap command at all and from setting either/both to an empty string. Having no wrap or unwrap command set when transparent data encryption is used leaves your data encryption key unsecured and results in a fatal error when running an affected utility program. +This setting specifies to use the key from the file without further processing. This approach differs from not setting a wrap or unwrap command at all and from setting either or both to an empty string. Having no wrap or unwrap command set when transparent data encryption is used leaves your data encryption key unsecured and results in a fatal error when running an affected utility program. diff --git a/product_docs/docs/tde/15/secure_key/index.mdx b/product_docs/docs/tde/15/secure_key/index.mdx index 4eb1a30238c..45ef27d8b51 100644 --- a/product_docs/docs/tde/15/secure_key/index.mdx +++ b/product_docs/docs/tde/15/secure_key/index.mdx @@ -13,9 +13,9 @@ redirects: ## Data encryption key -The key for transparent data encryption (the data key) is generated by `initdb` and stored in a file `pg_encryption/key.bin` under the data directory. This file actually contains several keys that are used for different purposes at runtime. The data key is a single sequence of random bytes in the file. +The key for transparent data encryption (the data key) is generated by `initdb` and stored in a file `pg_encryption/key.bin` under the data directory. This file contains several keys that are used for different purposes at runtime. The data key is a single sequence of random bytes in the file. -Without any further action, this file contains the key in plaintext, which isn't secure. Anyone with access to the encrypted data directory has access to the plaintext key, which defeats the purpose of encryption. +If you don't perform any further action, this file contains the key in plaintext, which isn't secure. Anyone with access to the encrypted data directory has access to the plaintext key, which defeats the purpose of encryption. ## Choosing a mechanism to protect the data encryption key @@ -27,15 +27,15 @@ With the wrap and unwrap commands you can: - [Protect the data key with a wrapping key stored in a key management system](key_store) or key store. This second key is also called the *key-wrapping key* or *master key*. -- You can also choose to [disable the data encryption key wrapping](disabling_key). Do this only for test environments, as it leaves the TDE key unprotected. +- You can also choose to [disable the data encryption key wrapping](disabling_key). Only do this for test environments, as it leaves the TDE key unprotected. ## Configuring a wrapping and unwrapping command After you choose a method to protect your key, you can create the wrapping/unwrapping commands. The configuration of these commands is left to the user, which allows you to tailor the setup to local requirements and integrate with existing key management software or similar. -[Using a passphrase](passphrase) provides an example for wrapping/unwrapping commands using OpenSSL and a passphrase to secure the TDE data key. [Using a key store](key_store) provides an example for wrapping/unwrapping commands using an external key store key to protect the TDE data key. +[Using a passphrase](passphrase) provides an example for wrapping and unwrapping commands using OpenSSL and a passphrase to secure the TDE data key. [Using a key store](key_store) provides an example for wrapping and unwrapping commands using an external key store key to protect the TDE data key. -When you initialize a server with TDE, the `initdb` command adds the `data_encryption_key_unwrap_command` parameter in the `postgresql.conf` configuration file. The string specified in `data_encryption_key_unwrap_command` is then able to unwrap (decrypt) the data encryption key. +When you initialize a server with TDE, the `initdb` command adds the `data_encryption_key_unwrap_command` parameter in the `postgresql.conf` configuration file. The string specified in `data_encryption_key_unwrap_command` can then unwrap (decrypt) the data encryption key. The commands must contain a placeholder `%p`, which is replaced with the name of the file containing the key to unwrap. The command must print the unwrapped (decrypted) key to its standard output. @@ -43,7 +43,7 @@ The commands must contain a placeholder `%p`, which is replaced with the name of You must make the commands available to the TDE database server so it can wrap and unwrap the data encryption key. You have the following options: -- You can configure the wrapping and unwrapping commands as environment variables before creating the database, so TDE can fall back on those variables when initializing a server. +- You can configure the wrapping and unwrapping commands as environment variables before creating the database, so TDE can fall back on those variables when initializing a server:
Example @@ -58,7 +58,7 @@ You must make the commands available to the TDE database server so it can wrap a

-- You can provide the wrapping and unwrapping commands directly in the command line when initializing a server with the `--key-wrap-command=` and `--key-unwrap-command=` options. +- You can provide the wrapping and unwrapping commands directly in the command line when initializing a server with the `--key-wrap-command=` and `--key-unwrap-command=` options:
Example @@ -69,7 +69,7 @@ You must make the commands available to the TDE database server so it can wrap a

-- You can disable the protection of your data encryption key with `--no-key-wrap`. Doing so leaves your key unprotected and we recommend it only for testing proposes. +- You can disable the protection of your data encryption key with `--no-key-wrap`. Doing so leaves your key unprotected and we recommend this practice only for testing purposes.
Example diff --git a/product_docs/docs/tde/15/secure_key/key_rotation.mdx b/product_docs/docs/tde/15/secure_key/key_rotation.mdx index 197d5997688..0cbe6c43106 100644 --- a/product_docs/docs/tde/15/secure_key/key_rotation.mdx +++ b/product_docs/docs/tde/15/secure_key/key_rotation.mdx @@ -4,11 +4,15 @@ description: Learn how to rotate your data encryption key. deepToc: true --- -To change the master key, manually run the unwrap command, specifying the old key. Then feed the result into the wrap command specifying the new key. Equivalently, if the data key is protected by a passphrase, to change the passphrase, run the unwrap command using the old passphrase. Then feed the result into the wrap command using the new passphrase. You can perform these operations while the database server is running. The wrapped data key in the file is used only on startup. It isn't used while the server is running. +To change the master key, manually run the unwrap command, specifying the old key. Then feed the result into the wrap command, specifying the new key. + +Equivalently, if the data key is protected by a passphrase, to change the passphrase, run the unwrap command using the old passphrase. Then feed the result into the wrap command using the new passphrase. + +You can perform these operations while the database server is running. The wrapped data key in the file is used only on startup. It isn't used while the server is running. ## Rotating the passphrase -Building on the example in [Using a passphrase](passphrase), which uses openssl, to change the passphrase, you can: +Building on the example in [Using a passphrase](passphrase), which uses OpenSSL, to change the passphrase, you can use this approach: ```shell cd $PGDATA/pg_encryption/ @@ -26,7 +30,7 @@ This technique leaks the old passphrase, which is being replaced anyway. OpenSSL ## Rotating the key store wrapping key -When using a [key store](key_store), you can connect the unwrap and wrap commands similarly, for example: +When using a [key store](key_store), you can connect the unwrap and wrap commands similarly. For example: ```shell cd $PGDATA/pg_encryption/ diff --git a/product_docs/docs/tde/15/secure_key/passphrase.mdx b/product_docs/docs/tde/15/secure_key/passphrase.mdx index 85054afd213..f09ac41f70f 100644 --- a/product_docs/docs/tde/15/secure_key/passphrase.mdx +++ b/product_docs/docs/tde/15/secure_key/passphrase.mdx @@ -3,7 +3,7 @@ title: Using a passphrase description: Learn how to secure your encryption key with a passphrase. --- -You can protect the data key with a passphrase using the openssl command line utility. The following is an example that sets up this protection: +You can protect the data key with a passphrase using the OpenSSL command line utility. The following is an example that sets up this protection: ```shell initdb -D datadir -y --key-wrap-command='openssl enc -e -aes-128-cbc -pbkdf2 -out "%p"' --key-unwrap-command='openssl enc -d -aes-128-cbc -pbkdf2 -in "%p"' @@ -13,10 +13,9 @@ This example wraps the randomly generated data key (done internally by initdb) b The unwrap command performs the opposite operation. initdb doesn't need the unwrap operation. However, it stores it in the `postgresql.conf` file of the initialized cluster, which uses it when it starts up. - The key wrap command receives the plaintext key on standard input and needs to put the wrapped key at the file system location specified by the `%p` placeholder. The key unwrap command needs to read the wrapped key from the file system location specified by the `%p` placeholder and write the unwrapped key to the standard output. -Utility programs like pg_rewind and pg_upgrade operate directly on the data directory or copies, such as backups. These programs also need to be told about the key unwrap command, depending on the circumstances. They each have command-line options for this purpose. +Utility programs like pg_rewind and pg_upgrade operate directly on the data directory or copies, such as backups. These programs also need to be told about the key unwrap command, depending on the circumstances. They each have command line options for this purpose. To simplify operations, you can also set the key wrap and unwrap commands in environment variables. These are accepted by all affected applications if you don't provide the corresponding command line options. For example: diff --git a/product_docs/docs/tde/15/upgrading.mdx b/product_docs/docs/tde/15/upgrading.mdx index 8ebb77df0a4..4dff1169f92 100644 --- a/product_docs/docs/tde/15/upgrading.mdx +++ b/product_docs/docs/tde/15/upgrading.mdx @@ -6,7 +6,8 @@ redirects: - /tde/latest/upgrade_use_cases/ #generated for TDE/refresh --- -You can use [pg_upgrade](https://www.postgresql.org/docs/current/pgupgrade.html) with additional TDE arguments to perform upgrading and migrating operations. +You can use [pg_upgrade](https://www.postgresql.org/docs/current/pgupgrade.html) with additional TDE arguments to perform upgrading and migrating operations. + This table provides an overview of supported use cases. | Use case | Source unencrypted server | Target encrypted server | From 84c7188c3423d264cc3bcc4d05f116f0a236c600 Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Thu, 14 Nov 2024 16:29:33 -0500 Subject: [PATCH 3/6] Update product_docs/docs/tde/15/initdb_tde_options.mdx Co-authored-by: gvasquezvargas --- product_docs/docs/tde/15/initdb_tde_options.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/product_docs/docs/tde/15/initdb_tde_options.mdx b/product_docs/docs/tde/15/initdb_tde_options.mdx index 69261bbce15..f42101cbeca 100644 --- a/product_docs/docs/tde/15/initdb_tde_options.mdx +++ b/product_docs/docs/tde/15/initdb_tde_options.mdx @@ -21,7 +21,7 @@ Provides the wrapping/encryption command to protect the data encryption key. `` is customizable, but it must contain the placeholder `%p`. See [Wrapping commands](secure_key/#configuring-a-wrapping-and-unwrapping-command) for examples and information. See [Securing the data encryption key](secure_key) for an overview of available wrapping mechanisms. -If you don't specify a command, TDE falls back on the environment variable `PGDATAKEYWRAPCMD`. +If you don't use this option, TDE falls back on the environment variable `PGDATAKEYWRAPCMD`. If you don't want to apply a wrapping mechanism, Use `-`. From 35997a577201bd1baf4f0f3c5c1329f57b98a0b2 Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Thu, 14 Nov 2024 16:29:40 -0500 Subject: [PATCH 4/6] Update product_docs/docs/tde/15/initdb_tde_options.mdx Co-authored-by: gvasquezvargas --- product_docs/docs/tde/15/initdb_tde_options.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/product_docs/docs/tde/15/initdb_tde_options.mdx b/product_docs/docs/tde/15/initdb_tde_options.mdx index f42101cbeca..924deab7fbe 100644 --- a/product_docs/docs/tde/15/initdb_tde_options.mdx +++ b/product_docs/docs/tde/15/initdb_tde_options.mdx @@ -33,7 +33,7 @@ Provides the unwrapping/decryption command to access the data encryption key. `` is customizable, but it must contain the placeholder `%p`. See [Configuring wrapping commands](secure_key/#configuring-a-wrapping-and-unwrapping-command) for examples and information. -If you don't specify a command, TDE falls back on the environment variable `PGDATAKEYUNWRAPCMD`. +If you don't use this option, TDE falls back on the environment variable `PGDATAKEYUNWRAPCMD`. If you didn't apply a wrapping mechanism, use `-` . From aaa52241bf7d7ea59dcb1e2553452edbb7015782 Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Thu, 21 Nov 2024 13:52:43 -0500 Subject: [PATCH 5/6] Update enabling_tde.mdx changed ok to password --- product_docs/docs/tde/15/enabling/enabling_tde.mdx | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/product_docs/docs/tde/15/enabling/enabling_tde.mdx b/product_docs/docs/tde/15/enabling/enabling_tde.mdx index 42d7d4dbdcf..af63e7559ab 100644 --- a/product_docs/docs/tde/15/enabling/enabling_tde.mdx +++ b/product_docs/docs/tde/15/enabling/enabling_tde.mdx @@ -17,13 +17,12 @@ This example uses EDB Postgres Advanced Server 15 running on a Linux platform. I 1. Set the data encryption key (wrap) and decryption (unwrap) environment variables: ```shell - export PGDATAKEYWRAPCMD='openssl enc -e -aes-128-cbc -pass pass:ok -out %p' - export PGDATAKEYUNWRAPCMD='openssl enc -d -aes-128-cbc -pass pass:ok -in %p' + export PGDATAKEYWRAPCMD='openssl enc -e -aes-128-cbc -pass pass: -out %p' + export PGDATAKEYUNWRAPCMD='openssl enc -d -aes-128-cbc -pass pass: -in %p' ``` + !!!note - If you're on Windows, you don't need the single quotes around the variable value. - - - Ensure you replace `ok` with the passphrase you want to use to wrap the data encryption key. !!! 1. Initialize the cluster using `initdb` with encryption enabled. This command sets the `data_encryption_key_unwrap_command` parameter in the `postgresql.conf` file. @@ -43,7 +42,7 @@ This example uses EDB Postgres Advanced Server 15 running on a Linux platform. I ```shell grep data_encryption_key_unwrap_command /var/lib/edb/as15/data/postgresql.conf __OUTPUT__ - data_encryption_key_unwrap_command = 'openssl enc -d -aes-128-cbc -pass pass:ok -in %p' + data_encryption_key_unwrap_command = 'openssl enc -d -aes-128-cbc -pass pass: -in %p' ``` -1. [Verify that data encryption is enabled](verifying_tde). \ No newline at end of file +1. [Verify that data encryption is enabled](verifying_tde). From 981cb4fdde89e7adb4169c6983ad58f5522339cc Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Thu, 21 Nov 2024 13:55:01 -0500 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: gvasquezvargas --- product_docs/docs/tde/15/enabling/enabling_tde_epas.mdx | 2 +- product_docs/docs/tde/15/enabling/postgres_to_extended.mdx | 2 +- product_docs/docs/tde/15/initdb_tde_options.mdx | 2 +- product_docs/docs/tde/15/overview.mdx | 2 +- product_docs/docs/tde/15/secure_key/disabling_key.mdx | 4 ++-- product_docs/docs/tde/15/secure_key/key_rotation.mdx | 2 +- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/product_docs/docs/tde/15/enabling/enabling_tde_epas.mdx b/product_docs/docs/tde/15/enabling/enabling_tde_epas.mdx index 612ef802116..d05c9b123b7 100644 --- a/product_docs/docs/tde/15/enabling/enabling_tde_epas.mdx +++ b/product_docs/docs/tde/15/enabling/enabling_tde_epas.mdx @@ -28,7 +28,7 @@ and use pg_upgrade to transfer data from the existing source cluster to the new ## Worked example -This example enables transparent data encryption on EDB Postgres Advanced Server version 16 running on an Ubuntu 22.04 machine. +This example enables TDE on EDB Postgres Advanced Server version 16 running on an Ubuntu 22.04 machine. A similar workflow applies to other versions of EDB Postgres Advanced Server and EDB Postgres Extended Server. The location of the bin and config directories differs depending on your operating system and the Postgres version. diff --git a/product_docs/docs/tde/15/enabling/postgres_to_extended.mdx b/product_docs/docs/tde/15/enabling/postgres_to_extended.mdx index 7a5f7ae65b3..4e9f507e6e4 100644 --- a/product_docs/docs/tde/15/enabling/postgres_to_extended.mdx +++ b/product_docs/docs/tde/15/enabling/postgres_to_extended.mdx @@ -28,7 +28,7 @@ Create a new EDB Postgres Extended Server cluster with TDE enabled and use pg_up ## Worked example -This example upgrades a PostgreSQL 16 instance to EDB Postgres Extended Server 16 while enabling transparent data encryption on an Ubuntu 22.04 machine. The location of the bin and config directories differs depending on your operating system and Postgres versions. +This example upgrades a PostgreSQL 16 instance to EDB Postgres Extended Server 16 while enabling TDE on an Ubuntu 22.04 machine. The location of the bin and config directories differs depending on your operating system and Postgres versions. ### Preparing your upgrade diff --git a/product_docs/docs/tde/15/initdb_tde_options.mdx b/product_docs/docs/tde/15/initdb_tde_options.mdx index 924deab7fbe..9b0387b0f1f 100644 --- a/product_docs/docs/tde/15/initdb_tde_options.mdx +++ b/product_docs/docs/tde/15/initdb_tde_options.mdx @@ -23,7 +23,7 @@ Provides the wrapping/encryption command to protect the data encryption key. If you don't use this option, TDE falls back on the environment variable `PGDATAKEYWRAPCMD`. -If you don't want to apply a wrapping mechanism, Use `-`. +If you don't want to apply a wrapping mechanism, use `-`. ## Option: `--key-unwrap-command=` diff --git a/product_docs/docs/tde/15/overview.mdx b/product_docs/docs/tde/15/overview.mdx index 16b584159dc..b8756512cab 100644 --- a/product_docs/docs/tde/15/overview.mdx +++ b/product_docs/docs/tde/15/overview.mdx @@ -6,7 +6,7 @@ redirects: - /tde/latest/enabling_tde/ --- -If you want to start using transparent data encryption (TDE) on your database, you'll want to either create a TDE-enabled database server or migrate an existing database server to a TDE-enabled environment. It isn't possible to enable TDE on existing instances. +If you want to start using Transparent Data Encryption (TDE) on your database, you'll want to either create a TDE-enabled database server or migrate an existing database server to a TDE-enabled environment. It isn't possible to enable TDE on existing instances. Regardless of whether you're creating a database server from scratch or creating an instance to migrate an existing database server, you have to create a TDE-enabled database by initializing a database cluster using [initdb](https://www.postgresql.org/docs/15/app-initdb.html). diff --git a/product_docs/docs/tde/15/secure_key/disabling_key.mdx b/product_docs/docs/tde/15/secure_key/disabling_key.mdx index 54f92af8819..bdf8edb7e19 100644 --- a/product_docs/docs/tde/15/secure_key/disabling_key.mdx +++ b/product_docs/docs/tde/15/secure_key/disabling_key.mdx @@ -1,9 +1,9 @@ --- title: Disabling the key wrapping -description: Learn how to prevent using a wrapping key. +description: Learn how to omit using a wrapping key. deepToc: true --- If you don't want key wrapping, for example for testing, then you must set the wrap and unwrap commands to the special value `-`. -This setting specifies to use the key from the file without further processing. This approach differs from not setting a wrap or unwrap command at all and from setting either or both to an empty string. Having no wrap or unwrap command set when transparent data encryption is used leaves your data encryption key unsecured and results in a fatal error when running an affected utility program. +This setting specifies to use the key from the file without further processing. This approach differs from not setting a wrap or unwrap command at all and from setting either or both to an empty string. Having no wrap or unwrap command set when TDE is used leaves your data encryption key unsecured and results in a fatal error when running an affected utility program. diff --git a/product_docs/docs/tde/15/secure_key/key_rotation.mdx b/product_docs/docs/tde/15/secure_key/key_rotation.mdx index 0cbe6c43106..a24799b5d33 100644 --- a/product_docs/docs/tde/15/secure_key/key_rotation.mdx +++ b/product_docs/docs/tde/15/secure_key/key_rotation.mdx @@ -6,7 +6,7 @@ deepToc: true To change the master key, manually run the unwrap command, specifying the old key. Then feed the result into the wrap command, specifying the new key. -Equivalently, if the data key is protected by a passphrase, to change the passphrase, run the unwrap command using the old passphrase. Then feed the result into the wrap command using the new passphrase. +If the data key is protected by a passphrase, to change the passphrase, run the unwrap command using the old passphrase. Then feed the result into the wrap command using the new passphrase. You can perform these operations while the database server is running. The wrapped data key in the file is used only on startup. It isn't used while the server is running.