From b3251edebfac62c095d973189a652c3925db4a24 Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Mon, 25 Jan 2021 14:15:57 -0500 Subject: [PATCH] key squash commit --- doc/src/sgml/database-encryption.sgml (new) | 124 ++++++++++++++++++++ doc/src/sgml/filelist.sgml | 1 + doc/src/sgml/installation.sgml | 5 +- doc/src/sgml/postgres.sgml | 1 + 4 files changed, 129 insertions(+), 2 deletions(-) diff --git a/doc/src/sgml/database-encryption.sgml b/doc/src/sgml/database-encryption.sgml new file mode 100644 index 0000000000..e8e1e69ec7 --- /dev/null +++ b/doc/src/sgml/database-encryption.sgml @@ -0,0 +1,124 @@ + + + + Cluster File Encryption + + + Cluster File Encryption + + + + The purpose of cluster file encryption is to prevent users with read + access to 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. It also protects against + decrypted data access after media theft. + + + + File system write access can allow for unauthorized file system data + decryption if the writes can be used to weaken the system's security + and this weakened system is later supplied with externally-stored keys. + This also does not protect from users who have read access to system + memory. + + + + Cluster file encryption uses two levels of encryption. The first level + is data encryption keys, specifically keys zero and one. Key zero is + the key used to encrypt database heap and index files which are stored in + the file system, plus temporary files created during database operation. + Key one is used to encrypt write-ahead log (WAL) files. Two different + keys are used so that primary and standby servers can use different zero + (heap/index/temp) keys, but the same one (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. + + + + The second level of encryption is a key used to encrypt first-level + keys. This type of 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 prevents anyone with access + to the database directories from decrypting the data because they do + not know the second-level key which encrypted the first-level keys + which encrypted the database cluster files. This key can be easily + changed via pg_alterckey without requiring any + changes to the the data files or WAL files, which + are encrypted with the data keys. + + + + 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' + + + + + + Internals + + + 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 38e8aa0bbf..b96f4ace6c 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 a53389b728..a1473bbf8d 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -976,8 +976,9 @@ build-postgresql: Build with support for SSL (encrypted) - connections. This requires the OpenSSL - package to be installed. configure will check + connections and cluster file encryption. This requires the + OpenSSL package to be installed. + configure will check for the required header files and libraries to make sure that your OpenSSL installation is sufficient before proceeding. diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 730d5fdc34..0ea7da604b 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