ACL

KS3 enables you to configure ACLs to manage the bucket and object access permissions. Each bucket and object have an ACL. The ACL defines the users with access permissions and the access types. After receiving a resource request, KS3 checks the corresponding ACL to verify whether the requester has the required access permission.
An ACL is expressed in XML format.

Example:

<AccessControlPolicy>
    <Owner>
       <ID>Owner-User-Id</ID>
       <DisplayName>Owner-User-Name</DisplayName>
    </Owner>
    <AccessControlList>
      <Grant>
        <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
          <ID>User2-Id</ID>
          <DisplayName>User2-Name</DisplayName>
        </Grantee>
        <Permission>READ</Permission>
     </Grant>
...
    </AccessControlList>
</AccessControlPolicy>

The Owner field specifies the account ID and username of the resource owner, and the Grant field specifies the authorized entity and the granted permission.

Authorized entities

Authorized entities can be Kingsoft Cloud accounts or all users, including anonymous users, but cannot be IAM users.

• Kingsoft Cloud account: represented by an account ID in the authorization statement.

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"><ID>ID</ID><DisplayName>GranteesEmail</DisplayName>
</Grantee>

• All users, including anonymous users: represented by
  http://acs.ksyun.com/groups/global/AllUsers in the authorization statement.

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group"><URI>http://acs.ksyun.com/groups/global/AllUsers</URI></Grantee>

Granted permissions

The following tables describe the permissions supported by KS3 in ACLs. ACL permissions for buckets and objects are the same. However, they allow different operations for buckets and objects. The following table describes the ACL permissions and their meanings for buckets and objects.

ACL permission	Bucket authorization	Object authorization
READ	Allows the authorized entity to list the objects in the bucket.	Allows the authorized entity to read the object data and metadata.
WRITE	Allows the authorized entity to create, overwrite, and delete any object in the bucket.	Not applicable.
FULL_CONTROL	Grants the bucket-specific read/write permissions to the authorized entity.	Grants the object-specific read permission to the authorized entity.

As described in the preceding table, the ACL grants limited permissions. Each permission allows one or more KS3 operations. For example, the object read permission allows the Head Object and GET Object operations. The following table describes the mapping between each ACL permission and the corresponding access policy permission. The ACL is mainly used to grant basic read/write permissions, which are similar to file system permissions.

ACL permission	Access policy used when the ACL permission is granted for a bucket	Access policy used when the ACL permission is granted for an object
READ	List Bucket and List Multipart Upload	Get Object, Head Object, and List Parts
WRITE	Put Object, Post Object, Put Object Copy, Upload Part Copy, Delete Object, Initiate Multipart Upload, Upload Part, Complete Multipart Upload, and Abort Multipart Upload	Not applicable.
FULL_CONTROL	Equivalent to the READ and WRITE ACL permissions.	Equivalent to the READ ACL permission.

Bucket and object access permissions

KS3 supports a series of predefined authorization policies, called preset ACLs. Each preset ACL contains a set of predefined authorized entities and permissions. The preset ACLs correspond to the bucket and object access permissions in the KS3 console.

• Bucket access permissions

Three access permissions are defined for buckets: private, public-read, and public-read-write.

Permission	Description	Limit on access
private	The private permission.	The bucket owner has full access permissions on the bucket, and other users are not allowed to access the bucket by default.
public-read	The public read permission.	The bucket owner has full access permissions on the bucket, and all users, including anonymous users, are allowed to list all objects in the bucket.
public-read-write	The public read/write permission.	All users, including anonymous users, are allowed to write objects to and delete objects from the bucket and list all objects in the bucket.

• Object access permissions

Two access permissions are defined for objects: private and public-read.

Permission	Description	Limit on access
private	The private permission.	The object owner is allowed to access the object, and other users are not allowed to access the object by default.
public-read	The public read permission.	All users, including anonymous users, are allowed to access the object.

• Settings

• When calling an API operation to create a bucket or object or modify a permission, you can add the x-kss-acl header to specify the preset ACL permission.

• You can also perform the following steps to set the access permission: Log in to the KS3 console and click Bucket in the left navigation pane. On the bucket list page that appears, click the name of the bucket that you want to manage. Click the Bucket Settings tab. On the Basic settings tab, click Edit next to Bucket Permissions to set the access permission. The following figure shows the Basic settings tab.

Set an ACL

• When creating a bucket or uploading an object, you can specify an ACL by setting the request headers in the following table.
• For more information, see:
  • PUT Bucket
  • PUT Object

Request header	Description
x-kss-acl	Specifies a preset ACL.
x-kss-grant-read	Grants the read permissions to users.
x-kss-grant-write	Grants the write permissions to users.
x-kss-grant-full-control	Grants the full permissions to users.

• To set an ACL for an existing resource, you can modify the request headers or request body.
• For more information, see:
  • PUT Bucket ACL
  • PUT Object ACL