From 12ededa7ae76ace98f9447297de1ea3936e79aaf Mon Sep 17 00:00:00 2001 From: Brent Roskos Date: Mon, 11 Aug 2014 12:16:16 -0400 Subject: [PATCH] Add documentation for cinder volume encryption. Closes-Bug: #1224977 Documentation covers the setup of encryption configuration, creating the necessary volume-type and creating encrypted volumes. Also shows a short procedure to validate encryption. Change-Id: I58b84e5119f56873fd4b74949d42f013b07ec91d --- .../section_volume-encryption.xml | 202 ++++++++++++++++++ .../ch_blockstorageconfigure.xml | 1 + 2 files changed, 203 insertions(+) create mode 100644 doc/config-reference/block-storage/section_volume-encryption.xml diff --git a/doc/config-reference/block-storage/section_volume-encryption.xml b/doc/config-reference/block-storage/section_volume-encryption.xml new file mode 100644 index 0000000000..674dec11f8 --- /dev/null +++ b/doc/config-reference/block-storage/section_volume-encryption.xml @@ -0,0 +1,202 @@ + + + %openstack; + ]> +
+ Volume encryption with static key + This is an implementation of a key manager that reads its key from the project's + configuration options. + + This key manager implementation provides limited security, assuming that the + key remains secret. Volume encryption provides protection against a lost or + stolen disk, assuming that the configuration file that contains the key is + not stored on the disk. Encryption also protects the confidentiality of data + as it is transmitted via iSCSI from the compute host to the storage host + as long as an attacker who intercepts the data does not know the secret key. + + Because this implementation uses a single, fixed key, it does not provide + protection if that key is compromised. In particular, different volumes + encrypted with a key provided by this key manager actually share the same + encryption key so any volume can be decrypted once the fixed key is known. + Updates are in the pipeline which will provide true key manager support via the key management service. + This will provide much better security once complete. +
+ Initial configuration + + Configuration changes need to be made to any nodes running the cinder-volume or + nova-compute services. + Update cinder-volume servers: + + Edit the /etc/cinder/cinder.conf file and add or update the value of the option + in the [keymgr] section: + [keymgr] +# Fixed key returned by key manager, specified in hex (string +# value) +fixed_key = 0000000000000000000000000000000000000000000000000000000000000000 + + + Restart cinder-volume. + + + + Update nova-compute servers: + + Edit the /etc/nova/nova.conf file and add or update the value of the option + in the [keymgr] section (add a keymgr section as shown if needed): + [keymgr] +# Fixed key returned by key manager, specified in hex (string +# value) +fixed_key = 0000000000000000000000000000000000000000000000000000000000000000 + + + Restart nova-compute. + + +
+
+ Create encrypted volume type + Block Storage volume type assignment provides a mechanism to provide scheduling to a specific back-end, + and also can be used to specify specific information for a back-end storage device to act upon. + In this case we are creating a volume type called LUKS and providing configuration information that will tell the storage system to + encrypt or decrypt the volume. + + + Source your admin credentials: + $ source admin-openrc.sh + + + Create the volume type: + $ cinder type-create LUKS ++--------------------------------------+-------+ +| ID | Name | ++--------------------------------------+-------+ +| e64b35a4-a849-4c53-9cc7-2345d3c8fbde | LUKS | ++--------------------------------------+-------+ + + + Mark the volume type as encrypted and provide the necessary details: + $ cinder encryption-type-create --cipher aes-xts-plain64 --key_size 512 \ + --control_location front-end LUKS nova.volume.encryptors.luks.LuksEncryptor ++--------------------------------------+-------------------------------------------+-----------------+----------+------------------+ +| Volume Type ID | Provider | Cipher | Key Size | Control Location | ++--------------------------------------+-------------------------------------------+-----------------+----------+------------------+ +| e64b35a4-a849-4c53-9cc7-2345d3c8fbde | nova.volume.encryptors.luks.LuksEncryptor | aes-xts-plain64 | 512 | front-end | ++--------------------------------------+-------------------------------------------+-----------------+----------+------------------+ + + + Support for creating the volume type in the OpenStack dashboard (horizon) exists today, + however support for tagging the type as encrypted and providing the additional information needed is still in review. +
+
+ Create an encrypted volume + Use the OpenStack dashboard (horizon), or the cinder command to create volumes just as you normally would. For an encrypted volume use the LUKS tag, + for unencrypted leave the LUKS tag off. + + + Source your admin credentials: + $ source admin-openrc.sh + + + Create an unencrypted 1 GB test volume: + $ cinder create --display-name 'unencrypted volume' 1 ++--------------------------------+--------------------------------------+ +| Property | Value | ++--------------------------------+--------------------------------------+ +| attachments | [] | +| availability_zone | nova | +| bootable | false | +| created_at | 2014-08-10T01:24:03.000000 | +| description | None | +| encrypted | False | +| id | 081700fd-2357-44ff-860d-2cd78ad9c568 | +| metadata | {} | +| name | unencrypted volume | +| os-vol-host-attr:host | controller | +| os-vol-mig-status-attr:migstat | None | +| os-vol-mig-status-attr:name_id | None | +| os-vol-tenant-attr:tenant_id | 08fdea76c760475f82087a45dbe94918 | +| size | 1 | +| snapshot_id | None | +| source_volid | None | +| status | creating | +| user_id | 7cbc6b58b372439e8f70e2a9103f1332 | +| volume_type | None | ++--------------------------------+--------------------------------------+ + + + Create an encrypted 1 GB test volume: + $ cinder create --display-name 'encrypted volume' --volume-type LUKS 1 ++--------------------------------+--------------------------------------+ +| Property | Value | ++--------------------------------+--------------------------------------+ +| attachments | [] | +| availability_zone | nova | +| bootable | false | +| created_at | 2014-08-10T01:24:24.000000 | +| description | None | +| encrypted | True | +| id | 86060306-6f43-4c92-9ab8-ddcd83acd973 | +| metadata | {} | +| name | encrypted volume | +| os-vol-host-attr:host | controller | +| os-vol-mig-status-attr:migstat | None | +| os-vol-mig-status-attr:name_id | None | +| os-vol-tenant-attr:tenant_id | 08fdea76c760475f82087a45dbe94918 | +| size | 1 | +| snapshot_id | None | +| source_volid | None | +| status | creating | +| user_id | 7cbc6b58b372439e8f70e2a9103f1332 | +| volume_type | LUKS | ++--------------------------------+--------------------------------------+ + + + Notice the encrypted parameter; it will show True/False. The option is also shown for easy review. + +
+
+ Testing volume encryption + This is a simple test scenario to help validate your encryption. It assumes an LVM based Block Storage server. + Perform these steps after completing the volume encryption setup and creating the volume-type for LUKS as described in the preceding sections. + + + Create a VM: + $ nova boot --flavor m1.tiny --image cirros-0.3.1-x86_64-disk vm-test + + + Create two volumes, one encrypted and one not encrypted then attach them to your VM: + $ cinder create --display-name 'unencrypted volume' 1 +$ cinder create --display-name 'encrypted volume' --volume-type LUKS 1 +$ cinder list ++--------------------------------------+-----------+--------------------+------+-------------+----------+-------------+ +| ID | Status | Name | Size | Volume Type | Bootable | Attached to | ++--------------------------------------+-----------+--------------------+------+-------------+----------+-------------+ +| 64b48a79-5686-4542-9b52-d649b51c10a2 | available | unencrypted volume | 1 | None | false | | +| db50b71c-bf97-47cb-a5cf-b4b43a0edab6 | available | encrypted volume | 1 | LUKS | false | | ++--------------------------------------+-----------+--------------------+------+-------------+----------+-------------+ +$ nova volume-attach vm-test 64b48a79-5686-4542-9b52-d649b51c10a2 /dev/vdb +$ nova volume-attach vm-test db50b71c-bf97-47cb-a5cf-b4b43a0edab6 /dev/vdc + + + On the VM, send some text to the newly attached volumes and synchronize them: + # echo "Hello, world (unencrypted /dev/vdb)" >> /dev/vdb +# echo "Hello, world (encrypted /dev/vdc)" >> /dev/vdc +# sync && sleep 2 +# sync && sleep 2 + + + On the system hosting cinder volume services, synchronize to flush the I/O cache then test to see if your strings can be found: + # sync && sleep 2 +# sync && sleep 2 +# strings /dev/stack-volumes/volume-* | grep "Hello" +Hello, world (unencrypted /dev/vdb) + + + In the above example you see that the search returns the string written to the unencrypted volume, but not the encrypted one. +
+
\ No newline at end of file diff --git a/doc/config-reference/ch_blockstorageconfigure.xml b/doc/config-reference/ch_blockstorageconfigure.xml index 735a7b42ed..f8b4f541a5 100644 --- a/doc/config-reference/ch_blockstorageconfigure.xml +++ b/doc/config-reference/ch_blockstorageconfigure.xml @@ -23,6 +23,7 @@ +