Updated on 2026-09-20 GMT+08:00

Configuring Bucket Encryption

Function

After you enable encryption for a bucket, the objects you upload to this bucket will be encrypted with the specified encryption method before they are stored in OBS. When you later download these encrypted objects, OBS decrypts them first and then returns them to you. This API is used to configure or update encryption for a bucket.

Restrictions

To configure encryption for a bucket, you must be the bucket owner or have the required permission (obs:bucket:PutEncryptionConfiguration in IAM or PutEncryptionConfiguration in a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Creating a Custom Bucket Policy.
The mapping between OBS regions and endpoints must comply with what is listed in Regions and Endpoints.

Method

obsClient.setBucketEncryption(SetBucketEncryptionRequest request)

Request Parameters

**Table 1** List of request parameters
Parameter	Type	Mandatory (Yes/No)	Description
request	Table 2	Yes	Explanation: Request parameters for configuring encryption for a bucket. For details, see Table 2.

**Table 2** SetBucketEncryptionRequest
Parameter	Type	Mandatory (Yes/No)	Description
bucketName	String	Yes	Explanation: Bucket name. Restrictions: A bucket name must be unique across all accounts and regions. A bucket name: Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed. Cannot be formatted as an IP address. Cannot start or end with a hyphen (-) or period (.). Cannot contain two consecutive periods (..), for example, my..bucket. Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket. If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket properties comply with those set in the first creation request. Default value: None
bucketEncryption	BucketEncryption	Yes	Explanation: Bucket encryption configuration. Value range: For details, see Table 3. Default value: None

**Table 3** BucketEncryption
Parameter	Type	Mandatory (Yes/No)	Description
sseAlgorithm	SSEAlgorithmEnum	Yes	Explanation: Server-side encryption method. Value range: See Table 4. Default value: None
kmsKeyId	String	No	Explanation: KMS master key used for SSE-KMS. Value range: Valid value formats are as follows: regionID:domainID:key/key_id key_id In the preceding formats: regionID indicates the ID of the region where the key is used. You can obtain it from Regions and Endpoints. domainID indicates the ID of the account to which the key belongs. To obtain it, see How Do I Get My Account ID and User ID? key_id indicates the ID of the key created on Data Encryption Workshop (DEW). To obtain it, see Viewing a CMK. Default value: If this parameter is not specified, the default master key will be used.

**Table 4** SSEAlgorithmEnum
Constant	Default Value	Description
KMS	kms	Objects are encrypted using SSE-KMS.
AES256	AES256	Objects are encrypted using SSE-OBS.

Responses

**Table 5** Common response headers
Parameter	Type	Description
statusCode	int	Explanation: HTTP status code. Value range: A status code is a group of digits that can be 2xx (indicating successes) or 4xx or 5xx (indicating errors). It indicates the status of a response. For more information, see Status Code. Default value: None
responseHeaders	Map<String, Object>	Explanation: HTTP response header list, composed of tuples. In a tuple, the String key indicates the name of the header, and the Object value indicates the value of the header. Default value: None

Sample Code

This example sets a bucket's encryption method to KMS.

import android.util.Log;
import com.obs.services.ObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.BucketEncryption;
import com.obs.services.model.HeaderResponse;
import com.obs.services.model.SSEAlgorithmEnum;

// Note: Network operations must be performed in a child thread. Otherwise, NetworkOnMainThreadException will be thrown.
new Thread(() -> {
    // Security warning: Hard-coded AK and SK are risky. You are advised to obtain the AK and SK from the security credential management system.
    String ak = System.getenv("ACCESS_KEY_ID");
    String sk = System.getenv("SECRET_ACCESS_KEY");
    String endPoint = "https://your-endpoint";

    ObsClient obsClient = null;
    try {
        obsClient = new ObsClient(ak, sk, endPoint);

        String bucketName = "examplebucket";

        // Set the bucket's encryption method to KMS.
        BucketEncryption encryption = new BucketEncryption();
        encryption.setSseAlgorithm(SSEAlgorithmEnum.KMS);

        HeaderResponse response = obsClient.setBucketEncryption(bucketName, encryption);
        Log.i("ObsDemo", "Configured the bucket encryption successfully. statusCode: " + response.getStatusCode());
    } catch (ObsException e) {
        Log.e("ObsDemo", "Failed to configure the bucket encryption. HTTP status code: " + e.getResponseCode()
                + ". Error code: " + e.getErrorCode()
                + ". Error message: " + e.getErrorMessage());
    } finally {
        if (obsClient != null) {
            try {
                obsClient.close();
            } catch (Exception e) {
                Log.e("ObsDemo", "Failed to close ObsClient.", e);
            }
        }
    }
}).start();

Parent topic: Server-Side Encryption