src/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 Access Control Lists (ACLs)
  53 ---------------------------
  54
  55 RGW supports S3-compatible ACL functionality. An ACL is a list of access grants
  56 that specify which operations a user can perform on a bucket or on an object.
  57 Each grant has a different meaning when applied to a bucket versus applied to
  58 an object:
  59
  60 +------------------+--------------------------------------------------------+----------------------------------------------+
  61 | Permission       | Bucket                                                 | Object                                       |
  62 +==================+========================================================+==============================================+
  63 | ``READ``         | Grantee can list the objects in the bucket.            | Grantee can read the object.                 |
  64 +------------------+--------------------------------------------------------+----------------------------------------------+
  65 | ``WRITE``        | Grantee can write or delete objects in the bucket.     | N/A                                          |
  66 +------------------+--------------------------------------------------------+----------------------------------------------+
  67 | ``READ_ACP``     | Grantee can read bucket ACL.                           | Grantee can read the object ACL.             |
  68 +------------------+--------------------------------------------------------+----------------------------------------------+
  69 | ``WRITE_ACP``    | Grantee can write bucket ACL.                          | Grantee can write to the object ACL.         |
  70 +------------------+--------------------------------------------------------+----------------------------------------------+
  71 | ``FULL_CONTROL`` | Grantee has full permissions for object in the bucket. | Grantee can read or write to the object ACL. |
  72 +------------------+--------------------------------------------------------+----------------------------------------------+
  73
  74 .. _RFC 2104: http://www.ietf.org/rfc/rfc2104.txt
  75 .. _HMAC: http://en.wikipedia.org/wiki/HMAC