Configuring Encryption

Phabricator User Documentation (Configuration)

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:

...
"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 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 marked 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 <format> F123 [--key <key>]

This will change the storage format of the specified file.

Verifying Storage Formats

You can review the storage format of a file from the web UI, in the 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 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 Configuring File Storage; or
• returning to the Configuration Guide.