src/ceph/doc/radosgw/barbican.rst

   1 ==============================
   2 OpenStack Barbican Integration
   3 ==============================
   4
   5 OpenStack `Barbican`_ can be used as a secure key management service for
   6 `Server-Side Encryption`_.
   7
   8 .. image:: ../images/rgw-encryption-barbican.png
   9
  10 #. `Configure Keystone`_
  11 #. `Create a Keystone user`_
  12 #. `Configure the Ceph Object Gateway`_
  13 #. `Create a key in Barbican`_
  14
  15 Configure Keystone
  16 ==================
  17
  18 Barbican depends on Keystone for authorization and access control of its keys.
  19
  20 See `OpenStack Keystone Integration`_.
  21
  22 Create a Keystone user
  23 ======================
  24
  25 Create a new user that will be used by the Ceph Object Gateway to retrieve
  26 keys.
  27
  28 For example::
  29
  30    user = rgwcrypt-user
  31    pass = rgwcrypt-password
  32    tenant = rgwcrypt
  33
  34 See OpenStack documentation for `Manage projects, users, and roles`_.
  35
  36 Create a key in Barbican
  37 ========================
  38
  39 See Barbican documentation for `How to Create a Secret`_. Requests to
  40 Barbican must include a valid Keystone token in the ``X-Auth-Token`` header.
  41
  42 Example request::
  43
  44    POST /v1/secrets HTTP/1.1
  45    Host: barbican.example.com:9311
  46    Accept: */*
  47    Content-Type: application/json
  48    X-Auth-Token: 7f7d588dd29b44df983bc961a6b73a10
  49    Content-Length: 299
  50
  51    {
  52        "name": "my-key",
  53        "expiration": "2016-12-28T19:14:44.180394",
  54        "algorithm": "aes",
  55        "bit_length": 256,
  56        "mode": "cbc",
  57        "payload": "6b+WOZ1T3cqZMxgThRcXAQBrS5mXKdDUphvpxptl9/4=",
  58        "payload_content_type": "application/octet-stream",
  59        "payload_content_encoding": "base64"
  60    }
  61
  62 Response::
  63
  64    {"secret_ref": "http://barbican.example.com:9311/v1/secrets/d1e7ef3b-f841-4b7c-90b2-b7d90ca2d723"}
  65
  66 In the response, ``d1e7ef3b-f841-4b7c-90b2-b7d90ca2d723`` is the key id that
  67 can be used in any `SSE-KMS`_ request.
  68
  69 This newly created key is not accessible by user ``rgwcrypt-user``. This
  70 privilege must be added with an ACL. See `How to Set/Replace ACL`_ for more
  71 details.
  72
  73 Example request (assuming that the Keystone id of ``rgwcrypt-user`` is
  74 ``906aa90bd8a946c89cdff80d0869460f``)::
  75
  76    PUT /v1/secrets/d1e7ef3b-f841-4b7c-90b2-b7d90ca2d723/acl HTTP/1.1
  77    Host: barbican.example.com:9311
  78    Accept: */*
  79    Content-Type: application/json
  80    X-Auth-Token: 7f7d588dd29b44df983bc961a6b73a10
  81    Content-Length: 101
  82
  83    {
  84        "read":{
  85        "users":[ "906aa90bd8a946c89cdff80d0869460f" ],
  86        "project-access": true
  87        }
  88    }
  89
  90 Response::
  91
  92    {"acl_ref": "http://barbican.example.com:9311/v1/secrets/d1e7ef3b-f841-4b7c-90b2-b7d90ca2d723/acl"}
  93
  94 Configure the Ceph Object Gateway
  95 =================================
  96
  97 Edit the Ceph configuration file to add information about the Barbican server
  98 and Keystone user::
  99
 100    rgw barbican url = http://barbican.example.com:9311
 101    rgw keystone barbican user = rgwcrypt-user
 102    rgw keystone barbican password = rgwcrypt-password
 103
 104 When using Keystone API version 2::
 105
 106    rgw keystone barbican tenant = rgwcrypt
 107
 108 When using API version 3::
 109
 110    rgw keystone barbican project
 111    rgw keystone barbican domain
 112
 113
 114 .. _Barbican: https://wiki.openstack.org/wiki/Barbican
 115 .. _Server-Side Encryption: ../encryption
 116 .. _OpenStack Keystone Integration: ../keystone
 117 .. _Manage projects, users, and roles: https://docs.openstack.org/admin-guide/cli-manage-projects-users-and-roles.html#create-a-user
 118 .. _How to Create a Secret: https://developer.openstack.org/api-guide/key-manager/secrets.html#how-to-create-a-secret
 119 .. _SSE-KMS: http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingKMSEncryption.html
 120 .. _How to Set/Replace ACL: https://developer.openstack.org/api-guide/key-manager/acls.html#how-to-set-replace-acl