Document swift3 compatibility

Change-Id: I56f879f87a0f0bda6089c509c111dc14f223e5be
Signed-off-by: Prashanth Pai <ppai@redhat.com>

README.md

@@ -70,3 +70,16 @@ Web Admin Install
     -U .super_admin:.super_admin -K swauthkey upload .webadmin .``
 
 3)  Open ``http://127.0.0.1:8080/auth/`` in your browser.
+
+
+Swift3 Middleware Compatibility
+-------------------------------
+[**Swift3 middleware**](https://github.com/openstack/swift3) can be used with
+swauth when `auth_type` in swauth is configured to be *Plaintext* (default).
+
+    [pipeline:main]
+    pipeline = catch_errors cache swift3 swauth proxy-server
+
+It can be used with `auth_type` set to Sha1/Sha512 too but with certain caveats.
+Refer to swift3 compatibility [section](https://swauth.readthedocs.org/en/latest/#swift3-middleware-compatibility)
+in documentation for further details

doc/source/index.rst

@@ -122,6 +122,26 @@ Web Admin Install
 3)  Open ``http[s]://<host>:<port>/auth/`` in your browser.
 
 
+Swift3 Middleware Compatibility
+-------------------------------
+`Swift3 middleware <https://github.com/openstack/swift3>`_ can be used with
+swauth when `auth_type` in swauth is configured to be *Plaintext* (default)::
+
+    [pipeline:main]
+    pipeline = catch_errors cache swift3 swauth proxy-server
+
+The AWS S3 client uses password in plaintext to
+`compute HMAC signature <https://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html>`_
+When `auth_type` in swauth is configured to be *Sha1* or *Sha512*, swauth
+can only use the stored hashed password to compute HMAC signature. This results
+in signature mismatch although the user credentials are correct.
+
+When `auth_type` is **not** *Plaintext*, the only way for S3 clients to
+authenticate is by giving SHA1/SHA512 of password as input to it's HMAC
+function. In this case, the S3 clients will have to know `auth_type` and
+`salt` beforehand.
+
+
 Contents
 --------