ceph/doc/radosgw/s3/authentication.rst

   1 =========================
   2  Authentication and ACLs
   3 =========================
   4
   5 Requests to the RADOS Gateway (RGW) can be either authenticated or
   6 unauthenticated. RGW assumes unauthenticated requests are sent by an anonymous
   7 user. RGW supports canned ACLs.
   8
   9 Authentication
  10 --------------
  11 Authenticating a request requires including an access key and a Hash-based
  12 Message Authentication Code (HMAC) in the request before it is sent to the
  13 RGW server. RGW uses an S3-compatible authentication approach.
  14
  15 ::
  16
  17         HTTP/1.1
  18         PUT /buckets/bucket/object.mpeg
  19         Host: cname.domain.com
  20         Date: Mon, 2 Jan 2012 00:01:01 +0000
  21         Content-Encoding: mpeg
  22         Content-Length: 9999999
  23
  24         Authorization: AWS {access-key}:{hash-of-header-and-secret}
  25
  26 In the foregoing example, replace ``{access-key}`` with the value for your access
  27 key ID followed by a colon (``:``). Replace ``{hash-of-header-and-secret}`` with
  28 a hash of the header string and the secret corresponding to the access key ID.
  29
  30 To generate the hash of the header string and secret, you must:
  31
  32 #. Get the value of the header string.
  33 #. Normalize the request header string into canonical form.
  34 #. Generate an HMAC using a SHA-1 hashing algorithm.
  35    See `RFC 2104`_ and `HMAC`_ for details.
  36 #. Encode the ``hmac`` result as base-64.
  37
  38 To normalize the header into canonical form:
  39
  40 #. Get all fields beginning with ``x-amz-``.
  41 #. Ensure that the fields are all lowercase.
  42 #. Sort the fields lexicographically.
  43 #. Combine multiple instances of the same field name into a
  44    single field and separate the field values with a comma.
  45 #. Replace white space and line breaks in field values with a single space.
  46 #. Remove white space before and after colons.
  47 #. Append a new line after each field.
  48 #. Merge the fields back into the header.
  49
  50 Replace the ``{hash-of-header-and-secret}`` with the base-64 encoded HMAC string.
  51
  52 Authentication against OpenStack Keystone
  53 -----------------------------------------
  54
  55 In a radosgw instance that is configured with authentication against
  56 OpenStack Keystone, it is possible to use Keystone as an authoritative
  57 source for S3 API authentication. To do so, you must set:
  58
  59 * the ``rgw keystone`` configuration options explained in :doc:`../keystone`,
  60 * ``rgw s3 auth use keystone = true``.
  61
  62 In addition, a user wishing to use the S3 API must obtain an AWS-style
  63 access key and secret key. They can do so with the ``openstack ec2
  64 credentials create`` command::
  65
  66   $ openstack --os-interface public ec2 credentials create
  67   +------------+---------------------------------------------------------------------------------------------------------------------------------------------+
  68   | Field      | Value                                                                                                                                       |
  69   +------------+---------------------------------------------------------------------------------------------------------------------------------------------+
  70   | access     | c921676aaabbccdeadbeef7e8b0eeb2c                                                                                                            |
  71   | links      | {u'self': u'https://auth.example.com:5000/v3/users/7ecbebaffeabbddeadbeefa23267ccbb24/credentials/OS-EC2/c921676aaabbccdeadbeef7e8b0eeb2c'} |
  72   | project_id | 5ed51981aab4679851adeadbeef6ebf7                                                                                                            |
  73   | secret     | ********************************                                                                                                            |
  74   | trust_id   | None                                                                                                                                        |
  75   | user_id    | 7ecbebaffeabbddeadbeefa23267cc24                                                                                                            |
  76   +------------+---------------------------------------------------------------------------------------------------------------------------------------------+
  77
  78 The thus-generated access and secret key can then be used for S3 API
  79 access to radosgw.
  80
  81 .. note:: Consider that most production radosgw deployments
  82           authenticating against OpenStack Keystone are also set up
  83           for :doc:`../multitenancy`, for which special
  84           considerations apply with respect to S3 signed URLs and
  85           public read ACLs.
  86
  87 Access Control Lists (ACLs)
  88 ---------------------------
  89
  90 RGW supports S3-compatible ACL functionality. An ACL is a list of access grants
  91 that specify which operations a user can perform on a bucket or on an object.
  92 Each grant has a different meaning when applied to a bucket versus applied to
  93 an object:
  94
  95 +------------------+--------------------------------------------------------+----------------------------------------------+
  96 | Permission       | Bucket                                                 | Object                                       |
  97 +==================+========================================================+==============================================+
  98 | ``READ``         | Grantee can list the objects in the bucket.            | Grantee can read the object.                 |
  99 +------------------+--------------------------------------------------------+----------------------------------------------+
 100 | ``WRITE``        | Grantee can write or delete objects in the bucket.     | N/A                                          |
 101 +------------------+--------------------------------------------------------+----------------------------------------------+
 102 | ``READ_ACP``     | Grantee can read bucket ACL.                           | Grantee can read the object ACL.             |
 103 +------------------+--------------------------------------------------------+----------------------------------------------+
 104 | ``WRITE_ACP``    | Grantee can write bucket ACL.                          | Grantee can write to the object ACL.         |
 105 +------------------+--------------------------------------------------------+----------------------------------------------+
 106 | ``FULL_CONTROL`` | Grantee has full permissions for object in the bucket. | Grantee can read or write to the object ACL. |
 107 +------------------+--------------------------------------------------------+----------------------------------------------+
 108
 109 Internally, S3 operations are mapped to ACL permissions thus:
 110
 111 +---------------------------------------+---------------+
 112 | Operation                             | Permission    |
 113 +=======================================+===============+
 114 | ``s3:GetObject``                      | ``READ``      |
 115 +---------------------------------------+---------------+
 116 | ``s3:GetObjectTorrent``               | ``READ``      |
 117 +---------------------------------------+---------------+
 118 | ``s3:GetObjectVersion``               | ``READ``      |
 119 +---------------------------------------+---------------+
 120 | ``s3:GetObjectVersionTorrent``        | ``READ``      |
 121 +---------------------------------------+---------------+
 122 | ``s3:GetObjectTagging``               | ``READ``      |
 123 +---------------------------------------+---------------+
 124 | ``s3:GetObjectVersionTagging``        | ``READ``      |
 125 +---------------------------------------+---------------+
 126 | ``s3:ListAllMyBuckets``               | ``READ``      |
 127 +---------------------------------------+---------------+
 128 | ``s3:ListBucket``                     | ``READ``      |
 129 +---------------------------------------+---------------+
 130 | ``s3:ListBucketMultipartUploads``     | ``READ``      |
 131 +---------------------------------------+---------------+
 132 | ``s3:ListBucketVersions``             | ``READ``      |
 133 +---------------------------------------+---------------+
 134 | ``s3:ListMultipartUploadParts``       | ``READ``      |
 135 +---------------------------------------+---------------+
 136 | ``s3:AbortMultipartUpload``           | ``WRITE``     |
 137 +---------------------------------------+---------------+
 138 | ``s3:CreateBucket``                   | ``WRITE``     |
 139 +---------------------------------------+---------------+
 140 | ``s3:DeleteBucket``                   | ``WRITE``     |
 141 +---------------------------------------+---------------+
 142 | ``s3:DeleteObject``                   | ``WRITE``     |
 143 +---------------------------------------+---------------+
 144 | ``s3:s3DeleteObjectVersion``          | ``WRITE``     |
 145 +---------------------------------------+---------------+
 146 | ``s3:PutObject``                      | ``WRITE``     |
 147 +---------------------------------------+---------------+
 148 | ``s3:PutObjectTagging``               | ``WRITE``     |
 149 +---------------------------------------+---------------+
 150 | ``s3:PutObjectVersionTagging``        | ``WRITE``     |
 151 +---------------------------------------+---------------+
 152 | ``s3:DeleteObjectTagging``            | ``WRITE``     |
 153 +---------------------------------------+---------------+
 154 | ``s3:DeleteObjectVersionTagging``     | ``WRITE``     |
 155 +---------------------------------------+---------------+
 156 | ``s3:RestoreObject``                  | ``WRITE``     |
 157 +---------------------------------------+---------------+
 158 | ``s3:GetAccelerateConfiguration``     | ``READ_ACP``  |
 159 +---------------------------------------+---------------+
 160 | ``s3:GetBucketAcl``                   | ``READ_ACP``  |
 161 +---------------------------------------+---------------+
 162 | ``s3:GetBucketCORS``                  | ``READ_ACP``  |
 163 +---------------------------------------+---------------+
 164 | ``s3:GetBucketLocation``              | ``READ_ACP``  |
 165 +---------------------------------------+---------------+
 166 | ``s3:GetBucketLogging``               | ``READ_ACP``  |
 167 +---------------------------------------+---------------+
 168 | ``s3:GetBucketNotification``          | ``READ_ACP``  |
 169 +---------------------------------------+---------------+
 170 | ``s3:GetBucketPolicy``                | ``READ_ACP``  |
 171 +---------------------------------------+---------------+
 172 | ``s3:GetBucketRequestPayment``        | ``READ_ACP``  |
 173 +---------------------------------------+---------------+
 174 | ``s3:GetBucketTagging``               | ``READ_ACP``  |
 175 +---------------------------------------+---------------+
 176 | ``s3:GetBucketVersioning``            | ``READ_ACP``  |
 177 +---------------------------------------+---------------+
 178 | ``s3:GetBucketWebsite``               | ``READ_ACP``  |
 179 +---------------------------------------+---------------+
 180 | ``s3:GetLifecycleConfiguration``      | ``READ_ACP``  |
 181 +---------------------------------------+---------------+
 182 | ``s3:GetObjectAcl``                   | ``READ_ACP``  |
 183 +---------------------------------------+---------------+
 184 | ``s3:GetObjectVersionAcl``            | ``READ_ACP``  |
 185 +---------------------------------------+---------------+
 186 | ``s3:GetReplicationConfiguration``    | ``READ_ACP``  |
 187 +---------------------------------------+---------------+
 188 | ``s3:DeleteBucketPolicy``             | ``WRITE_ACP`` |
 189 +---------------------------------------+---------------+
 190 | ``s3:DeleteBucketWebsite``            | ``WRITE_ACP`` |
 191 +---------------------------------------+---------------+
 192 | ``s3:DeleteReplicationConfiguration`` | ``WRITE_ACP`` |
 193 +---------------------------------------+---------------+
 194 | ``s3:PutAccelerateConfiguration``     | ``WRITE_ACP`` |
 195 +---------------------------------------+---------------+
 196 | ``s3:PutBucketAcl``                   | ``WRITE_ACP`` |
 197 +---------------------------------------+---------------+
 198 | ``s3:PutBucketCORS``                  | ``WRITE_ACP`` |
 199 +---------------------------------------+---------------+
 200 | ``s3:PutBucketLogging``               | ``WRITE_ACP`` |
 201 +---------------------------------------+---------------+
 202 | ``s3:PutBucketNotification``          | ``WRITE_ACP`` |
 203 +---------------------------------------+---------------+
 204 | ``s3:PutBucketPolicy``                | ``WRITE_ACP`` |
 205 +---------------------------------------+---------------+
 206 | ``s3:PutBucketRequestPayment``        | ``WRITE_ACP`` |
 207 +---------------------------------------+---------------+
 208 | ``s3:PutBucketTagging``               | ``WRITE_ACP`` |
 209 +---------------------------------------+---------------+
 210 | ``s3:PutPutBucketVersioning``         | ``WRITE_ACP`` |
 211 +---------------------------------------+---------------+
 212 | ``s3:PutBucketWebsite``               | ``WRITE_ACP`` |
 213 +---------------------------------------+---------------+
 214 | ``s3:PutLifecycleConfiguration``      | ``WRITE_ACP`` |
 215 +---------------------------------------+---------------+
 216 | ``s3:PutObjectAcl``                   | ``WRITE_ACP`` |
 217 +---------------------------------------+---------------+
 218 | ``s3:PutObjectVersionAcl``            | ``WRITE_ACP`` |
 219 +---------------------------------------+---------------+
 220 | ``s3:PutReplicationConfiguration``    | ``WRITE_ACP`` |
 221 +---------------------------------------+---------------+
 222
 223 Some mappings, (e.g. ``s3:CreateBucket`` to ``WRITE``) are not
 224 applicable to S3 operation, but are required to allow Swift and S3 to
 225 access the same resources when things like Swift user ACLs are in
 226 play. This is one of the many reasons that you should use S3 bucket
 227 policies rather than S3 ACLs when possible.
 228
 229
 230 .. _RFC 2104: http://www.ietf.org/rfc/rfc2104.txt
 231 .. _HMAC: https://en.wikipedia.org/wiki/HMAC