Managing Bucket ACLs

Updated on 2024-12-03 GMT+08:00

View PDF

NOTICE:

If you have any questions during development, post them on the Issues page of GitHub.

A bucket ACL can be configured in any of the following ways:

Specify a pre-defined access control policy during bucket creation.
Call set_bucket_acl_by_head to specify a pre-defined access control policy.
Call set_bucket_acl to set the ACL directly.

The following table lists the five permissions supported by OBS.

Permission	Description	Value in OBS C SDK
READ	A grantee with this permission for a bucket can obtain the list of objects in and metadata of the bucket. A grantee with this permission for an object can obtain the object content and metadata.	obs_permission. OBS_PERMISSION_READ
WRITE	A grantee with this permission for a bucket can upload, overwrite, and delete any object in the bucket. This permission is not applicable to objects.	obs_permission. OBS_PERMISSION_WRITE
READ_ACP	A grantee with this permission can obtain the ACL of a bucket or object. A bucket or object owner has this permission permanently.	obs_permission. OBS_PERMISSION_READ_ACP
WRITE_ACP	A grantee with this permission can update the ACL of a bucket or object. A bucket or object owner has this permission permanently. A grantee with this permission can modify the access control policy and thus the grantee obtains full access permissions.	obs_permission. OBS_PERMISSION_WRITE_ACP
FULL_CONTROL	A grantee with this permission for a bucket has READ, WRITE, READ_ACP, and WRITE_ACP permissions for the bucket. A grantee with this permission for an object has READ, READ_ACP, and WRITE_ACP permissions for the object.	obs_permission. OBS_PERMISSION_FULL_CONTROL

There are five access control policies pre-defined in OBS, as described in the following table:

**Table 1** Pre-defined Access Control Policies
Permission	Description	Value in OBS C SDK
private	The owner of a bucket or object has the FULL_CONTROL permission for the bucket or object. Other users have no permission to access the bucket or object.	obs_canned_acl. OBS_CANNED_ACL_PRIVATE
public-read	If this permission is set for a bucket, everyone can obtain the list of objects, multipart uploads, and object versions in the bucket, as well as metadata of the bucket. If this permission is set for an object, everyone can obtain the content and metadata of the object.	obs_canned_acl. OBS_CANNED_ACL_PUBLIC_READ
public-read-write	If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads. If this permission is set for an object, everyone can obtain the content and metadata of the object.	obs_canned_acl. OBS_CANNED_ACL_PUBLIC_READ_WRITE
public-read-delivered	If this permission is set for a bucket, everyone can obtain the object list, multipart uploads, and bucket metadata in the bucket, and obtain the content and metadata of the objects in the bucket. This permission cannot be set for objects.	obs_canned_acl. OBS_CANNED_ACL_PUBLIC_READ_DELIVERED
public-read-write-delivered	If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart tasks in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; abort multipart uploads; and obtain content and metadata of objects in the bucket. This permission cannot be set for objects.	obs_canned_acl. OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

Specifying a Pre-defined Access Control Policy During Bucket Creation

Sample code:

static void test_create_bucket(obs_canned_acl canned_acl, char *bucket_name)
{
    // Create and initialize option.
    obs_options option;
    obs_status ret_status = OBS_STATUS_BUTT;
    init_obs_options(&option);

    option.bucket_options.host_name = "<your-endpoint>";
    option.bucket_options.bucket_name = "<Your bucketname>";

// Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
    option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
    option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
    // Set response callback function.
    obs_response_handler response_handler =
    { 
        0, &response_complete_callback
    };
    // canned_acl specifies a pre-defined access control policy during bucket creation.
    create_bucket(&option, canned_acl, NULL, &response_handler, &ret_status);
    if (ret_status == OBS_STATUS_OK) {
        printf("create bucket successfully. \n");
    }
    else
    {
        printf("create bucket failed(%s).\n", obs_get_status_name(ret_status));
    }
}

Setting a Pre-defined Access Control Policy for a Bucket

The following code shows how to set a pre-defined access control policy for a bucket.

Field	Type	Mandatory or Optional	Description
option	The context of the bucket. For details, see Configuring option.	Mandatory	Bucket parameter
canned_acl	obs_canned_acl	Mandatory	For details about how to manage bucket access rights, see Table 1 in Managing Bucket ACLs.
handler	obs_response_handler *	Mandatory	Callback function
callback_data	void *	Optional	Callback data

Sample code:

void test_set_bucket_acl_byhead(char *bucket_name)
{
    obs_status ret_status = OBS_STATUS_BUTT;
    // Create and initialize option.
    obs_options option;
    init_obs_options(&option);

    option.bucket_options.host_name = "<your-endpoint>";
    option.bucket_options.bucket_name = "<Your bucketname>";

// Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
    option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
    option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
    // Set response callback function.
    obs_response_handler response_handler =                         
    { 
        0, &response_complete_callback
    };
// Set a pre-defined access policy for a bucket.
    obs_canned_acl canned_acl = OBS_CANNED_ACL_PUBLIC_READ_WRITE;
    set_bucket_acl_by_head(&option, canned_acl, &response_handler, &ret_status);
    if (ret_status == OBS_STATUS_OK) {
        printf("set bucket acl by head successfully. \n");
    }
    else
    {
        printf("set bucket acl by head failed(%s).\n", obs_get_status_name(ret_status));
    }
}

Directly Setting the Bucket ACL

The following code shows how to directly set bucket access permission parameters:

Field	Type	Mandatory or Optional	Description
option	The context of the bucket. For details, see Configuring option.	Mandatory	Bucket parameter
aclinfo	manager_acl_info *	Mandatory	Structure for managing ACL permission information
aclinfo->object_info	obs_object_info *	Ignoring malicious programs	Object name and version number. For non-multi-version objects, set version to 0.
aclinfo->owner_id	char *	Ignoring malicious programs	User account ID
aclinfo->acl_grant_count_return	int *	Mandatory	Pointer to the number of returned aclinfo->acl_grants
aclinfo->acl_grants	obs_acl_grant *	Mandatory	Pointer to the permission information structure. For details, see Table 2.
aclinfo->object_delivered	obs_object_delivered	Optional	Indicates whether the object ACL inherits the ACL of the bucket. Valid values are OBJECT_DELIVERED_TRUE and OBJECT_DELIVERED_FALSE. The default value is OBJECT_DELIVERED_TRUE.
handler	obs_response_handler *	Mandatory	Callback function
callback_data	void *	Optional	Callback data

**Table 2** Description of the permission information structure **obs_acl_grant**
Field	Type	Description
grantee_type	obs_grantee_type	For details, see Table 3.
grantee.canonical_user.id	char	CanonicalUser ID.
permission	obs_permission	For details, see Managing Bucket ACLs.
bucket_delivered	obs_bucket_delivered	Indicates whether the bucket ACL is transferred to the object in the bucket. Valid values are BUCKET_DELIVERED_TRUE and BUCKET_DELIVERED_FALSE. The default value is BUCKET_DELIVERED_FALSE.

**Table 3** Description of the authorized user type
Field	Description
obs_grantee_type.OBS_GRANTEE_TYPE_CANONICAL_USER	An OBS user. Bucket or object permissions can be granted to any user who has an OBS account. Authorized users can use the AK and SK to access OBS.
obs_grantee_type.OBS_GRANTEE_TYPE_ALL_USERS	All users can access buckets or objects, including anonymous users.

Sample code:

void test_set_bucket_acl(char *bucket_name)
{
    obs_status ret_status = OBS_STATUS_BUTT;
    // Create and initialize option.
    obs_options option;
    init_obs_options(&option);

    option.bucket_options.host_name = "<your-endpoint>";
    option.bucket_options.bucket_name = "<Your bucketname>";

// Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
    option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
    option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
    // Set response callback function.
    obs_response_handler response_handler =
    { 
        0, &response_complete_callback
    };
    // Create and initialize object information.
    manager_acl_info aclinfo;
    init_acl_info(&aclinfo);
    //Set a bucket ACL.
    set_bucket_acl(&option, &aclinfo, &response_handler, &ret_status);
    if (OBS_STATUS_OK == ret_status) {
        printf("set bucket acl successfully. \n");
    }
    else
    {
        printf("set bucket acl failed(%s).\n", obs_get_status_name(ret_status));
    }
    // Free memory.
    deinitialize_acl_info(&aclinfo);
}

NOTE:

The owner or grantee ID required in the ACL indicates an account ID, which can be viewed on the My Credentials page of OBS Console.

Obtaining the Bucket ACL

You can call get_bucket_acl to obtain the bucket ACL. Sample code:

void test_get_bucket_acl(char *bucket_name)
{
    obs_status ret_status = OBS_STATUS_BUTT;
    // Create and initialize option.
    obs_options option;
    init_obs_options(&option);
    option.bucket_options.host_name = "<your-endpoint>";
    option.bucket_options.bucket_name = "<Your bucketname>";

// Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
    option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
    option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
    // Set response callback function.
    obs_response_handler response_handler =
    { 
        0,&response_complete_callback
    };
    // Apply for the ACL structure memory.
    manager_acl_info *aclinfo = malloc_acl_info();
    // Call the API for obtaining permissions.
    get_bucket_acl(&option, aclinfo, &response_handler, &ret_status);
    if (OBS_STATUS_OK == ret_status) 
    {
        printf("get bucket acl: -------------");
        printf("%s\n", aclinfo->owner_id);
        if (aclinfo->acl_grant_count_return)
        {
            print_grant_info(*aclinfo->acl_grant_count_return, aclinfo->acl_grants);
        }
    }
    else
    {
        printf("get bucket acl failed(%s).\n", obs_get_status_name(ret_status));
    }
    // Free memory.
    free_acl_info(&aclinfo);
}