# 推理会话数据应用层加密方案
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
> **注意**
>
> 您调用 SDK 时，仅需增加行代码，即可免费使用本功能，代码示例请参见[加密数据](/docs/sdk-common-examples#23274b89)。
**为了保证推理会话数据的传输安全**，在默认的网络层加密方案基础上，方舟安全团队为**在线推理的会话数据**提供了**端到端应用层加密**方案，支持用户通过 SDK 在本地对推理会话的内容进行加密。
为什么需要网络层和应用层的双层加密？请看这个形象的比喻：网络层的加密就像给文件加了一层保险盒，而应用层加密就如同再给保险盒上了一把锁，双重保险确保即便有人拦截了这个文件，也无从打开它。
## 方案介绍
会话数据应用层加密的具体流程，如下面的视频所示：
[视频](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/7bf6cbf4e1cd4c4c82d6a2a21dddfec6)
用户可以依靠 SDK 在本地私域对推理会话内容进行加密，会话密文安全传输至沙箱后，仅在安全沙箱内存中解密成明文，用于模型推理。安全沙箱内的模型推理结束后，生成的推理结果会由安全沙箱加密，以密文的形式从安全沙箱传输至用户私域，最终由用户通过 SDK 在本地解密，获取明文推理结果。
## 使用说明
推理会话数据应用层加密功能集成在火山 SDK 中，**仅需增加几行代码，即可免费使用该功能**，示例代码请参见[加密数据](/docs/sdk-common-examples#23274b89)。
> **说明**
>
> * 语言情况：目前仅支持 Python SDK、Java SDK。
> * 版本要求：
>
> * Python SDK：需要保证 SDK 版本 `volcengine-python-sdk` `1.0.104`及以上。参考[升级 Python SDK](/docs/install-and-upgrade-sdk#d6b883b8)获得 SDK 的最新版本。
>
> * Java SDK：需要保证 SDK 版本 `volcengine-java-sdk-ark-runtime` `0.2.50`及以上。参考[升级 Java SDK](/docs/install-and-upgrade-sdk#4ab4182d)获得 SDK 的最新版本。
> * 三方支持：不支持三方 SDK ，包括 OpenAI SDK。
> * 能力支持：仅支持火山方舟平台发布的文生文对话模型和 Doubao-vision 系列图片理解模型（注：图片仅支持 Base64 图片加密， URL 图片无法加密）请求，仅支持 Chat Completions 中的单轮/多轮会话，支持流式/非流式，同步/异步调用。
|SDK 语言 |功能说明 |上线时间 |
|---|---|---|
|Python |1.0.104 正式支持应用层端到端加密能力 |2024-10-10 |
|Python |1.0.111 更新 Cryptography 依赖版本至最新 |2024-11-29 |
|Python |1.0.117 更新支持 Doubao-vision 系列模型请求 |2024-12-23 |
|Python |1.0.119 支持 API-Key 请求证书，本地缓存证书 |2025-01-02 |
|Python |1.0.121-125 暂不支持 AK/SK 获取证书 |2025-01-16 |
|Python |1.0.126 优先使用 API-Key 获取证书 |2025-02-27 |
|Python |3.0.3 支持 batch_chat API |2025-05-22 |
|Python |3.0.15 Cryptography 最低支持版本为 42.0.0，对于chat api风控情况输出导致的解密 exception 的修复 |2025-06-19 |
|Python |4.0.5 修复并发情况下本地证书目录冲突异常；修复会话加密情况下对 Chat 数据的内存修改 |2025-07-10 |
|Python |4.0.13 由于 [CVE-2024-12797](https://github.com/advisories/GHSA-79v4-65xg-pq4g)，火山SDK没有使用受 CVE 影响的 feature，更新 Cryptography 依赖版本最低为 44.0.1 |2025-08-22 |
|Python |4.0.16 缓存目录更新为当前用户的目录 |2025-09-04 |
|Python |4.0.22 解决部分非流式请求结果解密失败问题 |2025-09-25 |
|Python |4.0.25 解决部分非流式请求结果解密失败问题，TKS 加解密支持; batch chat加密功能暂时存在问题 |2025-10-16 |
|Python |4.0.29 解决非流式请求结果解密失败问题 / batch chat 加密请求失败问题 |2025-10-27 |
|Python |4.0.30 校验本地的数据是否是base64 / http / https URL |2025-10-30 |
|Java |0.2.45 支持 API-Key 请求 Chat 接口进行加解密请求 |2025-11-13 |
|Java |0.2.50 修复普通聊天请求对于 bouncycastle 软件包的依赖问题 |2025-12-04 |
## 原理说明
用 Alice 和 Bob 分别代表客户 SDK 和推理模型所在的安全沙箱容器，基本原理是利用 [ECIES](https://cryptobook.nakov.com/asymmetric-key-ciphers/ecies-public-key-encryption) 实现一个 0-RTT 协议（即让客户端在第一条消息中就发送加密的 Payload 的协议），协议如下：
1. Alice 通过公开渠道获得 Bob 的公钥`PK[Bob]`，该公钥须是椭圆曲线公钥。
2. Alice 生成随机数`r` ，通过和椭圆曲线基点相乘获得`R = r × G`，`R`为会话密钥的密文。会话密钥`S = r × PK[Bob]`，使用会话密钥`S`衍生密钥加密明文得到会话密文`Payload`。将`(R, Payload)`发送给 Bob。
3. Bob 收到`R`后利用自己的私钥解密会话密钥`SK[Bob] × R = SK[Bob] × r × G = S`，使用`S`衍生密钥解密密文`Payload`得到会话明文。
## 验证说明
#### 验证消息加密
动作：SDK 调用时，会对其中的 `content` 字段进行加密并使用 base64 编码。
验证：通过抓包工具的 `HTTPS` 抓包，查看请求体 `body` 中的会话数据是否是密文。
#### 验证证书获取
动作：使用 AK/SK 初始化客户端 SDK ，每个推理接入点第一次请求会话数据应用层加密时，会调用 GetEndpointCertificate 接口，用于获取该接入点对应的证书。
验证：可以在 [云审计](https://console.volcengine.com/cloudtrail/event) 查看 GetEndpointCertificate 接口的调用日志。
## **证书说明**
该证书仅适用于火山方舟平台发布的文生文对话模型和 Doubao-vision 系列图片理解模型（[模型发布公告](/docs/model-release-announcement)）。
客户从公开渠道获得的椭圆曲线公钥统一来自于豆包模型的自签名证书，豆包模型均使用同一份公钥，对应的私钥托管在 [火山私有 CA 服务](https://docs.volcengine.com/docs/6638/196517?lang=zh)，使用的是 P-256 椭圆曲线。
豆包模型的证书可以通过方舟 OpenAPI 获取，接口是 [GetEndpointCertificate](/docs/get-endpoint-certificate-api)。
证书详情：
| | | |
|证书的密钥算法 ||ECDSA 256 |
|---|---|---|
| | | |
|证书的签名算法 ||ECDSA-SHA256 |
|证书的序列号 ||1BC6311337412676230446127358F676227CFEE3 |
|证书的主体信息 |国家（C） |CN |
| |企业名称（O） |Volcano Engine Ark |
| |部门（OU） |Security |
| |城市（L） |Beijing |
| |省份（ST） |Beijing |
| |公用名（CN） |MaaS Crypto SDK Online |
|证书信息 |叶子证书 |```Plain Text | \
| | |-----BEGIN CERTIFICATE----- | \
| | |MIICxjCCAm2gAwIBAgIUG8YxEzdBJnYjBEYSc1j2diJ8/uMwCgYIKoZIzj0EAwIw | \
| | |gYQxITAfBgNVBAMMGE1hYVMgU0RLIFN1YiBDQSBFQ0MgUDI1NjEbMBkGA1UECgwS | \
| | |Vm9sY2FubyBFbmdpbmUgQXJrMREwDwYDVQQLDAhTZWN1cml0eTELMAkGA1UEBhMC | \
| | |Q04xEDAOBgNVBAgMB0JlaWppbmcxEDAOBgNVBAcMB0JlaWppbmcwHhcNMjQwMTAz | \
| | |MDY1MjM4WhcNMjkwMTAzMDY1MjM4WjCBgjELMAkGA1UEBhMCQ04xEDAOBgNVBAgT | \
| | |B0JlaWppbmcxEDAOBgNVBAcTB0JlaWppbmcxGzAZBgNVBAoTElZvbGNhbm8gRW5n | \
| | |aW5lIEFyazERMA8GA1UECxMIU2VjdXJpdHkxHzAdBgNVBAMTFk1hYVMgQ3J5cHRv | \
| | |IFNESyBPbmxpbmUwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATD7RyZC51FCwuK | \
| | |xYKh2ZCwIvbNDvQfosUk3gKc0B/+euemDWDAaVazuBOm8okHsSmUrsEudeksRruG | \
| | |LTGu1lBxo4G8MIG5MA4GA1UdDwEB/wQEAwIDiDBYBgNVHR8EUTBPME2gS6BJhkdo | \
| | |dHRwOi8vY3JsLnZvbGNjYS5jb20vdm9sYzE/c249NURCNEUwNDNFRjQ3MEY3RDBB | \
| | |REU0RDIyMTNBNTU1NTEzMjEyOEM3MzA4BggrBgEFBQcBAQQsMCowKAYIKwYBBQUH | \
| | |MAGGHGh0dHA6Ly9vY3NwLnZvbGNjYS5jb20vdm9sYzEwEwYDVR0lBAwwCgYIKwYB | \
| | |BQUHAwEwCgYIKoZIzj0EAwIDRwAwRAIgFSel9WBkyPmpdG6YzReb7ShCVKq3scT3 | \
| | |9T2mfBgooPkCIHpRalKvIJX5S9oSyTf6iQiUcwzfUHd47Ew+PUV7O6aq | \
| | |-----END CERTIFICATE----- | \
| | |``` |
| |中间根证书 |```Plain Text | \
| | |-----BEGIN CERTIFICATE----- | \
| | |MIIDCDCCAq+gAwIBAgIUXbTgQ+9HD30K3k0iE6VVUTISjHMwCgYIKoZIzj0EAwIw | \
| | |gYUxIjAgBgNVBAMMGU1hYVMgU0RLIFJvb3QgQ0EgRUNDIFAyNTYxGzAZBgNVBAoM | \
| | |ElZvbGNhbm8gRW5naW5lIEFyazERMA8GA1UECwwIU2VjdXJpdHkxCzAJBgNVBAYT | \
| | |AkNOMRAwDgYDVQQIDAdCZWlqaW5nMRAwDgYDVQQHDAdCZWlqaW5nMB4XDTI0MDEw | \
| | |MzA2NDUyMVoXDTM0MDEwMzE1NTk1OVowgYQxITAfBgNVBAMMGE1hYVMgU0RLIFN1 | \
| | |YiBDQSBFQ0MgUDI1NjEbMBkGA1UECgwSVm9sY2FubyBFbmdpbmUgQXJrMREwDwYD | \
| | |VQQLDAhTZWN1cml0eTELMAkGA1UEBhMCQ04xEDAOBgNVBAgMB0JlaWppbmcxEDAO | \
| | |BgNVBAcMB0JlaWppbmcwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATc+JkMHj6F | \
| | |22yAIQWIDlbGikKHcy77VNfQRLi8HNCAipNfKktlocMJUD7uvaomfn3cvcI/YAEk | \
| | |r1NA+OyINzeno4H7MIH4MBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQD | \
| | |AgGGMFgGA1UdHwRRME8wTaBLoEmGR2h0dHA6Ly9jcmwudm9sY2NhLmNvbS92b2xj | \
| | |MT9zbj0yRjU0Q0U1NUJDMjI2MzEzQ0Q1RUI4NkZDQTU0RTZGOUFFOEIwMzQwMDgG | \
| | |CCsGAQUFBwEBBCwwKjAoBggrBgEFBQcwAYYcaHR0cDovL29jc3Audm9sY2NhLmNv | \
| | |bS92b2xjMTAdBgNVHQ4EFgQU53TjY9gSc5gAQDq4lrjIfOAj1DEwHwYDVR0jBBgw | \
| | |FoAUjqqup74+HmschrVwON2NKvZtp9IwCgYIKoZIzj0EAwIDRwAwRAIgVrljBWvr | \
| | |a4LfaYVKqRANxpqS6YLGLCHtDdnhYtim+ZICICbtI8mtHkKLxhqvJDEjf7GU3ssX | \
| | |6Nq8pRWHxAmsx6DC | \
| | |-----END CERTIFICATE----- | \
| | |``` |
| |根证书 |```Plain Text | \
| | |-----BEGIN CERTIFICATE----- | \
| | |MIIDCzCCArCgAwIBAgIUL1TOVbwiYxPNXrhvylTm+a6LA0AwCgYIKoZIzj0EAwIw | \
| | |gYUxIjAgBgNVBAMMGU1hYVMgU0RLIFJvb3QgQ0EgRUNDIFAyNTYxGzAZBgNVBAoM | \
| | |ElZvbGNhbm8gRW5naW5lIEFyazERMA8GA1UECwwIU2VjdXJpdHkxCzAJBgNVBAYT | \
| | |AkNOMRAwDgYDVQQIDAdCZWlqaW5nMRAwDgYDVQQHDAdCZWlqaW5nMB4XDTI0MDEw | \
| | |MzA2NDQwOVoXDTM0MDEwMzE1NTk1OVowgYUxIjAgBgNVBAMMGU1hYVMgU0RLIFJv | \
| | |b3QgQ0EgRUNDIFAyNTYxGzAZBgNVBAoMElZvbGNhbm8gRW5naW5lIEFyazERMA8G | \
| | |A1UECwwIU2VjdXJpdHkxCzAJBgNVBAYTAkNOMRAwDgYDVQQIDAdCZWlqaW5nMRAw | \
| | |DgYDVQQHDAdCZWlqaW5nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgT4ZCpVh | \
| | |Bas9kCTPnA22SoE4QGyK5VZiy6a5NQ/q99EZT2jxFyP8xqsKPUWAdike2l93uSAC | \
| | |G7Jd4yK5nn58BqOB+zCB+DASBgNVHRMBAf8ECDAGAQH/AgEBMA4GA1UdDwEB/wQE | \
| | |AwIBhjBYBgNVHR8EUTBPME2gS6BJhkdodHRwOi8vY3JsLnZvbGNjYS5jb20vdm9s | \
| | |YzE/c249MkY1NENFNTVCQzIyNjMxM0NENUVCODZGQ0E1NEU2RjlBRThCMDM0MDA4 | \
| | |BggrBgEFBQcBAQQsMCowKAYIKwYBBQUHMAGGHGh0dHA6Ly9vY3NwLnZvbGNjYS5j | \
| | |b20vdm9sYzEwHQYDVR0OBBYEFI6qrqe+Ph5rHIa1cDjdjSr2bafSMB8GA1UdIwQY | \
| | |MBaAFI6qrqe+Ph5rHIa1cDjdjSr2bafSMAoGCCqGSM49BAMCA0kAMEYCIQCzOoAV | \
| | |vy4XHibX6+8gi9KkGCG9WLzYPKMrI1BlFN7DNAIhAKEiFkaMn/tBuytndKduE2Bx | \
| | |G2KI5sUSpiB8EEYvuoNP | \
| | |-----END CERTIFICATE----- | \
| | |``` |
|证书的创建时间 ||1704264758 |
|证书的过期时间 ||1862117558 |
|证书的生效时间 ||1704264758 |
|证书的有效时长 ||5 年 |
叶子证书信息：
[certificate.pem](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/d4ea207203ae48ef928935d6da33b6c5~tplv-goo7wpa0wc-image.image)
中间根证书和根证书信息：
[certificate_chain.pem](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/f62e5a90d74848c3a150734fc6521f2d~tplv-goo7wpa0wc-image.image)
## 性能说明
在 Intel(R) Xeon(R) Platinum 8260 CPU ＠ 2.40GHz 单核情况下，按照消息长度 256 字节计算，一次对话请求的加解密额外耗时平均为 0.5786 ms。