Object Storage Service (OSS) encrypts objects uploaded to a bucket that has server-side encryption enabled and stores the encrypted objects. When you call GetObject to download an object, OSS decrypts and returns the object. The x-oss-server-side-encryption header is contained in the response to declare that the object is encrypted on the server side.
Scenarios
OSS uses server-side encryption to protect static data. You can enable this feature in scenarios in which additional security or compliance is required, such as the storage of deep learning samples and online collaborative documents.
Usage notes
- You can enable server-side encryption for a bucket that is located in the following regions: China (Hangzhou), China (Shanghai), China (Qingdao), China (Beijing), China (Zhangjiakou), China (Hohhot), China (Ulanqab), China (Shenzhen), China (Heyuan), China (Guangzhou), China (Chengdu), China (Hong Kong), US (Silicon Valley), US (Virginia), Japan (Tokyo), South Korea (Seoul), Singapore, Australia (Sydney), Malaysia (Kuala Lumpur), Indonesia (Jakarta), Philippines (Manila), Thailand (Bangkok), India (Mumbai), Germany (Frankfurt), UK (London), and UAE (Dubai).
- Server-side encryption cannot automatically encrypt data that is obtained by using mirroring-based back-to-origin.
- The configurations of the default encryption method for a bucket do not affect the encryption configurations of existing objects within the bucket.
- Only one server-side encryption method can be used for an object at a time.
- If you enable server-side encryption for a bucket, you can still configure a separate encryption method for objects that you upload or copy to the bucket. The encryption method configured for objects takes precedence. For more information, see PutObject.
Encryption method
The following table describes the server-side encryption methods that you can use in different scenarios.
Encryption method | Description | Scenario | Notes | Billing rule |
---|---|---|---|---|
Server-side encryption that uses KMS-managed CMKs (SSE-KMS) | You can use the default customer master key (CMK) managed by Key Management Service (KMS) or specify a CMK to encrypt or decrypt data. This method is cost-effective because you do not need to send data to the KMS server over networks for encryption or decryption. | You must specify a CMK to meet security and compliance requirements. |
| You are charged when you call API operations to encrypt or decrypt data by using CMKs stored in KMS. For more information about the fees, see Billing of KMS. |
Server-side encryption that uses OSS-managed keys (SSE-OSS) | You can use SSE-OSS to encrypt each object. To improve security, OSS uses master keys that are periodically rotated to encrypt cryptographic keys. | Only basic encryption capabilities are required. You do not need to manage keys on your own. | None | Free of charge. |
Use the OSS console
Method 1: Enable server-side encryption when you create a bucket
- Log on to the OSS console.
- In the left-side navigation pane, click Buckets. On the Buckets page, click Create Bucket.
- In the Create Bucket panel, configure the parameters.
The following table describes the parameters that you can configure for server-side encryption.
Parameter Description Encryption Method Select an encryption method to encrypt objects in the bucket. Valid values: - None: Server-side encryption is disabled.
- OSS-Managed: The keys managed by OSS are used to encrypt objects in the bucket. OSS uses keys to encrypt objects. OSS also uses periodically rotated master keys to encrypt cryptographic keys.
- KMS: The default CMK stored in KMS or a specific CMK is used to encrypt and decrypt data.
Before you can use KMS-managed keys, you must activate KMS. For more information, see Purchase a dedicated KMS instance.
Encryption Algorithm Only AES256 is supported. CMK This parameter is available only when KMS is selected for Encryption Method. - alias/acs/oss: The default CMK stored in KMS is used to encrypt different objects and decrypt objects when the objects are downloaded.
- CMK ID: The keys generated by a specific CMK are used to encrypt different objects, and the specific CMK ID is recorded in the metadata of the encrypted object. Objects are decrypted when they are downloaded by users who have the decryption permissions.
Before you specify a CMK ID, you must create a normal key or an external key in the same region as the bucket in the KMS console. For more information, see Create a CMK.
For more information about other parameters that you must configure, see Create buckets.
- Click OK.
Method 2: Enable server-side encryption for a created bucket
- Log on to the OSS console.
- In the left-side navigation pane, click Buckets. On the Buckets page, click the name of the desired bucket.
- In the left-side navigation tree, choose .
- On the Server-side Encryption page, click Configure and configure the parameters. The following table describes the parameters.
Parameter Description Encryption Method Select an encryption method to encrypt objects in the bucket. Valid values: - None: Server-side encryption is disabled.
- OSS-Managed: The keys managed by OSS are used to encrypt objects in the bucket. OSS uses keys to encrypt objects. OSS also uses periodically rotated master keys to encrypt cryptographic keys.
- KMS: The default CMK stored in KMS or a specific CMK is used to encrypt and decrypt data.
Before you can use KMS-managed keys, you must activate KMS. For more information, see Purchase a dedicated KMS instance.
Encryption Algorithm Only AES256 is supported. CMK This parameter is available only when KMS is selected for Encryption Method. - alias/acs/oss: The default CMK stored in KMS is used to encrypt different objects and decrypt objects when the objects are downloaded.
- CMK ID: The keys generated by a specific CMK are used to encrypt different objects, and the specific CMK ID is recorded in the metadata of the encrypted object. Objects are decrypted when they are downloaded by users who have the decryption permissions.
Before you specify a CMK ID, you must create a normal key or an external key in the same region as the bucket in the KMS console. For more information, see Create a CMK.
- Click Save.
Use OSS SDKs
The following sample code provides examples on how to configure server-side encryption for a bucket by using OSS SDK for common programming languages. For more information about how to configure server-side encryption for a bucket by using OSS SDK for other programming languages, see Overview.
import com.aliyun.oss.*;
import com.aliyun.oss.model.*;
public class Demo {
public static void main(String[] args) throws Throwable {
// In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint.
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console.
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// Specify the name of the bucket. Example: examplebucket.
String bucketName = "examplebucket";
// Specify the CMK ID managed by KMS. Example: e1935511-cf88-1123-a0f8-1be8d2511***.
String kmsId = "e1935511-cf88-1123-a0f8-1be8d2511***";
// Create an OSSClient instance.
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
try {
// Configure server-side encryption for the bucket.
ServerSideEncryptionByDefault applyServerSideEncryptionByDefault = new ServerSideEncryptionByDefault(SSEAlgorithm.KMS);
applyServerSideEncryptionByDefault.setKMSMasterKeyID(kmsId);
ServerSideEncryptionConfiguration sseConfig = new ServerSideEncryptionConfiguration();
sseConfig.setApplyServerSideEncryptionByDefault(applyServerSideEncryptionByDefault);
SetBucketEncryptionRequest request = new SetBucketEncryptionRequest(bucketName, sseConfig);
ossClient.setBucketEncryption(request);
} catch (OSSException oe) {
System.out.println("Caught an OSSException, which means your request made it to OSS, "
+ "but was rejected with an error response for some reason.");
System.out.println("Error Message:" + oe.getErrorMessage());
System.out.println("Error Code:" + oe.getErrorCode());
System.out.println("Request ID:" + oe.getRequestId());
System.out.println("Host ID:" + oe.getHostId());
} catch (ClientException ce) {
System.out.println("Caught an ClientException, which means the client encountered "
+ "a serious internal problem while trying to communicate with OSS, "
+ "such as not being able to access the network.");
System.out.println("Error Message:" + ce.getMessage());
} finally {
if (ossClient != null) {
ossClient.shutdown();
}
}
}
}
<?php
if (is_file(__DIR__ . '/../autoload.php')) {
require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
require_once __DIR__ . '/../vendor/autoload.php';
}
use OSS\OssClient;
use OSS\Core\OssException;
use OSS\Model\ServerSideEncryptionConfig;
// The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console.
$accessKeyId = "<yourAccessKeyId>";
$accessKeySecret = "<yourAccessKeySecret>";
// In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint.
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
$bucket= "<yourBucketName>";
$ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint, false);
try {
// Set the default server-side encryption method of the bucket to SSE-OSS.
$config = new ServerSideEncryptionConfig("AES256");
$ossClient->putBucketEncryption($bucket, $config);
// Set the default server-side encryption method of the bucket to KMS without specifying a CMK ID.
$config = new ServerSideEncryptionConfig("KMS");
$ossClient->putBucketEncryption($bucket, $config);
// Set the default server-side encryption method of the bucket to KMS and specify a CMK ID.
$config = new ServerSideEncryptionConfig("KMS", "your kms id");
$ossClient->putBucketEncryption($bucket, $config);
} catch (OssException $e) {
printf(__FUNCTION__ . ": FAILED\n");
printf($e->getMessage() . "\n");
return;
}
print(__FUNCTION__ . ": OK" . "\n");
const OSS = require("ali-oss");
const store = new OSS({
// Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
region: 'yourregion',
// The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a Resource Access Management (RAM) user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console.
accessKeyId: 'yourAccessKeyId',
accessKeySecret: 'yourAccessKeySecret',
// Specify yourbucketname as the name of the bucket.
bucket: 'yourbucketname'
});
async function putBucketEncryption() {
try {
// Configure an encryption method for the bucket.
const result = await store.putBucketEncryption("bucket-name", {
SSEAlgorithm: "AES256", // In this example, the AES-256 encryption algorithm is configured. To use KMS for encryption, you must configure KMSMasterKeyID.
// KMSMasterKeyID: "<yourKMSMasterKeyId>". Configure the CMK ID. This parameter is available when SSEAlgorithm is set to KMS and a specified CMK is used for encryption. In other cases, leave this parameter empty.
});
console.log(result);
} catch (e) {
console.log(e);
}
}
putBucketEncryption();
# -*- coding: utf-8 -*-
import oss2
from oss2.models import ServerSideEncryptionRule
# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console.
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
# Specify the bucket name. Example: examplebucket.
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Create encryption configurations for the bucket. In this example, AES-256 encryption is used.
rule = ServerSideEncryptionRule()
rule.sse_algorithm = oss2.SERVER_SIDE_ENCRYPTION_AES256
# Specify the customer master key (CMK) ID. The CMK ID can be specified only if you use the OSS-KMS encryption method. If you want to use a specified CMK for encryption, enter the CMK ID. If you want to use the default CMK managed by Key Management Service (KMS) for encryption, leave this parameter empty. If you use AES-256 encryption, you must leave this parameter empty.
rule.kms_master_keyid = ""
# Apply the encryption configurations to the bucket.
result = bucket.put_bucket_encryption(rule)
# Display the returned HTTP status code.
print('http response code:', result.status)
using Aliyun.OSS;
using Aliyun.OSS.Common;
// Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
var endpoint = "yourEndpoint";
// The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console.
var accessKeyId = "yourAccessKeyId";
var accessKeySecret = "yourAccessKeySecret";
// Specify the bucket name. Example: examplebucket.
var bucketName = "examplebucket";
// Create an OSSClient instance.
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
try
{
// Configure server-side encryption for the bucket.
var request = new SetBucketEncryptionRequest(bucketName, "KMS", null);
client.SetBucketEncryption(request);
Console.WriteLine("Set bucket:{0} Encryption succeeded ", bucketName);
}
catch (OssException ex)
{
Console.WriteLine("Failed with error code: {0}; Error info: {1}. \nRequestID:{2}\tHostID:{3}",
ex.ErrorCode, ex.Message, ex.RequestId, ex.HostId);
}
catch (Exception ex)
{
Console.WriteLine("Failed with error info: {0}", ex.Message);
}
package main
import (
"fmt"
"os"
"github.com/aliyun/aliyun-oss-go-sdk/oss"
)
func main() {
// Create an OSSClient instance.
// Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. Specify your actual endpoint.
// The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console.
client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// Initialize an encryption rule. In this example, AES-256 encryption is used.
config := oss.ServerEncryptionRule{SSEDefault: oss.SSEDefaultRule{SSEAlgorithm: "AES256"}}
err = client.SetBucketEncryption("yourBucketName", config)
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
}
#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;
int main(void)
{
/* Initialize the information about the account that is used to access OSS. */
/* The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. */
std::string AccessKeyId = "yourAccessKeyId";
std::string AccessKeySecret = "yourAccessKeySecret";
/* Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. */
std::string Endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
/* Specify the name of the bucket. Example: examplebucket. */
std::string BucketName = "examplebucket";
/* Initialize resources such as networks. */
InitializeSdk();
ClientConfiguration conf;
OssClient client(Endpoint, AccessKeyId, AccessKeySecret, conf);
SetBucketEncryptionRequest setrequest(BucketName);
setrequest.setSSEAlgorithm(SSEAlgorithm::KMS);
/* Set the default encryption method for the bucket to SSE-KMS. */
auto outcome = client.SetBucketEncryption(setrequest);
if (!outcome.isSuccess()) {
/* Handle exceptions. */
std::cout << "SetBucketEncryption fail" <<
",code:" << outcome.error().Code() <<
",message:" << outcome.error().Message() <<
",requestId:" << outcome.error().RequestId() << std::endl;
return -1;
}
/* Release resources such as networks. */
ShutdownSdk();
return 0;
}
Use ossutil
Method 1: Configure server-side encryption when you create a bucket
For more information about how to enable server-side encryption when you create a bucket by using ossutil, see bucket-encryption.
Method 2: Specify an encryption method for an object when you upload an object
For more information about how to specify an encryption method for an object when you upload an object by using ossutil, see Specify an encryption method for an object when you upload the object.
Use RESTful APIs
If your business requires a high level of customization, you can directly call RESTful APIs. To directly call an API, you must include the signature calculation in your code. For more information, see PutBucketEncryption.
Use KMS-managed CMKs for encryption and decryption
You can use a CMK managed by KMS to generate cryptographic keys for object encryption. KMS eliminates the need to manually maintain the security, integrity, and availability of your keys. This way, you can focus on the data encryption, data decryption, and digital signature generation and verification features of your service.

- The default CMK managed by KMS
For this method, OSS generates different keys to encrypt different objects by using the default CMK that is managed by KMS, and automatically decrypts an object when the object is downloaded. The first time you use SSE-KMS, OSS creates a CMK in KMS.
Configuration methods:
- Configure the default server-side encryption method for a bucket
Set the default server-side encryption method for a bucket to KMS, without specifying a CMK ID. This way, objects uploaded to this bucket are encrypted.
- Use a KMS-managed CMK to configure server-side encryption for a specific object
When you upload an object or modify the metadata of an object, include the
x-oss-server-side-encryption
parameter in the request and set the parameter toKMS
. This way, OSS uses the default CMK managed by KMS and the AES-256 encryption algorithm to encrypt the object. For more information, see PutObject.
- Configure the default server-side encryption method for a bucket
- CMKs generated by using Bring Your Own Key (BYOK)
After you use the BYOK material in the KMS console to generate a CMK, the keys generated by a specified CMK that is managed by KMS are used to encrypt different objects and the specified CMK ID is recorded in the metadata of the encrypted object. Objects are decrypted only when they are downloaded by users who have the permissions to decrypt the objects.
You can obtain your BYOK material from one of the following sources:- BYOK material provided by Alibaba Cloud: When you create a key on KMS, you can select Alibaba Cloud KMS as the source of the key material.
- BYOK material provided by the user: When you create a key on KMS, you can select External as the source of the key material and import the external key material. For more information about how to import the key material, see Import key material.
Configuration methods:- Configure the default server-side encryption method for a bucket
Set the default server-side encryption method for a bucket to KMS and specify a CMK ID. Objects uploaded to this bucket are encrypted.
- Configure an encryption method for a specific object
When you upload an object or modify the metadata of an object, include the
x-oss-server-side-encryption
parameter in the request and set the parameter toKMS
. In addition, include thex-oss-server-side-encryption-key-id
parameter in the request and set the parameter to a specified CMK ID. This way, OSS uses the specified CMK managed by KMS and the AES-256 encryption algorithm to encrypt the object. For more information, see PutObject.
Use OSS-managed keys for encryption and decryption
OSS generates and manages data keys used to encrypt data, and provides strong and multi-factor security measures to protect data. SSE-OSS uses AES-256 to encrypt data. AES-256 is one of the advanced encryption standard algorithms.
Configuration methods:
- Configure the default server-side encryption method for a bucket
Set the default encryption method to SSE-OSS and specify AES-256 as the encryption algorithm. This way, all objects uploaded to the bucket are encrypted by default.
- Configure an encryption method for a specific object
When you upload an object or modify the metadata of an object, include the
x-oss-server-side-encryption
parameter in the request and set the parameter toAES256
. This way, OSS uses OSS-managed keys to encrypt the object. For more information, see PutObject.
Required permissions
If a RAM user wants to use server-side encryption to encrypt and decrypt objects in different scenarios, the RAM user must have the required permissions.
- Configure an encryption method for a bucket
- The permissions to manage the bucket.
- The permissions to call the
PutBucketEncryption
andGetBucketEncryption
operations. - The permissions to call the
ListKeys
,Listalias
,ListAliasesByKeyId
, andDescribeKeys
operations when you set the encryption method to SSE-KMS and use a specified CMK ID to encrypt data. The following sample code provides an example on how to grant a RAM user the preceding permissions by using a RAM policy:{ "Version": "1", "Statement": [ { "Effect": "Allow", "Action": [ "kms:List*", "kms:DescribeKey" ], "Resource": [ "acs:kms:*:141661496593****:*" // The RAM user is allowed to use all KMS-managed CMKs that belong to the Alibaba Cloud account. To specify that only a specific CMK is available for the RAM user, enter the CMK ID. ] } ] }
- Upload an object to a bucket for which an encryption method is configured
- The permissions to upload objects to the bucket.
- The permissions to call the
ListKeys
,Listalias
,ListAliasesByKeyId
,DescribeKeys
,GenerateDataKey
, andkms:Decrypt
operations when you set the encryption method to KMS and use a specified CMK ID to encrypt data. The following sample code provides an example on how to grant a RAM user the preceding permissions by using a RAM policy:{ "Version": "1", "Statement": [ { "Effect": "Allow", "Action": [ "kms:List*", "kms:DescribeKey", "kms:GenerateDataKey", "kms:Decrypt" ], "Resource": [ "acs:kms:*:141661496593****:*" // The RAM user is allowed to use all CMKs that belong to the Alibaba Cloud account. To specify that only a specific CMK is available for the RAM user, enter the CMK ID. ] } ] }
- Download an object from a bucket for which an encryption method is configured
- The permissions to access objects in the bucket.
- The permissions to call the
Decrypt
operation when you set the encryption method to KMS and use a specified CMK ID to encrypt data. The following sample code provides an example on how to grant a RAM user the preceding permissions by using a RAM policy:{ "Version": "1", "Statement": [ { "Effect": "Allow", "Action": [ "kms:Decrypt" ], "Resource": [ "acs:kms:*:141661496593****:*" // The RAM user has the permissions to use all CMKs that belong to the Alibaba Cloud account. To specify that only a specific CMK is available for the RAM user to decrypt objects, enter the CMK ID. ] } ] }
FAQ
Does OSS encrypt existing objects in a bucket after I configure server-side encryption for the bucket?
No, OSS encrypts only objects that are uploaded after server-side encryption is configured for the bucket and does not encrypt existing objects in the bucket. If you want to encrypt existing objects in the bucket, you can call the CopyObject operation to overwrite the existing objects.