Configure encryption rules for a bucket - Object Storage Service

Use the PutBucketEncryption operation to configure server-side encryption rules for a bucket.

Usage notes

Calling the PutBucketEncryption operation requires the oss:PutBucketEncryption permission. For more information, see Grant a custom policy.

Note

Only the bucket owner and authorized RAM users can set encryption rules for a bucket. Otherwise, OSS returns an HTTP 403 error. For more information about bucket encryption, see server-side encryption.

Request syntax

PUT /?encryption HTTP/1.1
Date: GMT Date
Content-Length：ContentLength
Content-Type: application/xml
Host: BucketName.oss.aliyuncs.com
Authorization: SignatureValue
<?xml version="1.0" encoding="UTF-8"?>
<ServerSideEncryptionRule>
  <ApplyServerSideEncryptionByDefault>
    <SSEAlgorithm>AES256</SSEAlgorithm>
    <KMSMasterKeyID></KMSMasterKeyID>
  </ApplyServerSideEncryptionByDefault>
</ServerSideEncryptionRule>

Request elements

Parameter	Type	Required	Example	Description
ServerSideEncryptionRule	Container	Yes	N/A	A container for server-side encryption rules. Child element: ApplyServerSideEncryptionByDefault
ApplyServerSideEncryptionByDefault	Container	Yes	N/A	A container for the default server-side encryption configuration. Child elements: SSEAlgorithm and KMSMasterKeyID
SSEAlgorithm	String	Yes	AES256	Specifies the default server-side encryption method. Valid values: `KMS`, `AES256`. Note In CloudBox scenarios, only `AES256` is supported. Using KMS keys incurs small fees for API calls made to KMS. For more information, see KMS pricing. For cross-region replication, if the destination bucket has default server-side encryption enabled and the replication rule specifies a `ReplicaCMKID`, the following behavior occurs: OSS encrypts plaintext objects from the source bucket by using the default encryption method of the destination bucket. Objects in the source bucket encrypted with SSE-KMS or SSE-OSS retain their original encryption methods after replication to the destination bucket. For more information, see Use cross-region replication with server-side encryption.
KMSMasterKeyID	String	No	9468da86-3509-4f8d-a61e-6eab1eac****	The ID of the KMS key. This element is applicable only when `SSEAlgorithm` is set to `KMS`. If `SSEAlgorithm` is not `KMS`, leave this element empty. If you use OSS on CloudBox, this parameter is not supported.

This operation also uses common request headers such as Date and Host. For more information, see Common request headers.

Response headers

The response contains only common response headers. For more information, see Common response headers.

Examples

Sample requests

Configure SSE-KMS encryption

This example shows how to configure SSE-KMS encryption for a bucket named oss-example.

PUT /?encryption HTTP/1.1
Date: Thu, 17 Apr 2025 11:09:13 GMT
Content-Length：ContentLength
Content-Type: application/xml
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<ServerSideEncryptionRule>
  <ApplyServerSideEncryptionByDefault>
    <SSEAlgorithm>KMS</SSEAlgorithm>
    <KMSMasterKeyID>9468da86-3509-4f8d-a61e-6eab1eac****</KMSMasterKeyID>
  </ApplyServerSideEncryptionByDefault>
</ServerSideEncryptionRule>

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 5C1B138A109F4E405B2D****
Date: Thur, 5 Nov 2020 11:09:13 GMT

SDKs

You can use the following SDKs to call the PutBucketEncryption operation:

ossutil CLI

For the corresponding ossutil command, see put-bucket-encryption.

Error codes

Error code	HTTP status code	Description
InvalidEncryptionAlgorithmError	400	OSS returns this error if the value of `SSEAlgorithm` is not `KMS` or `AES256`. The error message is: `The Encryption request you specified is not valid. Supported value: AES256/KMS`.
InvalidArgument	400	OSS returns this error if `SSEAlgorithm` is set to `AES256` but `KMSMasterKeyID` is specified. The error message is: `KMSMasterKeyID is not applicable if the default sse algorithm is not KMS`.