控制台指南

最佳实践

开发者指南

API 文档

SDK 文档

诚邀爱技术、爱分享的你,成为文档内容共建者> HOT

简介

本文档提供在上传和下载对象时使用服务端加密的 SDK 示例代码。服务端加密说明请参见 服务端加密概述

使用 SSE-COS 服务端加密保护数据

由腾讯云对象存储(Cloud Object Storage,COS)托管主密钥和管理数据。COS 会帮助您在数据写入数据中心时自动加密,并在您取用该数据时自动解密。目前支持使用 COS 主密钥对数据进行 AES-256 加密。

请求示例:上传和下载 SSE-COS 加密对象

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import logging

# 正常情况日志级别使用INFO,需要定位时可以修改为DEBUG,此时SDK会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在CosConfig中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = 'SecretId'     # 替换为用户的 SecretId,请登录访问管理控制台进行查看和管理,https://console.cloud.tencent.com/cam/capi
secret_key = 'SecretKey'   # 替换为用户的 SecretKey,请登录访问管理控制台进行查看和管理,https://console.cloud.tencent.com/cam/capi
region = 'ap-beijing'      # 替换为用户的 region,已创建桶归属的region可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
                           # COS支持的所有region列表参见https://cloud.tencent.com/document/product/436/6224
token = None               # 如果使用永久密钥不需要填入token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见https://cloud.tencent.com/document/product/436/14048
scheme = 'https'           # 服务端加密必须使用https

config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)  # 获取配置对象
client = CosS3Client(config)

# 上传SSE-COS加密对象,指定加密类型为AES256即为SSE-COS加密
response = client.put_object(
    Bucket='examplebucket-125000000',
    Key='sdk-sse-cos',
    Body='123',
    ServerSideEncryption='AES256' 
)
print(response['x-cos-server-side-encryption']) # 服务端返回'x-cos-server-side-encryption': 'AES256' 表示是SSE-COS对象

# 下载SSE-COS加密对象,不需要携带加密头域,由服务端自动解密
response = client.get_object(
    Bucket='examplebucket-125000000',
    Key='sdk-sse-cos',
)
print(response['x-cos-server-side-encryption']) # 服务端返回'x-cos-server-side-encryption': 'AES256' 表示是SSE-COS对象

参数说明

参数名 参数描述 类型 是否必填
ServerSideEncryption 服务段加密类型,AES256 表示使用 SSE-COS 加密,cos/kms 表示使用 KMS 加密 String

使用 SSE-KMS 服务端加密保护数据

由腾讯云密钥管理系统 KMS 托管密钥的服务端加密方式,可选择使用默认密钥或自建密钥。关于密钥信息,可参见 创建 KMS 密钥,关于 SSE-KMS 的更多信息,请参见 服务端加密概述:SSE-KMS

请求示例:上传和下载 SSE-KMS 加密对象

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
from qcloud_cos.cos_comm import to_byte

import sys
import logging
import base64

# 正常情况日志级别使用INFO,需要定位时可以修改为DEBUG,此时SDK会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在CosConfig中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = 'SecretId'     # 替换为用户的 SecretId,请登录访问管理控制台进行查看和管理,https://console.cloud.tencent.com/cam/capi
secret_key = 'SecretKey'   # 替换为用户的 SecretKey,请登录访问管理控制台进行查看和管理,https://console.cloud.tencent.com/cam/capi
region = 'ap-beijing'      # 替换为用户的 region,已创建桶归属的region可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
                           # COS支持的所有region列表参见https://cloud.tencent.com/document/product/436/6224
token = None               # 如果使用永久密钥不需要填入token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见https://cloud.tencent.com/document/product/436/14048
scheme = 'https'           # 服务端加密必须使用https

config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)  # 获取配置对象
client = CosS3Client(config)

# 上传SSE-KMS加密对象,指定加密类型为cos/kms即为SSE-KMS加密
response = client.put_object(
    Bucket='examplebucket-125000000',
    Key='sdk-sse-kms',
    Body='123',
    ServerSideEncryption='cos/kms',  # SSE-KMS加密固定填写 cos/kms
    SSEKMSKeyId='kms-key-id',  # 填写 KMS 的用户主密钥 CMK,如不填写则使用 COS 默认创建的 CMK
    SSEKMSContext=base64.standard_b64encode(to_bytes("{\"test\":\"test\"}")) # 加密上下文,值为 JSON 格式加密上下文键值对的 Base64 编码,可选
)
print(response['x-cos-server-side-encryption']) # 服务端返回'x-cos-server-side-encryption': 'cos/kms' 表示是SSE-KMS对象

# 下载SSE-KMS加密对象,不需要携带加密头域,由服务端自动解密
response = client.get_object(
    Bucket='examplebucket-125000000',
    Key='sdk-sse-kms',
)
print(response['x-cos-server-side-encryption']) # 服务端返回'x-cos-server-side-encryption': 'cos/kms' 表示是SSE-KMS对象

# 高级接口上传SSE-KMS加密对象,指定加密类型为cos/kms即为SSE-KMS加密
response = client.upload_file(
    Bucket='examplebucket-125000000', 
    Key='sdk-sse-kms', 
    LocalFilePath="sdk-sse-kms.local", 
    ServerSideEncryption='cos/kms') # SSE-KMS加密固定填写 cos/kms

# 高级接口下载SSE-KMS加密对象,不需要携带加密头域,由服务端自动解密
response = client.download_file(
    Bucket='examplebucket-125000000', 
    Key='sdk-sse-kms', 
    DestFilePath='sdk-sse-kms.local')

参数说明

参数名 参数描述 类型 是否必填
ServerSideEncryption 服务段加密配置,AES256 表示使用 SSE-COS 加密,cos/kms 表示使用 KMS 加密 String
SSEKMSKeyId 当 ServerSideEncryption='cos/kms'时,可以填写 KMS 的用户主密钥 CMK,如不填写则使用 COS 默认创建的 CMK String
SSEKMSContext 当ServerSideEncryption='cos/kms'时,可以填加密上下文,值为 JSON 格式加密上下文键值对的 Base64 编码 String

使用 SSE-C 服务端加密保护数据

加密密钥由用户自己提供,用户在上传对象时,COS 将使用用户提供的加密密钥对用户的数据进行 AES-256 加密。

注意:

  • 该加密所运行的服务需要使用 HTTPS 请求。
  • customerKey:用户提供的密钥,传入一个32字节的字符串,支持数字、字母、字符的组合,不支持中文。
  • 如果上传的源文件调用了该方法,那么在使用 GET(下载)、HEAD(查询)时对源对象操作的时候也要调用该方法。

请求示例:上传、下载、拷贝、取回 SSE-C 加密对象

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
from qcloud_cos.cos_comm import get_md5, to_byte

import sys
import logging
import base64

# 正常情况日志级别使用INFO,需要定位时可以修改为DEBUG,此时SDK会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在CosConfig中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = 'SecretId'     # 替换为用户的 SecretId,请登录访问管理控制台进行查看和管理,https://console.cloud.tencent.com/cam/capi
secret_key = 'SecretKey'   # 替换为用户的 SecretKey,请登录访问管理控制台进行查看和管理,https://console.cloud.tencent.com/cam/capi
region = 'ap-beijing'      # 替换为用户的 region,已创建桶归属的region可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
                           # COS支持的所有region列表参见https://cloud.tencent.com/document/product/436/6224
token = None               # 如果使用永久密钥不需要填入token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见https://cloud.tencent.com/document/product/436/14048
scheme = 'https'           # 服务端加密必须使用https

config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)  # 获取配置对象
client = CosS3Client(config)
bucket = 'examplebucket-125000000'
file_name = 'sdk-sse-c'

# 编码和哈希加密密钥
ssec_secret = '00000000000000000000000000000001' # 原始密钥需要是32位
ssec_key = base64.standard_b64encode(to_bytes(ssec_secret)) # 密钥必须Base64编码
ssec_key_md5 = get_md5(ssec_secret)

# 上传SSE-C加密对象
response = client.put_object(
    Bucket=bucket, Key=file_name, Body="00000",
    SSECustomerAlgorithm='AES256', SSECustomerKey=ssec_key, SSECustomerKeyMD5=ssec_key_md5)
print(response['x-cos-server-side-encryption-customer-algorithm']) # 服务端返回'x-cos-server-side-encryption-customer-algorithm': 'AES256' 表示是SSE-C对象

# 下载SSE-C加密对象
response = client.get_object(
    Bucket=bucket, Key=file_name,
    SSECustomerAlgorithm='AES256', SSECustomerKey=ssec_key, SSECustomerKeyMD5=ssec_key_md5)
print(response['x-cos-server-side-encryption-customer-algorithm']) # 服务端返回'x-cos-server-side-encryption-customer-algorithm': 'AES256' 表示是SSE-C对象

# HEAD SSE-C加密对象
response = client.head_object(
    Bucket=bucket, Key=file_name, 
    SSECustomerAlgorithm='AES256', SSECustomerKey=ssec_key, SSECustomerKeyMD5=ssec_key_md5)
print(response['x-cos-server-side-encryption-customer-algorithm']) # 服务端返回'x-cos-server-side-encryption-customer-algorithm': 'AES256' 表示是SSE-C对象

# 高级接口上传SSE-C加密对象
response = client.upload_file(
    Bucket=bucket, Key=file_name, LocalFilePath="sdk-sse-c.local",
    SSECustomerAlgorithm='AES256', SSECustomerKey=ssec_key, SSECustomerKeyMD5=ssec_key_md5)

# 高级接口下载SSE-C加密对象
response = client.download_file(
    Bucket=bucket, Key=file_name, DestFilePath='sdk-sse-c.local',
    SSECustomerAlgorithm='AES256', SSECustomerKey=ssec_key, SSECustomerKeyMD5=ssec_key_md5)

# 拷贝SSE-C加密对象,源和目标的加密类型和密钥可以不一样。例子中的源对象是SSE-C类型,目标对象也是SSE-C类型。
dest_ssec_secret = '00000000000000000000000000000002' # 密钥需要是32位
dest_ssec_key = base64.standard_b64encode(to_bytes(dest_ssec_secret))
dest_ssec_key_md5 = get_md5(dest_ssec_secret)
copy_source = {'Bucket': bucket, 'Key': file_name, 'Region': region}
response = client.copy_object(
    Bucket=bucket, Key='sdk-sse-c-copy', CopySource=copy_source,
    SSECustomerAlgorithm='AES256', SSECustomerKey=dest_ssec_key, SSECustomerKeyMD5=dest_ssec_key_md5,
    CopySourceSSECustomerAlgorithm='AES256', CopySourceSSECustomerKey=ssec_key, CopySourceSSECustomerKeyMD5=ssec_key_md5
)

# 高级接口拷贝SSE-C加密对象
response = client.copy(
    Bucket=bucket, Key='sdk-sse-c-copy', CopySource=copy_source, MAXThread=2,
    SSECustomerAlgorithm='AES256', SSECustomerKey=dest_ssec_key, SSECustomerKeyMD5=dest_ssec_key_md5,
    CopySourceSSECustomerAlgorithm='AES256', CopySourceSSECustomerKey=ssec_key, CopySourceSSECustomerKeyMD5=ssec_key_md5)

# 取回SSE-C加密对象
response = client.restore_object(
    Bucket=bucket, Key=file_name, RestoreRequest={
        'Days': 1,
        'CASJobParameters': {
            'Tier': 'Expedited'
        }
    }, 
    SSECustomerAlgorithm='AES256', SSECustomerKey=ssec_key, SSECustomerKeyMD5=ssec_key_md5)

参数说明

参数名 参数描述 类型 是否必填
SSECustomerAlgorithm SSE-C 加密算法,目前只支持 AES256 String
SSECustomerKey 用户的加密密钥,密钥需要是32位字符串,支持数字、字母、字符的组合,不支持中文,并且使用 Base64 编码 String SSECustomerAlgorithm 存在时必填
SSECustomerKeyMD5 用户的加密密钥 MD5 值,用于服务端校验密钥完整性 String SSECustomerAlgorithm 存在时必填
CopySourceSSECustomerAlgorithm 在拷贝接口中,如果源对象使用了 SSE-C 加密,则需要通过此参数指定源对象的加密算法,目前只支持 AES256 String
CopySourceSSECustomerKey 在拷贝接口中,如果源对象使用了 SSE-C 加密,则需要通过此参数指定源对象的加密密钥,密钥需要是32位字符串,并且使用 Base64 编码 String CopySourceSSECustomerAlgorithm 存在时必填
CopySourceSSECustomerKeyMD5 在拷贝接口中,如果源对象使用了 SSE-C 加密,需要通过此参数指定源对象的加密密钥 MD5 值,用于服务端校验密钥完整性 String CopySourceSSECustomerAlgorithm 存在时必填
目录