Updated on 2024-10-08 GMT+08:00

Managing Bucket ACLs

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:

  1. Specify a pre-defined access control policy during bucket creation.
  2. Call set_bucket_acl_by_head to specify a pre-defined access control policy.
  3. 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/eu/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/eu/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/eu/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);
}

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/eu/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);
}