You can call this operation to configure encryption rules for a bucket.
Notes
The oss:PutBucketEncryption permission is required for configuring encryption rules for a bucket. For more information, see Attach a custom policy to a RAM user.
Only the bucket owner or authorized RAM users can configure encryption rules for a bucket. Otherwise, OSS returns the 403 error. For more information about bucket encryption, see Server-side encryption.
Request structure
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
Element | Type | Required | Example | Description |
ServerSideEncryptionRule | Container | Yes | N/A | The container that stores server-side encryption rules. Child node: ApplyServerSideEncryptionByDefault |
ApplyServerSideEncryptionByDefault | Container | Yes | N/A | The container that stores the default server-side encryption method. Child nodes: SSEAlgorithm and KMSMasterKeyID |
SSEAlgorithm | String | Yes | AES256 | The default server-side encryption method. Valid values: KMS, AES256. Note If you use OSS on CloudBox, only AES-256 is supported. You are charged for calling API operations when you use CMKs to encrypt or decrypt data. For more information about the fees, see KMS pricing. In cross-region replications, if the default server-side encryption method is configured for the destination bucket and ReplicaCMKID is configured in the replication rule:
For more information, see Use cross-region replication with server-side encryption. |
KMSDataEncryption | String | No | SM4 | The algorithm used to encrypt objects. If this element is not specified, objects are encrypted by using AES256. This element is valid only when the value of SSEAlgorithm is set to KMS. Valid value: SM4. If you use OSS on CloudBox, this parameter is not supported. |
KMSMasterKeyID | String | No | 9468da86-3509-4f8d-a61e-6eab1eac**** | The CMK ID that must be specified when SSEAlgorithm is set to KMS and a specified CMK is used for encryption. In other cases, this element must be set to null. If you use OSS on CloudBox, this parameter is not supported. |
For more information about other common request headers included in PutBucketEncryption requests, such as Host and Date, see Common request headers.
Response headers
All headers in the response to a DescribeRegions request are common response headers. For more information, see Common response headers.
Examples
Sample requests
Set the encryption method to SSE-KMS
The following sample request can be sent to configure the encryption method of the bucket named oss-example to SSE-KMS:
PUT /? encryption HTTP/1.1 Date: Thur, 5 Nov 2020 11:09:13 GMT Content-Length: ContentLength Content-Type: application/xml Host: oss-example.oss-cn-hangzhou.aliyuncs.com Authorization: OSS qn6q**************:77Dv**************** <? 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
SDK
You can use OSS SDKs for the following programming languages to call the PutBucketEncryption operation:
Errors codes
Error code | HTTP status code | Description |
InvalidEncryptionAlgorithmError | 400 | The error returned because the value of SSEAlgorithm is not KMS or AES256. The following error message is returned: |
InvalidArgument | 400 | The error returned because the value of SSEAlgorithm is AES256 but KMSMasterKeyID is specified. The following error message is returned: |