Docs

Torch Object Storage

Server-side encryption

PutBucketEncryption

Feature description

This interface sets server-side encryption for a bucket. Once configured, all objects uploaded to the bucket will automatically inherit its encryption settings, unless otherwise specified. Currently, server-side encryption using KMS-managed keys (SSE-KMS) and TOS-managed keys (SSE-TOS) is supported for bucket configuration.

For more information on server-side encryption, see Server-Side Encryption Overview.

Notes

PutBucketEncryption can only be called over HTTPS.

Only users with tos:PutBucketEncryption permission can call PutBucketEncryption. By default, the bucket owner directly has tos:PutBucketEncryption permission, and the bucket owner can grant this permission to other users.

HNS buckets do not support the PutBucketEncryption interface.

Request syntax

PUT /?encryption HTTPS​
Host: bucketname.tos-cn-beijing.volces.com​
Date: Fri, 30 Jul 2021 08:05:36 +0000​
Authorization: authorization string​
Content-MD5: OolRtfRnEQlFUQVcEd5Q****​
​
{​
    "Rule":{​
        "ApplyServerSideEncryptionByDefault":{​
            "SSEAlgorithm":"kms",​
            "KMSMasterKeyID":"trn:kms:cn-beijing:200000****:keyrings/ring-test/keys/key-test"​
        }​
    }​
}​

Request parameters and headers

This request requires setting the Content-MD5 value of the request body elements in the headers. It will be compared with the MD5 value of the uploaded request body elements. If they do not match, an error will be returned. For other common request headers, see common parameters.

Name	Location	Type	Required	Sample value	Note
encryption	Query	String	Yes	-	Special identifier representing the PutBucketEncryption request.
Content-MD5	Header	String	Yes	XrY7u+Ae7tCTyyK7j1rNww==	Base64-encoded MD5 digest of the message body.

Request body elements

Name	Type	Required	Sample value	Note
Rule	Array	Yes	-	Bucket encryption rule information.
ApplyServerSideEncryptionByDefault	Array	Yes	-	Server-side encryption configuration information.
SSEAlgorithm	String	Yes	AES256	The default encryption method for server-side encryption is described as follows: kms: use SSE-KMS encryption. AES256: uses SSE-TOS encryption with the AES256 algorithm. SM4: uses SSE-TOS encryption with the SM4 algorithm. tip Using SSE-KMS for server-side encryption generates API call fees, and creating KMS keys generates key management fees, which are charged by KMS. For more information, see KMS Billing Overview. The AES-256 algorithm for SSE-TOS is only supported in China (Beijing), China (Shanghai), Asia Pacific (Johor), and Asia Pacific (Jakarta); the SM4 algorithm for SSE-TOS is only supported in China (Beijing) and China (Shanghai).
KMSDataEncryption	String	No	AES256	Set the encryption algorithm when using SSE-KMS encryption. If not set, it defaults to the AES256 encryption algorithm. The values are explained as follows: AES256: AES256 encryption algorithm. SM4: SM4 encryption algorithm. tip AES-256 algorithm under SSE-KMS is only supported in China (Beijing), China (Shanghai), Asia Pacific (Johor), and Asia Pacific (Jakarta); SM4 algorithm under SSE-KMS is only supported in China (Beijing) and China (Shanghai).
KMSMasterKeyID	String	No	trn:kms:cn-beijing:200000*****:keyrings/ring-test/keys/key-test	Specify the primary key for SSE-KMS encryption in the format trn:kms:<region>:<accountID>:keyrings/<keyring>/keys/<key>, which is the TRN of the KMS primary key. Parameter details are as follows: region: the Region ID where the key is used. accountID: the account ID that owns the key. keyring: alias of the keyring. key: primary key alias. tip You can also create a primary key in the KMS console, then click the key name to get the KMSMasterKeyID under the key TRN and alias column on the key ring details page. For detailed information on KMS keys, refer to KMS quick start. Set the KMSMasterKeyID parameter only when the SSEAlgorithm value is kms.

Response headers

For the common response headers returned by this request, see common parameters.

Response body elements

No elements are used.

Sample request

PUT /?encryption HTTPS​
Host: bucketname.tos-cn-beijing.volces.com​
Date: Fri, 30 Jul 2021 08:05:36 +0000​
Authorization: authorization string​
Content-MD5: OolRtfRnEQlFUQVcEd5Q****​
​
{​
    "Rule":{​
        "ApplyServerSideEncryptionByDefault":{​
            "SSEAlgorithm":"kms",​
            "KMSMasterKeyID":"trn:kms:cn-beijing:200000****:keyrings/ring-test/keys/key-test"​
        }​
    }​
}​

Sample response

HTTPS 200 OK​
x-tos-id-2: f91b0c03a01300c1-a444ed0        ​
x-tos-request-id: f91b0c03a01300c1-a444ed0            ​
Date: Fri, 30 Jul 2021 06:45:39 GMT​
server: TosServer​
Content-Length: 0​

Last updated: 2025.09.08 17:32:49