当请求内容涉及敏感信息或通过公网传输时,您可以对请求体中的input字段值加密,防止数据在传输过程中被窃听或篡改。
加解密过程
-
准备请求数据。
-
生成AES对称密钥。AES是一种高效的对称加密算法,在此用于加密
input内容。说明:
input为大模型应用调用请求中的核心对象,包含对话消息(messages)等参数,本文示例均通过messages传入对话内容。 -
使用密钥对
input内容进行加密。 -
使用RSA公钥对AES密钥进行加密。从阿里云百炼平台获取托管的RSA公钥,对AES密钥进行加密,以确保AES密钥的传输安全。
说明:RSA是一种非对称加密算法,包括公钥和私钥。其中公钥用于加密数据,私钥用于解密数据。
-
生成AES对称密钥。AES是一种高效的对称加密算法,在此用于加密
-
发起请求。发起阿里云百炼平台调用时将加密后的
input内容、密钥信息(封装在X-DashScope-EncryptionKey请求头中)传入阿里云百炼平台。 -
阿里云百炼平台处理请求。
- 阿里云百炼推理链路中全程加密。
- 阿里云百炼平台在向量召回、模型推理过程中解密数据。
- 使用相同的AES密钥加密生成的答案,返回加密后的推理结果。
- 处理响应结果。用户侧收到响应内容,使用AES密钥解密推理结果,获得明文答案。
前提条件
已开通阿里云百炼服务并获得API-KEY:获取与配置 API Key。
重要:建议您将API-KEY配置到环境变量中以降低API-KEY的泄漏风险,配置方法可参考配置API Key到环境变量。您也可以在代码中配置API-KEY,但是泄漏风险会提高。
DashScope SDK调用(自动加密·开箱即用)
DashScope SDK 封装了加解密逻辑,您只需启用加密功能即可实现加密调用,无需自行实现加密和解密代码。
约束与限制
- 不支持自定义密钥,如需自定义密钥,请参见HTTP调用(手动密钥管理)。
- 仅支持Java和Python,其他编程语言请参见HTTP调用(手动密钥管理)。
接入流程
- 安装最新版DashScope SDK。
-
启用加密功能。
- Java SDK
- Python SDK
将enableEncrypt设置为true即可启用加密功能。 - 调用模型。使用与普通调用相同的方式发起请求,SDK会自动完成加解密处理。
SDK完整示例代码
重要:示例代码仅供参考,请勿直接在生产环境中使用。
说明:关于请求参数的更多说明,请参见千问API文档。
- Java SDK
- Python SDK
请求示例响应示例DashScope SDK会自动完成解密,返回的响应内容为明文,无需手动解密。
HTTP调用(手动密钥管理)
说明:此加密调用方式是阿里云百炼平台提供的安全功能。以下加密流程仅适用于DashScope的Endpoint,OpenAI兼容(Chat Completions API和Responses API)的Endpoint不支持此加密机制。
和普通调用的区别
加密调用在普通调用的基础上,需要额外做如下三个处理(详细操作请参见接入流程):
-
添加
X-DashScope-EncryptionKey请求头。X-DashScope-EncryptionKey请求头对应的内容是一个JSON字符串,各参数说明如下:public_key_id:公钥ID。encrypt_key:RSA公钥加密后的AES密钥。iv:初始向量IV。
-
对请求参数
input的内容进行加密。 普通调用和加密调用请求数据的区别: - 对响应数据进行解密。
接入流程
接入流程分为三个阶段:首先准备请求数据(生成AES密钥、生成IV、加密input数据、加密AES密钥),然后构建并发送加密请求,最后解密响应数据。
一、准备请求数据
-
生成AES密钥
- 算法:AES
-
密钥规格:
-
长度:128位(16字节)/192位(24字节)/256位 (32字节)
说明:密钥长度越长,安全性越高,但计算开销越大;256位安全性最高,适用于金融核心数据等高敏感数据保护。
- 随机性:随机生成,建议使用密码学安全随机源
- 唯一性:单次请求有效,禁止复用
-
长度:128位(16字节)/192位(24字节)/256位 (32字节)
- 示例代码:
- 生成初始向量(IV) 生成GCM加密所需的随机初始化向量(IV):使用安全的随机数生成器生成一个12字节的随机字节序列,该字节序列本身即为IV;将IV进行Base64编码仅用于放入请求头传输。 示例代码:
- 加密input数据
- 对序列化后的
input执行AES-GCM加密 - 将加密结果转成字符串格式,待后续构建并发送请求时将其拼接到
input字段中
- 示例代码:
-
使用RSA公钥加密AES密钥
- 算法:RSA
-
处理流程:
- Base64编码原始AES密钥(即步骤1生成的AES密钥)
-
使用RSA公钥(请参见获取RSA的公钥从阿里云百炼平台获取
public_key和public_key_id)对编码后的AES密钥进行加密RSA 公钥无需每次请求都重新获取,建议在客户端缓存公钥(推荐缓存时长 1 分钟),以降低高 QPS 场景下的接口调用压力。公钥在正常情况下不会变更,仅在发生安全事故时才会紧急轮转。因此建议您按如下策略处理公钥缓存:- 正常情况:使用缓存公钥,缓存过期后自动重新获取最新公钥
- 请求报错时:若返回错误码
BadRequest.IllegalInput(错误信息:The input parameter can not be decoded.),说明公钥已失效,需立即重新获取最新公钥,可将影响降至最低
- 对加密结果进行Base64编码
- 示例代码:
二、构建并发送请求
添加X-DashScope-EncryptionKey请求头,并将原先的input替换为加密后的input,然后用和普通调用同样的方式发送请求即可。
以下是X-DashScope-EncryptionKey请求头的参数说明,各参数的值已在上述准备请求数据阶段生成。
public_key_id:公钥ID。encrypt_key:RSA公钥加密后的AES密钥。iv:初始向量IV。
三、解密响应数据
- 算法:AES-GCM
- 参数:
-
处理流程:
- 使用AES-GCM解密
output字段对应的内容。 - 返回明文结果。
- 使用AES-GCM解密
- 示例代码:
HTTP完整示例代码
本节提供Java和Python的完整示例代码,将上述接入流程中的各步骤整合为可直接运行的完整程序。如您使用其他编程语言,请参照接入流程自行实现。
提示:如需其他编程语言的实现,您可以借助大模型将以下代码转换为目标语言。
重要:示例代码仅供参考,请勿直接在生产环境中使用。
说明:关于请求参数的更多说明,请参见千问API文档。请求示例
output字段为Base64编码的密文,需按照上文"三、解密响应数据"的说明手动解密。解密后的output内容示例如下:
常见问题
Q:为什么代码执行报错,“Invalid AES key Length: 294 bytes”?
A:AES密钥长度支持128位(16字节)、192位(24字节)、256 位(32字节),请检查密钥长度设置是否符合要求。
Q:OpenAI兼容(Chat Completions API 和 Responses API)的Endpoint是否支持加密推理?
A:不支持,本文的加密流程仅适用于DashScope SDK和HTTP的Endpoint。
Q:RSA公钥是否需要每次请求都重新获取?
A:不需要。建议在客户端缓存 RSA 公钥(推荐缓存时长 1 分钟),公钥在正常情况下不会变更,仅在发生安全事故时才会紧急轮转。若请求返回错误码 BadRequest.IllegalInput(The input parameter can not be decoded.),则说明公钥已失效,需立即重新获取最新公钥。