You can call this operation to configure encryption rules for a bucket.

Note 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 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

Element Type Required Description
ServerSideEncryptionRule Container Yes The container that stores server-side encryption rules.

Child nodes: ApplyServerSideEncryptionByDefault

ApplyServerSideEncryptionByDefault Container Yes The container that stores the default server-side encryption method.

Child nodes: SSEAlgorithm and KMSMasterKeyID

SSEAlgorithm String Yes The default server-side encryption method.

Valid values: KMS and AES256.

  • 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 encryption method is configured for the destination bucket and ReplicaCMKID is configured in the replication rule:
    • If objects in the source bucket are not encrypted, they are encrypted with the default encryption method of the destination bucket after they are replicated.
    • If objects in the source bucket are encrypted by using SSE-KMS or SSE-OSS, they are encrypted by using the same method after they are replicated.

    For more information about cross-region replication, see Cross-region replication.

KMSMasterKeyID String No 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 parameter must be set to null.

Examples

  • Sample request

    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: Tue, 20 Dec 2018 11:09:13 GMT
    Content-Length: ContentLength
    Content-Type: application/xml
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Authorization: OSS qn6qrrqxo2oawuk53otf****:ceOEyZavKY4QcjoUWYSpYbJ3****
    <? 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: Thu, 20 Dec 2018 11:11:06 GMT

SDK

You can use the following SDKs for various programming languages to call PutBucketEncryption:

Error 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: The Encryption request you specified is not valid. Supported value: AES256/KMS.
InvalidArgument 400 The error returned because the value of SSEAlgorithm is AES256 but KMSMasterKeyID is specified. The following error message is returned: KMSMasterKeyID is not applicable if the default sse algorithm is not KMS.