From: Casey Bodley Date: Wed, 15 Feb 2017 23:47:32 +0000 (-0500) Subject: doc: rgw server-side encryption and barbican X-Git-Tag: v12.0.2~33^2 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=a1cf8ac4cd0775fc4c7c638baf8f007a673c0425;p=ceph.git doc: rgw server-side encryption and barbican Signed-off-by: Adam Kupczyk Signed-off-by: Casey Bodley --- diff --git a/doc/images/rgw-encryption-barbican.png b/doc/images/rgw-encryption-barbican.png new file mode 100644 index 00000000000..e3c10c4a7b7 Binary files /dev/null and b/doc/images/rgw-encryption-barbican.png differ diff --git a/doc/radosgw/barbican.rst b/doc/radosgw/barbican.rst new file mode 100644 index 00000000000..557c956042f --- /dev/null +++ b/doc/radosgw/barbican.rst @@ -0,0 +1,119 @@ +============================== +OpenStack Barbican Integration +============================== + +OpenStack `Barbican`_ can be used as a secure key management service for +`Server-Side Encryption`_. + +.. image:: ../images/rgw-encryption-barbican.png + +#. `Configure Keystone`_ +#. `Create a Keystone user`_ +#. `Configure the Ceph Object Gateway`_ +#. `Create a key in Barbican`_ + +Configure Keystone +================== + +Barbican depends on Keystone for authorization and access control of its keys. + +See `OpenStack Keystone Integration`_. + +Create a Keystone user +====================== + +Create a new user that will be used by the Ceph Object Gateway to retrieve +keys. + +For example:: + + user = rgwcrypt-user + pass = rgwcrypt-password + tenant = rgwcrypt + +See OpenStack documentation for `Manage projects, users, and roles`_. + +Create a key in Barbican +======================== + +See Barbican documentation for `How to Create a Secret`_. Requests to +Barbican must include a valid Keystone token in the ``X-Auth-Token`` header. + +Example request:: + + POST /v1/secrets HTTP/1.1 + Host: barbican.example.com:9311 + Accept: */* + Content-Type: application/json + X-Auth-Token: 7f7d588dd29b44df983bc961a6b73a10 + Content-Length: 299 + + { + "name": "my-key", + "expiration": "2016-12-28T19:14:44.180394", + "algorithm": "aes", + "bit_length": 256, + "mode": "cbc", + "payload": "6b+WOZ1T3cqZMxgThRcXAQBrS5mXKdDUphvpxptl9/4=", + "payload_content_type": "application/octet-stream", + "payload_content_encoding": "base64" + } + +Response:: + + {"secret_ref": "http://barbican.example.com:9311/v1/secrets/d1e7ef3b-f841-4b7c-90b2-b7d90ca2d723"} + +In the response, ``d1e7ef3b-f841-4b7c-90b2-b7d90ca2d723`` is the key id that +can be used in any `SSE-KMS`_ request. + +This newly created key is not accessible by user ``rgwcrypt-user``. This +privilege must be added with an ACL. + +Example request (assuming that the Keystone id of ``rgwcrypt-user`` is +``906aa90bd8a946c89cdff80d0869460f``):: + + PUT /v1/secrets/d1e7ef3b-f841-4b7c-90b2-b7d90ca2d723/acl HTTP/1.1 + Host: barbican.example.com:9311 + Accept: */* + Content-Type: application/json + X-Auth-Token: 7f7d588dd29b44df983bc961a6b73a10 + Content-Length: 101 + + { + "read":{ + "users":[ "906aa90bd8a946c89cdff80d0869460f" ], + "project-access": true + } + } + +Response:: + + {"acl_ref": "http://barbican.example.com:9311/v1/secrets/d1e7ef3b-f841-4b7c-90b2-b7d90ca2d723/acl"} + +Configure the Ceph Object Gateway +================================= + +Edit the Ceph configuration file to add information about the Barbican server +and Keystone user:: + + rgw barbican url = http://barbican.example.com:9311 + rgw keystone barbican user = rgwcrypt-user + rgw keystone barbican password = rgwcrypt-password + +When using Keystone API version 2:: + + rgw keystone barbican tenant = rgwcrypt + +When using API version 3:: + + rgw keystone barbican project + rgw keystone barbican domain + + +.. _Barbican: https://wiki.openstack.org/wiki/Barbican +.. _Server-Side Encryption: ../encryption +.. _OpenStack Keystone Integration: ../keystone +.. _Manage projects, users, and roles: https://docs.openstack.org/admin-guide/cli-manage-projects-users-and-roles.html#create-a-user +.. _How to Create a Secret: https://developer.openstack.org/api-guide/key-manager/secrets.html#how-to-create-a-secret +.. _SSE-KMS: http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingKMSEncryption.html +.. _How to Set/Replace ACL: https://developer.openstack.org/api-guide/key-manager/acls.html#how-to-set-replace-acl diff --git a/doc/radosgw/config-ref.rst b/doc/radosgw/config-ref.rst index b5e0ca5ed9d..8a9c39e8588 100644 --- a/doc/radosgw/config-ref.rst +++ b/doc/radosgw/config-ref.rst @@ -1115,7 +1115,53 @@ Keystone Settings :Type: Boolean :Default: ``true`` +Barbican Settings +================= + +``rgw barbican url`` + +:Description: The URL for the Barbican server. +:Type: String +:Default: None + +``rgw keystone barbican user`` + +:Description: The name of the OpenStack user with access to the `Barbican`_ + secrets used for `Encryption`_. +:Type: String +:Default: None + +``rgw keystone barbican password`` + +:Description: The password associated with the `Barbican`_ user. +:Type: String +:Default: None + +``rgw keystone barbican tenant`` + +:Description: The name of the OpenStack tenant associated with the `Barbican`_ + user when using OpenStack Identity API v2. +:Type: String +:Default: None + +``rgw keystone barbican project`` + +:Description: The name of the OpenStack project associated with the `Barbican`_ + user when using OpenStack Identity API v3. +:Type: String +:Default: None + +``rgw keystone barbican domain`` + +:Description: The name of the OpenStack domain associated with the `Barbican`_ + user when using OpenStack Identity API v3. +:Type: String +:Default: None + + .. _Architecture: ../../architecture#data-striping .. _Pool Configuration: ../../rados/configuration/pool-pg-config-ref/ .. _Cluster Pools: ../../rados/operations/pools .. _Rados cluster handles: ../../rados/api/librados-intro/#step-2-configuring-a-cluster-handle +.. _Barbican: ../barbican +.. _Encryption: ../encryption diff --git a/doc/radosgw/encryption.rst b/doc/radosgw/encryption.rst new file mode 100644 index 00000000000..0097b1b0081 --- /dev/null +++ b/doc/radosgw/encryption.rst @@ -0,0 +1,56 @@ +========== +Encryption +========== + +.. versionadded:: Luminous + +The Ceph Object Gateway supports server-side encryption of uploaded objects, +with 3 options for the management of encryption keys. Server-side encryption +means that the data is sent over HTTP in its unencrypted form, and the Ceph +Object Gateway stores that data in the Ceph Storage Cluster in encrypted form. + +Customer-Provided Keys +====================== + +In this mode, the client passes an encryption key along with each request to +read or write encrypted data. It is the client's responsibility to manage those +keys and remember which key was used to encrypt each object. + +This is implemented in S3 according to the `Amazon SSE-C`_ specification. + +As all key management is handled by the client, no special configuration is +needed to support this encryption mode. + +Key Management Service +====================== + +This mode allows keys to be stored in a secure key management service and +retrieved on demand by the Ceph Object Gateway to service requests to encrypt +or decrypt data. + +This is implemented in S3 according to the `Amazon SSE-KMS`_ specification. + +In principle, any key management service could be used here, but currently +only integration with `Barbican`_ is implemented. + +See `OpenStack Barbican Integration`_. + +Automatic Encryption (for testing only) +======================================= + +A ``rgw crypt default encryption key`` can be set in ceph.conf to force the +encryption of all objects that do not otherwise specify an encryption mode. + +The configuration expects a base64-encoded 256 bit key. For example:: + + rgw crypt default encryption key = 4YSmvJtBv0aZ7geVgAsdpRnLBEwWSWlMIGnRS8a9TSA= + +.. important:: This mode is for diagnostic purposes only! The ceph configuration + file is not a secure method for storing encryption keys. Keys that are + accidentally exposed in this way should be considered compromised. + + +.. _Amazon SSE-C: https://docs.aws.amazon.com/AmazonS3/latest/dev/ServerSideEncryptionCustomerKeys.html +.. _Amazon SSE-KMS: http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingKMSEncryption.html +.. _Barbican: https://wiki.openstack.org/wiki/Barbican +.. _OpenStack Barbican Integration: ../barbican diff --git a/doc/radosgw/index.rst b/doc/radosgw/index.rst index e2f71d4c15a..7bf08cdbe97 100644 --- a/doc/radosgw/index.rst +++ b/doc/radosgw/index.rst @@ -47,8 +47,10 @@ you may write data with one API and retrieve it with the other. Admin Ops API Python binding OpenStack Keystone Integration + OpenStack Barbican Integration Multi-tenancy Compression + Server-Side Encryption Data Layout in RADOS Upgrade to Older Versions of Jewel troubleshooting