Differential D25007 Diff 19 src/docs/user/configuration/configuring_encryption.diviner

Changeset 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}.