Merge "Document access control lists (ACLs)"

5 files changed, 400 insertions, 84 deletions

diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 8140c9fff..b1ae69be5 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -259,6 +259,31 @@ Transfer-Encoding:
   in: header
   required: false
   type: string
+X-Account-Access-Control_req:
+  description: |
+    **Note**: `X-Account-Access-Control` is not supported by Keystone auth.
+
+    Sets an account access control list (ACL) that grants access to
+    containers and objects in the account.
+    See `Account ACLs
+    <http://docs.openstack.org/developer/swift/overview_acl.html#account-acls>`_
+    for more information.
+  in: header
+  required: false
+  type: string
+X-Account-Access-Control_resp:
+  description: |
+    **Note**: `X-Account-Access-Control` is not supported by Keystone auth.
+
+    The account access control list (ACL) that grants access to
+    containers and objects in the account.
+    If there is no ACL, this header is not returned by this operation.
+    See `Account ACLs
+    <http://docs.openstack.org/developer/swift/overview_acl.html#account-acls>`_
+    for more information.
+  in: header
+  required: false
+  type: string
 X-Account-Bytes-Used:
   description: |
     The total number of bytes that are stored in
@@ -528,7 +553,9 @@ X-Container-Read:
     or to perform a GET or HEAD operation on the container itself.
 
     The format and scope of the ACL is dependent on the authorization system
-    used by the Object Storage service.
+    used by the Object Storage service. See `Container ACLs
+    <http://docs.openstack.org/developer/swift/overview_acl.html#container-acls>`_
+    for more information.
   in: header
   required: false
   type: string
@@ -536,6 +563,9 @@ X-Container-Read_resp:
   description: |
     The ACL that grants read access. If there is no ACL, this
     header is not returned by this operation.
+    See `Container ACLs
+    <http://docs.openstack.org/developer/swift/overview_acl.html#container-acls>`_
+    for more information.
   in: header
   required: false
   type: string
@@ -583,7 +613,9 @@ X-Container-Write:
     metadata.
 
     The format of the ACL is dependent on the authorization system
-    used by the Object Storage service.
+    used by the Object Storage service.  See `Container ACLs
+    <http://docs.openstack.org/developer/swift/overview_acl.html#container-acls>`_
+    for more information.
 
   in: header
   required: false
@@ -592,6 +624,9 @@ X-Container-Write_resp:
   description:
     The ACL that grants write access. If there is no ACL,
     this header is not returned by this operation.
+    See `Container ACLs
+    <http://docs.openstack.org/developer/swift/overview_acl.html#container-acls>`_
+    for more information.
   in: header
   required: false
   type: string
diff --git a/api-ref/source/storage-account-services.inc b/api-ref/source/storage-account-services.inc
index 8834c1a6d..b3c19b765 100644
--- a/api-ref/source/storage-account-services.inc
+++ b/api-ref/source/storage-account-services.inc
@@ -109,6 +109,7 @@ Response Parameters
    - X-Account-Storage-Policy-name-Container-Count: X-Account-Storage-Policy-name-Container-Count
    - X-Account-Storage-Policy-name-Object-Count: X-Account-Storage-Policy-name-Object-Count
    - X-Account-Meta-Quota-Bytes: X-Account-Meta-Quota-Bytes_resp
+   - X-Account-Access-Control: X-Account-Access-Control_resp
    - Content-Type: Content-Type_listing_resp
    - count: count
    - bytes: bytes
@@ -257,6 +258,7 @@ Request
    - X-Account-Meta-Temp-URL-Key-2: X-Account-Meta-Temp-URL-Key-2_req
    - X-Account-Meta-name: X-Account-Meta-name_req
    - X-Remove-Account-name: X-Remove-Account-name
+   - X-Account-Access-Control: X-Account-Access-Control_req
    - X-Trans-Id-Extra: X-Trans-Id-Extra
 
 
@@ -359,9 +361,5 @@ Response Parameters
    - X-Account-Storage-Policy-name-Container-Count: X-Account-Storage-Policy-name-Container-Count
    - X-Account-Storage-Policy-name-Object-Count: X-Account-Storage-Policy-name-Object-Count
    - X-Account-Meta-Quota-Bytes: X-Account-Meta-Quota-Bytes_resp
-   - Content-Type: Content-Type_cud_resp
-
-
-
-
-
+   - X-Account-Access-Control: X-Account-Access-Control_resp
+   - Content-Type: Content-Type_cud_resp
\ No newline at end of file
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 3c96a60e7..27afd5b1f 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -48,6 +48,7 @@ Overview and Concepts
     overview_policies
     overview_reaper
     overview_auth
+    overview_acl
     overview_replication
     ratelimit
     overview_large_objects
diff --git a/doc/source/overview_acl.rst b/doc/source/overview_acl.rst
new file mode 100644
index 000000000..f8cc67b54
--- /dev/null
+++ b/doc/source/overview_acl.rst
@@ -0,0 +1,300 @@
+
+===========================
+Access Control Lists (ACLs)
+===========================
+
+Normally to create, read and modify containers and objects, you must have the
+appropriate roles on the project associated with the account, i.e., you
+must be the owner of the account. However, an owner can grant access to
+other users by using an Access Control List (ACL).
+
+There are two types of ACLs:
+
+- :ref:`container_acls`. These are specified on a container and
+  apply to that container only and the objects in the container.
+- :ref:`account_acls`. These are specified at the account level and
+  apply to all containers and objects in the account.
+
+.. _container_acls:
+
+--------------
+Container ACLs
+--------------
+
+Container ACLs are stored in the ``X-Container-Write`` and ``X-Container-Read``
+metadata. The scope of the ACL is limited to the container where the
+metadata is set and the objects in the container. In addition:
+
+- ``X-Container-Write`` grants the ability to perform PUT, POST and DELETE
+  operations on objects within a container. It does not grant the ability
+  to perform POST or DELETE operations on the container itself. Some ACL
+  elements also grant the ability to perform HEAD or GET operations on the
+  container.
+
+- ``X-Container-Read`` grants the ability to perform GET and HEAD
+  operations on objects within a container. Some of the ACL elements also grant
+  the ability to perform HEAD or GET operations on the container itself.
+  However, a container ACL does not allow access to privileged metadata (such
+  as ``X-Container-Sync-Key``).
+
+Container ACLs use the "V1" ACL syntax which is a comma separated string
+of elements as shown in the following example::
+
+    .r:*,.rlistings,7ec59e87c6584c348b563254aae4c221:*
+
+Spaces may occur between elements as shown in the following example::
+
+
+    .r : *, .rlistings, 7ec59e87c6584c348b563254aae4c221:*
+
+However, these spaces are removed from the value stored in the
+``X-Container-Write`` and ``X-Container-Read`` metadata. In addition,
+the ``.r:`` string can be written as ``.referrer:``, but is stored as ``.r:``.
+
+While all auth systems use
+the same syntax, the meaning of some elements
+is different because of the different concepts used by different
+auth systems as explained in the following sections:
+
+- :ref:`acl_common_elements`
+- :ref:`acl_keystone_elements`
+- :ref:`acl_tempauth_elements`
+
+
+.. _acl_common_elements:
+
+Common ACL Elements
+-------------------
+
+The following table describes elements of an ACL that are
+supported by both Keystone auth and TempAuth. These elements
+should only be used with ``X-Container-Read`` (with the exception
+of ``.rlistings``, an error will occur if used with
+``X-Container-Write``):
+
+============================== ================================================
+Element                        Description
+============================== ================================================
+``.r:*``                       Any user has access to objects. No token is
+                               required in the request.
+``.r:<referrer>``              The referrer is granted access to objects. The
+                               referrer is identified by the ``Referer``
+                               request header in the request. No token is
+                               required.
+``.r:-<referrer>``             This syntax (with "-" prepended to the
+                               referrer) is supported. However, it does not
+                               deny access if another element (e.g., ``.r:*``)
+                               grants access.
+``.rlistings``                 Any user can perform a HEAD or GET operation
+                               on the container provided the user also has
+                               read access on objects (e.g., also has ``.r:*``
+                               or ``.r:<referrer>``. No token is required.
+============================== ================================================
+
+.. _acl_keystone_elements:
+
+Keystone Auth ACL Elements
+--------------------------
+
+The following table describes elements of an ACL that are
+supported only by Keystone auth. Keystone auth also supports
+the elements described in :ref:`acl_common_elements`.
+
+A token must be included in the request for any of these ACL elements
+to take effect.
+
+============================== ================================================
+Element                        Description
+============================== ================================================
+``<project-id>:<user-id>``     The specified user, provided a token
+                               scoped to the project is included
+                               in the request, is granted access.
+                               Access to the container is also granted
+                               when used in ``X-Container-Read``.
+``<project-id>:*``             Any user with a role in the specified Keystone
+                               project has access. A token scoped to the
+                               project must be included in the request.
+                               Access to the container is also granted
+                               when used in ``X-Container-Read``.
+``*:<user-id>``                The specified user has access. A token
+                               for the user (scoped to any
+                               project) must be included in the request.
+                               Access to the container is also granted
+                               when used in ``X-Container-Read``.
+``*:*``                        Any user has access.
+                               Access to the container is also granted
+                               when used in ``X-Container-Read``.
+                               The ``*:*`` element differs from the ``.r:*``
+                               element because
+                               ``*:*`` requires that a valid token is
+                               included in the request whereas ``.r:*``
+                               does not require a token. In addition,
+                               ``.r:*`` does not grant access to the
+                               container listing.
+============================== ================================================
+
+.. note::
+
+    Keystone project (tenant) or user *names* (i.e.,
+    ``<project-name>:<user-name``) must no longer be
+    used because with the introduction
+    of domains in Keystone, names are not globally unique. You should
+    use user and project *ids* instead.
+
+    For backwards compatibility, ACLs using names will be granted by
+    keystoneauth when it can be established that
+    the grantee project, the grantee user and the project being
+    accessed are either not yet in a domain (e.g. the ``X-Auth-Token`` has
+    been obtained via the Keystone V2 API) or are all in the default domain
+    to which legacy accounts would have been migrated.
+
+
+.. _acl_tempauth_elements:
+
+TempAuth ACL Elements
+---------------------
+
+The following table describes elements of an ACL that are
+supported only by TempAuth. TempAuth auth also supports
+the elements described in :ref:`acl_common_elements`.
+
+============================== ================================================
+Element                        Description
+============================== ================================================
+``<user-name>``                The named user is granted access. The
+                               wildcard ("*") character is not supported.
+                               A token from the user must be included in the
+                               request.
+============================== ================================================
+
+----------------------
+Container ACL Examples
+----------------------
+
+Container ACLs may be set by including ``X-Container-Write`` and/or
+``X-Container-Read`` headers with a PUT or a POST request to the container URL.
+The following examples use the ``swift`` command line client which support
+these headers being set via its ``--write-acl`` and ``--read-acl`` options.
+
+Example: Public Container
+-------------------------
+
+The following allows anybody to list objects in the ``www`` container and
+download objects. The users do not need to include a token in
+their request. This ACL is commonly referred to as making the
+container "public". It is useful when used with :ref:`staticweb`::
+
+    swift post www --read-acl ".r:*,.rlistings"
+
+
+Example: Shared Writable Container
+----------------------------------
+
+The following allows anybody to upload or download objects. However, to
+download an object, the exact name of the object must be known since
+users cannot list the objects in the container.
+The users must include a Keystone token in the upload request. However, it does not
+need to be scoped to the project associated with the container::
+
+    swift post www --read-acl ".r:*" --write-acl "*:*"
+
+
+Example: Sharing a Container with Project Members
+-------------------------------------------------
+
+The following allows any member of the ``77b8f82565f14814bece56e50c4c240f``
+project to upload and download objects or to list the contents
+of the ``www`` container. A token scoped to the ``77b8f82565f14814bece56e50c4c240f``
+project must be included in the request::
+
+    swift post www --read-acl "77b8f82565f14814bece56e50c4c240f:*" \
+                   --write-acl "77b8f82565f14814bece56e50c4c240f:*"
+
+
+Example: Allowing a Referrer Domain to Download Objects
+-------------------------------------------------------
+
+The following allows any request from
+the ``example.com`` domain to access an object in the container::
+
+    swift post www --read-acl ".r:.example.com"
+
+However, the request from the user **must** contain the appropriate
+`Referer` header as shown in this example request::
+
+    curl -i $publicURL/www/document --head -H "Referer: http://www.example.com/index.html"
+
+.. note::
+
+    The `Referer` header is included in requests by many browsers. However,
+    since it is easy to create a request with any desired value in the
+    `Referer` header, the referrer ACL has very weak security.
+
+
+.. _account_acls:
+
+------------
+Account ACLs
+------------
+
+.. note::
+
+    Account ACLs are not currently supported by Keystone auth
+
+The ``X-Account-Access-Control`` header is used to specify
+account-level ACLs in a format specific to the auth system.
+These headers are visible and settable only by account owners (those for whom
+``swift_owner`` is true).
+Behavior of account ACLs is auth-system-dependent.  In the case of TempAuth,
+if an authenticated user has membership in a group which is listed in the
+ACL, then the user is allowed the access level of that ACL.
+
+Account ACLs use the "V2" ACL syntax, which is a JSON dictionary with keys
+named "admin", "read-write", and "read-only".  (Note the case sensitivity.)
+An example value for the ``X-Account-Access-Control`` header looks like this,
+where ``a``, ``b`` and ``c`` are user names::
+
+   {"admin":["a","b"],"read-only":["c"]}
+
+Keys may be absent (as shown in above example).
+
+The recommended way to generate ACL strings is as follows::
+
+  from swift.common.middleware.acl import format_acl
+  acl_data = { 'admin': ['alice'], 'read-write': ['bob', 'carol'] }
+  acl_string = format_acl(version=2, acl_dict=acl_data)
+
+Using the :func:`format_acl` method will ensure
+that JSON is encoded as ASCII (using e.g. '\u1234' for Unicode).  While
+it's permissible to manually send ``curl`` commands containing
+``X-Account-Access-Control`` headers, you should exercise caution when
+doing so, due to the potential for human error.
+
+Within the JSON dictionary stored in ``X-Account-Access-Control``, the keys
+have the following meanings:
+
+============   ==============================================================
+Access Level   Description
+============   ==============================================================
+read-only      These identities can read *everything* (except privileged
+               headers) in the account.  Specifically, a user with read-only
+               account access can get a list of containers in the account,
+               list the contents of any container, retrieve any object, and
+               see the (non-privileged) headers of the account, any
+               container, or any object.
+read-write     These identities can read or write (or create) any container.
+               A user with read-write account access can create new
+               containers, set any unprivileged container headers, overwrite
+               objects, delete containers, etc.  A read-write user can NOT
+               set account headers (or perform any PUT/POST/DELETE requests
+               on the account).
+admin          These identities have "swift_owner" privileges.  A user with
+               admin account access can do anything the account owner can,
+               including setting account headers and any privileged headers
+               -- and thus granting read-only, read-write, or admin access
+               to other users.
+============   ==============================================================
+
+
+For more details, see :mod:`swift.common.middleware.tempauth`.  For details
+on the ACL format, see :mod:`swift.common.middleware.acl`.
\ No newline at end of file
diff --git a/doc/source/overview_auth.rst b/doc/source/overview_auth.rst
index e98526e7a..88bf550e4 100644
--- a/doc/source/overview_auth.rst
+++ b/doc/source/overview_auth.rst
@@ -3,12 +3,11 @@ The Auth System
 ===============
 
 --------
-TempAuth
+Overview
 --------
 
-The auth system for Swift is loosely based on the auth system from the existing
-Rackspace architecture -- actually from a few existing auth systems -- and is
-therefore a bit disjointed. The distilled points about it are:
+Swift supports a number of auth systems that share the following common
+characteristics:
 
 * The authentication/authorization part can be an external system or a
   subsystem run within Swift as WSGI middleware
@@ -26,91 +25,69 @@ validation.
 
 Swift will make calls to the auth system, giving the auth token to be
 validated. For a valid token, the auth system responds with an overall
-expiration in seconds from now. Swift will cache the token up to the expiration
+expiration time in seconds from now. To avoid the overhead in validating the same
+token over and over again, Swift will cache the
+token for a configurable time, but no longer than the expiration
 time.
 
-The included TempAuth also has the concept of admin and non-admin users
+The Swift project includes two auth systems:
+
+- :ref:`temp_auth`
+- :ref:`keystone_auth`
+
+It is also possible to write your own auth system as described in
+:ref:`extending_auth`.
+
+.. _temp_auth:
+
+--------
+TempAuth
+--------
+
+The included TempAuth has the concept of admin and non-admin users
 within an account.  Admin users can do anything within the account.
-Non-admin users can only perform operations per container based on the
-container's X-Container-Read and X-Container-Write ACLs.  Container ACLs
-use the "V1" ACL syntax, which looks like this:
-``name1, name2, .r:referrer1.com, .r:-bad.referrer1.com, .rlistings``
-For more information on ACLs, see :mod:`swift.common.middleware.acl`.
-
-Additionally, if the auth system sets the request environ's swift_owner key to
-True, the proxy will return additional header information in some requests,
-such as the X-Container-Sync-Key for a container GET or HEAD.
-
-In addition to container ACLs, TempAuth allows account-level ACLs.  Any auth
-system may use the special header ``X-Account-Access-Control`` to specify
-account-level ACLs in a format specific to that auth system.  (Following the
-TempAuth format is strongly recommended.)  These headers are visible and
-settable only by account owners (those for whom ``swift_owner`` is true).
-Behavior of account ACLs is auth-system-dependent.  In the case of TempAuth,
-if an authenticated user has membership in a group which is listed in the
-ACL, then the user is allowed the access level of that ACL.
-
-Account ACLs use the "V2" ACL syntax, which is a JSON dictionary with keys
-named "admin", "read-write", and "read-only".  (Note the case sensitivity.)
-An example value for the ``X-Account-Access-Control`` header looks like this:
-``{"admin":["a","b"],"read-only":["c"]}``  Keys may be absent (as shown).
-The recommended way to generate ACL strings is as follows::
-
-  from swift.common.middleware.acl import format_acl
-  acl_data = { 'admin': ['alice'], 'read-write': ['bob', 'carol'] }
-  acl_string = format_acl(version=2, acl_dict=acl_data)
-
-Using the :func:`format_acl` method will ensure
-that JSON is encoded as ASCII (using e.g. '\u1234' for Unicode).  While
-it's permissible to manually send ``curl`` commands containing
-``X-Account-Access-Control`` headers, you should exercise caution when
-doing so, due to the potential for human error.
-
-Within the JSON dictionary stored in ``X-Account-Access-Control``, the keys
-have the following meanings:
-
-============   ==============================================================
-Access Level   Description
-============   ==============================================================
-read-only      These identities can read *everything* (except privileged
-               headers) in the account.  Specifically, a user with read-only
-               account access can get a list of containers in the account,
-               list the contents of any container, retrieve any object, and
-               see the (non-privileged) headers of the account, any
-               container, or any object.
-read-write     These identities can read or write (or create) any container.
-               A user with read-write account access can create new
-               containers, set any unprivileged container headers, overwrite
-               objects, delete containers, etc.  A read-write user can NOT
-               set account headers (or perform any PUT/POST/DELETE requests
-               on the account).
-admin          These identities have "swift_owner" privileges.  A user with
-               admin account access can do anything the account owner can,
-               including setting account headers and any privileged headers
-               -- and thus granting read-only, read-write, or admin access
-               to other users.
-============   ==============================================================
-
-
-For more details, see :mod:`swift.common.middleware.tempauth`.  For details
-on the ACL format, see :mod:`swift.common.middleware.acl`.
+Non-admin users can only perform read operations. However, some
+privileged metadata such as X-Container-Sync-Key is not accessible to
+non-admin users.
 
 Users with the special group ``.reseller_admin`` can operate on any account.
 For an example usage please see :mod:`swift.common.middleware.tempauth`.
 If a request is coming from a reseller the auth system sets the request environ
 reseller_request to True. This can be used by other middlewares.
 
+Other users may be granted the ability to perform operations on
+an account or container via ACLs. TempAuth supports two types of ACL:
+
+- Per container ACLs based on the
+  container's ``X-Container-Read`` and ``X-Container-Write`` metadata. See
+  :ref:`container_acls` for more information.
+
+- Per account ACLs based on the account's ``X-Account-Access-Control``
+  metadata. For more information see :ref:`account_acls`.
+
 TempAuth will now allow OPTIONS requests to go through without a token.
 
-The user starts a session by sending a REST request to the auth system to
-receive the auth token and a URL to the Swift system.
+The TempAuth middleware is responsible for creating its own tokens. A user
+makes a request containing their username and password and TempAuth
+responds with a token. This token is then used to perform subsequent
+requests on the user's account, containers and objects.
+
+.. _keystone_auth:
 
 -------------
 Keystone Auth
 -------------
 
-Swift is able to authenticate against OpenStack Keystone_ via the
-:ref:`keystoneauth` middleware.
+Swift is able to authenticate against OpenStack Keystone_. In this
+environment, Keystone is responsible for creating and validating
+tokens. The :ref:`keystoneauth` middleware is responsible for
+implementing the auth system within Swift as described here.
+
+The :ref:`keystoneauth` middleware supports per container based ACLs on the
+container's ``X-Container-Read`` and ``X-Container-Write`` metadata.
+For more information see :ref:`container_acls`.
+
+The account-level ACL is not supported by Keystone auth.
 
 In order to use the ``keystoneauth`` middleware the ``auth_token``
 middleware from KeystoneMiddleware_ will need to be configured.
@@ -383,13 +360,18 @@ keystone with Swift:
   If this ``openstack`` command fails then it is likely that there is a problem
   with the ``authtoken`` configuration.
 
+.. _extending_auth:
+
 --------------
 Extending Auth
 --------------
 
 TempAuth is written as wsgi middleware, so implementing your own auth is as
 easy as writing new wsgi middleware, and plugging it in to the proxy server.
-The Keystone project and the Swauth project are examples of additional auth
-services.
+The `Swauth <https://github.com/openstack/swauth>`_ project is an example of
+an additional auth service.
+
+See :doc:`development_auth` for detailed information on extending the
+auth system.
+
 
-Also, see :doc:`development_auth`.