Changeset View
Changeset View
Standalone View
Standalone View
src/docs/user/configuration/configuring_encryption.diviner
@title Configuring Encryption | @title Configuring Encryption | ||||
@group config | @group config | ||||
Setup guide for configuring encryption. | Setup guide for configuring encryption. | ||||
Overview | Overview | ||||
======== | ======== | ||||
Phabricator supports at-rest encryption of uploaded file data stored in the | Phorge supports at-rest encryption of uploaded file data stored in the | ||||
"Files" application. | "Files" application. | ||||
Configuring at-rest file data encryption does not encrypt any other data or | 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 | resources. In particular, it does not encrypt the database and does not encrypt | ||||
Passphrase credentials. | Passphrase credentials. | ||||
Attackers who compromise a Phabricator host can read the master key and decrypt | Attackers who compromise a Phorge host can read the master key and decrypt | ||||
the data. In most configurations, this does not represent a significant | the data. In most configurations, this does not represent a significant | ||||
barrier above and beyond accessing the file data. Thus, configuring at-rest | barrier above and beyond accessing the file data. Thus, configuring at-rest | ||||
encryption is primarily useful for two types of installs: | encryption is primarily useful for two types of installs: | ||||
- If you maintain your own webserver and database hardware but want to use | - 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 | 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. | 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 | - If you face a regulatory or compliance need to encrypt data at rest but do | ||||
▲ Show 20 Lines • Show All 51 Lines • ▼ Show 20 Lines | |||||
from the storage engine. | from the storage engine. | ||||
Format: Raw Data | Format: Raw Data | ||||
================ | ================ | ||||
The `raw` storage format is automatically selected for all newly uploaded | 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 | 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. | the behavior of Phorge if you haven't configured anything. | ||||
This format stores raw data without modification. | This format stores raw data without modification. | ||||
Format: AES256 | Format: AES256 | ||||
============== | ============== | ||||
The `aes-256-cbc` storage format is automatically selected for all newly | 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 | uploaded file data if an AES256 key is marked as the `default` key in the | ||||
keyring. | keyring. | ||||
This format uses AES256 in CBC mode. Each block of file data is encrypted with | 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 | 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 | master key. Among other motivations, this strategy allows the master key to be | ||||
cycled relatively cheaply later (see "Cycling Master Keys" below). | cycled relatively cheaply later (see "Cycling Master Keys" below). | ||||
AES256 keys should be randomly generated and 256 bits (32 characters) in | AES256 keys should be randomly generated and 256 bits (32 characters) in | ||||
length, then base64 encoded when represented in `keyring`. | length, then base64 encoded when represented in `keyring`. | ||||
You can generate a valid, properly encoded AES256 master key with this command: | You can generate a valid, properly encoded AES256 master key with this command: | ||||
``` | ``` | ||||
phabricator/ $ ./bin/files generate-key --type aes-256-cbc | phorge/ $ ./bin/files generate-key --type aes-256-cbc | ||||
``` | ``` | ||||
This mode is generally similar to the default server-side encryption mode | This mode is generally similar to the default server-side encryption mode | ||||
supported by Amazon S3. | supported by Amazon S3. | ||||
Format: ROT13 | Format: ROT13 | ||||
============= | ============= | ||||
Show All 13 Lines | |||||
This will read the file data, decrypt it if necessary, write a new copy of the | 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 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 | data. You can use this to make sure encryption works before turning it on by | ||||
default. | default. | ||||
To change the format of an individual file, run this command: | To change the format of an individual file, run this command: | ||||
``` | ``` | ||||
phabricator/ $ ./bin/files encode --as <format> F123 [--key <key>] | phorge/ $ ./bin/files encode --as <format> F123 [--key <key>] | ||||
``` | ``` | ||||
This will change the storage format of the specified file. | This will change the storage format of the specified file. | ||||
Verifying Storage Formats | Verifying Storage Formats | ||||
========================= | ========================= | ||||
Show All 16 Lines | |||||
useful if you believe your master key may have been compromised. | 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 | 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 leave the old key in place for now so existing data can be decrypted. | ||||
To cycle an individual file, run this command: | To cycle an individual file, run this command: | ||||
``` | ``` | ||||
phabricator/ $ ./bin/files cycle F123 | phorge/ $ ./bin/files cycle F123 | ||||
``` | ``` | ||||
Verify that cycling worked properly by examining the command output and | Verify that cycling worked properly by examining the command output and | ||||
accessing the file to check that the data is present and decryptable. You | accessing the file to check that the data is present and decryptable. You | ||||
can cycle additional files to gain additional confidence. | can cycle additional files to gain additional confidence. | ||||
You can cycle all files with this command: | You can cycle all files with this command: | ||||
``` | ``` | ||||
phabricator/ $ ./bin/files cycle --all | phorge/ $ ./bin/files cycle --all | ||||
``` | ``` | ||||
Once all files have been cycled, remove the old master key from the keyring. | 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 | 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 | if the storage format is an encrypted format. For example, cycling a file that | ||||
uses the `raw` storage format has no effect. | uses the `raw` storage format has no effect. | ||||
Next Steps | Next Steps | ||||
========== | ========== | ||||
Continue by: | Continue by: | ||||
- understanding storage engines with @{article:Configuring File Storage}; or | - understanding storage engines with @{article:Configuring File Storage}; or | ||||
- returning to the @{article:Configuration Guide}. | - returning to the @{article:Configuration Guide}. |
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0