doc: Updated authentication with header canonicalization.

Signed-off-by: John Wilkins <john.wilkins@inktank.com>

1 files changed, 34 insertions, 26 deletions

diff --git a/doc/api/s3/authentication.rst b/doc/api/s3/authentication.rst
index d443c0ac0eb..b1875385bf9 100644
--- a/doc/api/s3/authentication.rst
+++ b/doc/api/s3/authentication.rst
@@ -1,15 +1,16 @@
-Authentication and ACLs
-=======================
-Requests to the RADOS Gateway (RGW) can be either authenticated or unauthenticated.
-RGW assumes unauthenticated requests are sent by an anonymous user. RGW supports
-canned ACLs.
+=========================
+ Authentication and ACLs
+=========================
+
+Requests to the RADOS Gateway (RGW) can be either authenticated or 
+unauthenticated. RGW assumes unauthenticated requests are sent by an anonymous 
+user. RGW supports canned ACLs.
 
 Authentication
 --------------
-
-Authenticating a request requires including an access key and a Hash-based Message Authentication Code (HMAC)
-in the request before it is sent to the RGW server. RGW uses an S3-compatible authentication
-approach. The HTTP header signing is similar to OAuth 1.0, but avoids the complexity associated with the 3-legged OAuth 1.0 method.
+Authenticating a request requires including an access key and a Hash-based 
+Message Authentication Code (HMAC) in the request before it is sent to the 
+RGW server. RGW uses an S3-compatible authentication approach. 
 
 ::
 
@@ -17,31 +18,34 @@ approach. The HTTP header signing is similar to OAuth 1.0, but avoids the comple
 	PUT /buckets/bucket/object.mpeg
 	Host: cname.domain.com
 	Date: Mon, 2 Jan 2012 00:01:01 +0000
+	Content-Encoding: mpeg	
 	Content-Length: 9999999
-	Content-Encoding: mpeg
 
 	Authorization: AWS {access-key}:{hash-of-header-and-secret}
 
-In the foregoing example, replace ``{access-key}`` with the value for your access key ID followed by
-a colon (``:``). Replace ``{hash-of-header-and-secret}`` with a hash of the header string and the secret
-corresponding to the access key ID.
+In the foregoing example, replace ``{access-key}`` with the value for your access 
+key ID followed by a colon (``:``). Replace ``{hash-of-header-and-secret}`` with 
+a hash of the header string and the secret corresponding to the access key ID.
 
 To generate the hash of the header string and secret, you must:
 
-1. Get the value of the header string and the secret::
-
-	str = "HTTP/1.1\nPUT /buckets/bucket/object.mpeg\nHost: cname.domain.com\n
-	Date: Mon, 2 Jan 2012 00:01:01 +0000\nContent-Length: 9999999\nContent-Encoding: mpeg";
-
-	secret = "valueOfSecret";
+#. Get the value of the header string.
+#. Normalize the request header string into canonical form. 
+#. Generate an HMAC using a SHA-1 hashing algorithm.
+   See `RFC 2104`_ and `HMAC`_ for details.
+#. Encode the ``hmac`` result as base-64.
 
-2. Generate an HMAC using a SHA-1 hashing algorithm. ::
+To normalize the header into canonical form: 
 
-    hmac = object.hmac-sha1(str, secret);
-
-3. Encode the ``hmac`` result using base-64. ::
-
-    encodedHmac = someBase64Encoder.encode(hmac);
+#. Get all fields beginning with ``x-amz-``.
+#. Ensure that the fields are all lowercase.
+#. Sort the fields lexicographically. 
+#. Combine multiple instances of the same field name into a 
+   single field and separate the field values with a comma.
+#. Replace white space and line breaks in field values with a single space.
+#. Remove white space before and after colons.
+#. Append a new line after each field.
+#. Merge the fields back into the header.
 
 Replace the ``{hash-of-header-and-secret}`` with the base-64 encoded HMAC string.
 
@@ -50,7 +54,8 @@ Access Control Lists (ACLs)
 
 RGW supports S3-compatible ACL functionality. An ACL is a list of access grants
 that specify which operations a user can perform on a bucket or on an object.
-Each grant has a different meaning when applied to a bucket versus applied to an object:
+Each grant has a different meaning when applied to a bucket versus applied to 
+an object:
 
 +------------------+--------------------------------------------------------+----------------------------------------------+
 | Permission       | Bucket                                                 | Object                                       |
@@ -65,3 +70,6 @@ Each grant has a different meaning when applied to a bucket versus applied to an
 +------------------+--------------------------------------------------------+----------------------------------------------+
 | ``FULL_CONTROL`` | Grantee has full permissions for object in the bucket. | Grantee can read or write to the object ACL. |
 +------------------+--------------------------------------------------------+----------------------------------------------+
+
+.. _RFC 2104: http://www.ietf.org/rfc/rfc2104.txt
+.. _HMAC: http://en.wikipedia.org/wiki/HMAC