From 9e997a5f1cdd630a95dd2bd2dc7d742e9d95ef36 Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Tue, 6 Apr 2021 14:23:34 -0400 Subject: [PATCH] cfe-01-doc_over_master squash commit --- doc/src/sgml/database-encryption.sgml (new) | 149 ++++++++++++++++++++ doc/src/sgml/filelist.sgml | 1 + doc/src/sgml/installation.sgml | 2 +- doc/src/sgml/monitoring.sgml | 13 ++ doc/src/sgml/postgres.sgml | 1 + 5 files changed, 165 insertions(+), 1 deletion(-) diff --git a/doc/src/sgml/database-encryption.sgml b/doc/src/sgml/database-encryption.sgml new file mode 100644 index 0000000000..c4377ada64 --- /dev/null +++ b/doc/src/sgml/database-encryption.sgml @@ -0,0 +1,149 @@ + + + + Cluster File Encryption + + + Cluster File Encryption + + + + The purpose of cluster file encryption is to prevent users with read + access on the directories used to store database files and write-ahead + log files from being able to access the data stored in those files. + For example, when using cluster file encryption, users who have read + access to the cluster directories for backup purposes will not be able + to decrypt the data stored in these files. Read-only access for a group + of users can be enabled using the initdb + option. Cluster file encryption + also provides data-at-rest security, protecting users from data loss + should the physical storage media be stolen or improperly erased before + disposal. + + + + Cluster file encryption does not protect against unauthorized file + system writes. Such writes can allow data decryption if used to weaken + the system's security and the weakened system is later supplied with + the externally-stored cluster encryption key. This also does not always + detect if users with write access remove or modify database files. + + + + This also does not protect against users who have read access to database + process memory because all in-memory data pages and data encryption keys + are stored unencrypted in memory. Therefore, an attacker who is able + to read memory can read the data encryption keys and decrypt the entire + cluster. The Postgres operating system user and the operating system + administrator, e.g., the root user, have such access. + + + + Keys + + + Cluster file encryption uses two levels of encryption — an upper + key which encrypts lower-level keys. The upper-level key is often + referred to as a Key Encryption Key (KEK). This key + is not stored in the file system, but provided at + initdb time and each time the server is started. This + key can be easily changed via pg_alterckey without + requiring any changes to the the data files or WAL + files. + + + + The lower level keys are data encryption keys, specifically for relations + and WAL. The relation key is used to encrypt database + heap and index files. The WAL key is used to encrypt write-ahead log + (WAL) files. Two different keys are used so that primary and standby + servers can use different relation keys, but the same WAL key, so that + these keys can (in a future release) be rotated by switching the + primary to the standby and then changing the WAL key. Eventually, + encryption will be able to added to non-encrypted clusters by creating + encrypted replicas and switching over to them. + + + + Postgres stores the data encryption (lower-level) keys in the data + directory encrypted (wrapped) by key encryption (upper-level) key. + Though the data encryption keys technically exist in the file system, + the key encryption key does not, so the data encryption keys are + securely stored. Data encryption keys are used to security encrypt + other database files. + + + + + Initialization + + + Cluster file encryption is enabled when + PostgreSQL is built + with --with-openssl and is specified + during initdb. The cluster key + provided by the + option during initdb and the one generated + by in the + postgresql.conf must match for the database + cluster to start. Note that the cluster key command + passed to initdb must return a key of + 64 hexadecimal characters. For example: + +initdb -D dbname --cluster-key-command='ckey_passphrase.sh' + + Cluster file encryption does not support a wal_level + of minimal. + + + + + Operation + + + During the initdb process, if + is specified, two data-level + encryption keys are created. These two keys are then encrypted with + the key encryption key (KEK) supplied by the cluster key command before + being stored in the database directory. The key or passphrase that + derives the key must be supplied from the terminal or stored in a + trusted key store, such as key vault software or a hardware security + module. + + + + If the PostgreSQL server has + been initialized to require a cluster key, each time the + server starts the postgresql.conf + cluster_key_command command will be executed + and the cluster key retrieved. The data encryption keys in the + pg_cryptokeys directory will then be decrypted + using the supplied key and integrity-checked to ensure it matches the + initdb-supplied key. (If this check fails, the server will refuse + to start.) The cluster encryption key will then be removed from + system memory. The decrypted data encryption keys will remain in + shared memory until the server is stopped. + + + + The data encryption keys are randomly generated and can be 128, 192, + or 256-bits in length, depending on whether AES128, + AES192, or AES256 is specified. + They are encrypted by the key encryption key (KEK) using Advanced + Encryption Standard (AES256) encryption in Key + Wrap Padded Mode, which also provides KEK authentication; see RFC 5649. While + 128-bit encryption is sufficient for most sites, 256-bit encryption + is thought to be more immune to future quantum cryptographic attacks. + + + . + If you prefer to create the random keys on your own, you can create + a empty directory with a pg_cryptokeys/live + subdirectory, generate the keys there using your tools. and use the + initdb + to copy those keys into the newly-created cluster. + + + diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 45b701426b..baf65fa24c 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -49,6 +49,7 @@ + diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 66ad4ba938..405cdc2fac 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -976,7 +976,7 @@ build-postgresql: Build with support for SSL (encrypted) - connections. The only LIBRARY + connections and cluster file encryption. The only LIBRARY supported is . This requires the OpenSSL package to be installed. configure will check for the required diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 56018745c8..418e4e2644 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -1302,6 +1302,19 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser DataFileWrite Waiting for a write to a relation data file. + + KeyFileRead + Waiting for a read of the wrapped data encryption keys. + + + KeyFileWrite + Waiting for a write of the wrapped data encryption keys. + + + KeyFileSync + Waiting for changes to the wrapped data encryption keys to reach + durable storage. + LockFileAddToDataDirRead Waiting for a read while adding a line to the data directory lock diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index d453be3909..628cb86098 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -171,6 +171,7 @@ break is not needed in a wider output rendering. &wal; &logical-replication; &jit; + &database-encryption; ®ress; -- 2.20.1