diff --git a/src/docs/user/configuration/configuring_encryption.diviner b/src/docs/user/configuration/configuring_encryption.diviner index 1e62071509..dbd0e76314 100644 --- a/src/docs/user/configuration/configuring_encryption.diviner +++ b/src/docs/user/configuration/configuring_encryption.diviner @@ -1,196 +1,196 @@ @title Configuring Encryption @group config Setup guide for configuring encryption. Overview ======== Phabricator supports at-rest encryption of uploaded file data stored in the "Files" application. Configuring at-rest file data encryption does not encrypt any other data or resources. In particular, it does not encrypt the database and does not encrypt Passphrase credentials. Attackers who compromise a Phabricator host can read the master key and decrypt the data. In most configurations, this does not represent a significant barrier above and beyond accessing the file data. Thus, configuring at-rest encryption is primarily useful for two types of installs: - If you maintain your own webserver and database hardware but want to use Amazon S3 or a similar cloud provider as a blind storage server, file data encryption can let you do so without needing to trust the cloud provider. - If you face a regulatory or compliance need to encrypt data at rest but do not need to actually secure this data, encrypting the data and placing the master key in plaintext next to it may satisfy compliance requirements. The remainder of this document discusses how to configure at-rest encryption. Quick Start =========== To configure encryption, you will generally follow these steps: - Generate a master key with `bin/files generate-key`. - Add the master key it to the `keyring`, but don't mark it as `default` yet. - Use `bin/files encode ...` to test encrypting a few files. - Mark the key as `default` to automatically encrypt new files. - Use `bin/files encode --all ...` to encrypt any existing files. See the following sections for detailed guidance on these steps. Configuring a Keyring ===================== To configure a keyring, set `keyring` with `bin/config` or by using another configuration source. This option should be a list of keys in this format: ```lang=json ... "keyring": [ { "name": "master.key", "type": "aes-256-cbc", "material.base64": "UcHUJqq8MhZRwhvDV8sJwHj7bNJoM4tWfOIi..." "default": true }, ... ] ... ``` Each key should have these properties: - `name`: //Required string.// A unique key name. - `type`: //Required string.// Type of the key. Only `aes-256-cbc` is supported. - `material.base64`: //Required string.// The key material. See below for details. - `default`: //Optional bool.// Optionally, mark exactly one key as the default key to enable encryption of newly uploaded file data. -The key material is sensitive an an attacker who learns it can decrypt data +The key material is sensitive and an attacker who learns it can decrypt data from the storage engine. Format: Raw Data ================ The `raw` storage format is automatically selected for all newly uploaded file data if no key is makred as the `default` key in the keyring. This is the behavior of Phabricator if you haven't configured anything. This format stores raw data without modification. Format: AES256 ============== The `aes-256-cbc` storage format is automatically selected for all newly uploaded file data if an AES256 key is marked as the `default` key in the keyring. This format uses AES256 in CBC mode. Each block of file data is encrypted with a unique, randomly generated private key. That key is then encrypted with the master key. Among other motivations, this strategy allows the master key to be cycled relatively cheaply later (see "Cycling Master Keys" below). AES256 keys should be randomly generated and 256 bits (32 characters) in length, then base64 encoded when represented in `keyring`. You can generate a valid, properly encoded AES256 master key with this command: ``` phabricator/ $ ./bin/files generate-key --type aes-256-cbc ``` This mode is generally similar to the default server-side encryption mode supported by Amazon S3. Format: ROT13 ============= The `rot13` format is a test format that is never selected by default. You can select this format explicitly with `bin/files encode` to test storage and encryption behavior. This format applies ROT13 encoding to file data. Changing File Storage Formats ============================= To test configuration, you can explicitly change the storage format of a file. This will read the file data, decrypt it if necessary, write a new copy of the data with the desired encryption, then update the file to point at the new data. You can use this to make sure encryption works before turning it on by default. To change the format of an individual file, run this command: ``` phabricator/ $ ./bin/files encode --as F123 [--key ] ``` This will change the storage format of the sepcified file. Verifying Storage Formats ========================= You can review the storage format of a file from the web UI, in the {nav Storage} tab under "Format". You can also use the "Engine" and "Handle" properties to identify where the underlying data is stored and verify that it is encrypted or encoded in the way you expect. See @{article:Configuring File Storage} for more information on storage engines. Cycling Master Keys =================== If you need to cycle your master key, some storage formats support key cycling. Cycling a file's encryption key decodes the local key for the data using the old master key, then re-encodes it using the new master key. This is primarily useful if you believe your master key may have been compromised. First, add a new key to the keyring and mark it as the default key. You need to leave the old key in place for now so existing data can be decrypted. To cycle an individual file, run this command: ``` phabricator/ $ ./bin/files cycle F123 ``` Verify that cycling worked properly by examining the command output and accessing the file to check that the data is present and decryptable. You can cycle additional files to gain additional confidence. You can cycle all files with this command: ``` phabricator/ $ ./bin/files cycle --all ``` Once all files have been cycled, remove the old master key from the keyring. Not all storage formats support key cycling: cycling a file only has an effect if the storage format is an encrypted format. For example, cycling a file that uses the `raw` storage format has no effect. Next Steps ========== Continue by: - understanding storage engines with @{article:Configuring File Storage}; or - returning to the @{article:Configuration Guide}.