通过 PSP 解密功能,您可以使用自己控制的非对称密钥,读取已连接的云端存储中的 PSP 记录内容。
取得记录及其原始密钥元数据后,您即可使用云端密钥管理服务和本地代码完成解密,无需调用 OpenAI API。
本指南适用于启用 PSP 的 ZDR 配置。对于启用 PSP 的私有保留配置,记录存储在 OpenAI 托管的基础设施中,因此本指南不适用。
您的云端密钥管理服务负责解密一个小型恢复封装。您的应用程序使用从封装中恢复的秘密值在本地解密记录。您的私钥始终保存在云端密钥管理服务中。
附录介绍了记录包的格式,并提供了本地解密示例。
准备工作
- 启用 PSP 解密,连接存储并选择恢复密钥。请参阅 PSP 解密和设置非对称密钥。
- 授予应用程序读取存储对象的权限,以及使用该记录的原始 RSA-3072 恢复密钥进行解密的权限。
- 只要仍有记录依赖原始注册信息、公钥和对应版本的云端密钥,就请保留这些信息和密钥。
只有在写入时已为您的密钥启用 PSP 解密的记录,才能使用该密钥解密。已有记录不会被转换。
解密记录
1. 读取记录
从云端存储中读取记录。如果记录带有 EKM 存储信封,请先使用其原始 EKM 配置解密这一层。
如果使用 OCI EKM,恢复应用程序还需要对原始 AES 密钥具有 KEY_DECRYPT 权限。解密这一层时,请保留信封中的密钥版本以及与作用域关联的数据。
解析得到的 JSON 记录包,其中包含 protected_record 和 customer_access,具体结构见记录包格式。如果 customer_access 为 null,则无法对该记录使用 PSP 解密。
2. 选择原始密钥
使用 customer_access.customer_key_id 在您保存的注册元数据中查找原始云端密钥及其版本。您也可以使用组织的 Admin API 密钥,通过 Admin API 调用 GET /v1/organization/external_keys/{customer_key_id} 来获取注册信息。请参阅获取密钥注册信息。
核对公钥指纹,并确保使用的云端密钥及其版本与注册信息完全一致。请将私钥保存在您的云端密钥管理服务中,切勿与 OpenAI 共享。
3. 解密恢复封装
将解码后的 customer_access.recovery_secret 发送到您的云端密钥管理服务,使用 RSA-OAEP-SHA256 解密。
如果使用 OCI Vault,请通过该保管库的密码运算端点调用 Decrypt 操作,并按下表设置字段:
| 字段 | 值 |
|---|---|
keyId |
原始注册信息中的 key_ocid |
keyVersionId |
原始注册信息中的 key_version_ocid 原值 |
encryptionAlgorithm |
RSA_OAEP_SHA_256 |
ciphertext |
将恢复密文的字节序列按标准 Base64 编码后得到的值 |
记录包使用 base64url 编码。请先解码 recovery_secret,再将得到的字节序列按标准 Base64 编码,供 OCI 使用。对响应中以 Base64 编码的 plaintext 进行解码,即可得到第 4 步所需的恢复封装。此时仍需解密记录本身。
恢复应用程序使用的 OCI 身份必须对原始 RSA 密钥具有 KEY_DECRYPT 权限。此权限与 OpenAI 读取公钥的权限相互独立。密钥轮换后,请确保原始版本仍然可用。执行此 RSA 操作时,请省略 associatedData。
4. 解密并验证内容
使用解密示例检查恢复封装是否与该记录绑定,并在本地解密内容。
只有在所有检查和 AES-GCM 认证均通过后,才能返回内容。
检查结果
操作成功后会返回通过认证的 UTF-8 内容。请求记录包含 request_text,以及指明是否发生截断的元数据。请参阅恢复的内容。
故障排查
| 结果 | 检查事项 |
|---|---|
customer_access 为 null |
写入该记录时,未为恢复密钥启用 PSP 解密。事后选择密钥也无法为该记录启用 PSP 解密。 |
| KMS 拒绝访问或密钥不可用 | 检查是否具有解密权限,以及原始云端密钥及其对应版本是否可用。 |
| 指纹或绑定关系不匹配 | 核对目标记录及其原始注册信息。请勿修改受认证保护的字段,也不要换用其他密钥。 |
| AES-GCM 认证失败 | 检查传给解密示例的输入。请勿返回部分明文。 |
相关指南
附录:格式与解密参考
本附录适用于版本为 1 的记录包和版本为 v4 的受保护记录。使用下面的示例,即可在不依赖 OpenAI 库的情况下实现本地解密。
记录包格式
该对象采用 UTF-8 编码的 JSON 格式,结构如下。尖括号中的内容为占位符。
{
"bundle_version": 1,
"protected_record": {
"version": "v4",
"algorithm": "HPKE-v1-DHKEM_P256_HKDF_SHA256-EXPORT_ONLY-AES256_GCM",
"scope": "global",
"key_thumbprint": "<runtime public-key thumbprint>",
"expires_at": "2026-11-20",
"content_id": "<content ID>",
"encrypted_dek": "<E: base64url P-256 public point>",
"safety_review_runtime_public_key": "<R: base64url P-256 public point>",
"nonce": "<base64url 12-byte nonce>",
"encrypted_cot": ["<opaque encrypted CoT string>"],
"ciphertext": "<base64url ciphertext followed by GCM tag>"
},
"customer_access": {
"version": 1,
"algorithm": "RSA-OAEP-256",
"customer_key_id": "<original registration ID>",
"customer_public_key_fingerprint": "<RSA public-key fingerprint>",
"recovery_secret": "<base64url RSA ciphertext>"
}
}
encrypted_cot 包含加密的思维链内容。您的客户恢复密钥无法解密这些内容。该数组可能为空。
解密示例
如果记录带有单独的 EKM 存储信封,请先将其解密。使用原始云端密钥解密恢复封装后,即可运行以下示例。示例代码先检查密钥指纹、封装与记录的绑定关系、恢复出的标量以及运行时密钥指纹,再对有效载荷进行认证和解密。
如果使用 Python,请安装 pyhpke、cryptography 和 rfc8785。
如果使用 Ruby,请安装 hpke、json-canonicalization 和 OpenSSL 的 Ruby 绑定。
如果使用 Go,请安装 github.com/cyberphone/json-canonicalization/go/src/webpki.org/jsoncanonicalizer。完整的示例程序使用 Go 的密码学包执行 P-256、HKDF 和 AES-GCM 运算。程序中的 recoverRecord 函数接受下文列出的四个参数。该命令从标准输入读取一个包含 bundle、capsule、key_id 和 public_key 字段的 JSON 对象。请使用标准 Base64 对恢复封装进行编码。
将以下参数传给恢复函数:
bundle_json:内部记录包,表示为 UTF-8 编码的 JSON 字节序列。capsule:云端密钥管理服务返回的字节序列。original_key_id:第 2 步中查到的原始密钥注册 ID。original_public_key_pem:该版本云端密钥的 RSA 公钥,以 PEM 格式的字节序列传入。
该函数以 UTF-8 字符串形式返回解密后的内容。任何一项检查失败都会终止恢复过程。
import base64
import hashlib
import hmac
import json
import rfc8785
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ec, rsa
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
from pyhpke import AEADId, CipherSuite, KDFId, KEMId, KEMKey, KEMKeyPair
def recover_record(bundle_json, capsule, original_key_id, original_public_key_pem):
"""Return plaintext from exact inner bundle bytes and a decrypted capsule.
Use the documented schema and trusted original key ID/RSA public PEM.
No cloud calls occur here. The RSA private key stays in the cloud.
"""
record, access, runtime, nonce, ciphertext = validate_bundle(
bundle_json, original_key_id, original_public_key_pem
)
e = recover_scalar(record, access, capsule)
ephemeral = ec.derive_private_key(e, ec.SECP256R1())
pair = KEMKeyPair(
KEMKey.from_pyca_cryptography_key(ephemeral),
KEMKey.from_pyca_cryptography_key(ephemeral.public_key()),
)
suite = CipherSuite.new(
KEMId.DHKEM_P256_HKDF_SHA256, KDFId.HKDF_SHA256, AEADId.EXPORT_ONLY
)
enc, sender = suite.create_sender_context(
KEMKey.from_pyca_cryptography_key(runtime),
info=b"OpenAI-PSP-v4/HPKE-export",
eks=pair,
)
require(enc == decode64(record["encrypted_dek"]), "Wrong recovered scalar")
aad = rfc8785.dumps({k: v for k, v in record.items() if k != "ciphertext"})
key = sender.export(b"OpenAI-PSP-v4/payload-key" + hashlib.sha256(aad).digest(), 32)
return AESGCM(key).decrypt(nonce, ciphertext, aad).decode("utf-8")
def validate_bundle(bundle_json, original_key_id, original_public_key_pem):
bundle = json.loads(bundle_json.decode("utf-8"), object_pairs_hook=unique_object)
require(
type(bundle["bundle_version"]) is int and bundle["bundle_version"] == 1,
"Unsupported bundle version",
)
record, access = bundle["protected_record"], bundle["customer_access"]
require(access is not None, "Customer recovery is unavailable")
require(
record["version"] == "v4"
and record["algorithm"]
== "HPKE-v1-DHKEM_P256_HKDF_SHA256-EXPORT_ONLY-AES256_GCM",
"Unsupported record",
)
require(
type(access["version"]) is int
and access["version"] == 1
and access["algorithm"] == "RSA-OAEP-256",
"Unsupported recovery capsule",
)
require(access["customer_key_id"] == original_key_id, "Wrong key registration")
require(len(decode64(access["recovery_secret"])) == 384, "Wrong RSA length")
public_key = serialization.load_pem_public_key(original_public_key_pem)
require(isinstance(public_key, rsa.RSAPublicKey), "Expected an RSA public key")
require(public_key.key_size == 3072, "Expected RSA-3072")
spki = public_key.public_bytes(
serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo
)
fingerprint = decode64(access["customer_public_key_fingerprint"])
require(
hmac.compare_digest(fingerprint, hashlib.sha256(spki).digest()), "Wrong key"
)
runtime = point(record["safety_review_runtime_public_key"])
coordinates = runtime.public_numbers()
jwk = {
"crv": "P-256",
"kty": "EC",
"x": b64url(coordinates.x.to_bytes(32, "big")),
"y": b64url(coordinates.y.to_bytes(32, "big")),
}
thumbprint = b64url(hashlib.sha256(rfc8785.dumps(jwk)).digest())
require(record["key_thumbprint"] == thumbprint, "Wrong runtime key")
nonce, ciphertext = decode64(record["nonce"]), decode64(record["ciphertext"])
require(len(nonce) == 12 and len(ciphertext) >= 16, "Invalid AES-GCM encoding")
return record, access, runtime, nonce, ciphertext
def recover_scalar(record, access, capsule):
header = {k: v for k, v in access.items() if k != "recovery_secret"}
binding_input = {
"purpose": "OpenAI-PSP-v4/customer-recovery-binding",
"bundle_version": 1,
"record": record,
"recovery_header": header,
}
binding = hashlib.sha256(rfc8785.dumps(binding_input)).digest()
require(
isinstance(capsule, bytes)
and len(capsule) == 72
and capsule[:8] == b"PSPv4\x00\x00\x01"
and hmac.compare_digest(capsule[40:], binding),
"Invalid recovery capsule binding",
)
e = int.from_bytes(capsule[8:40], "big")
order = 0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551
require(1 <= e < order, "Invalid P-256 private scalar")
return e
def require(condition, message):
if not condition:
raise ValueError(message)
def unique_object(pairs):
require(len(pairs) == len(dict(pairs)), "Duplicate JSON field")
return dict(pairs)
def b64url(data):
return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
def decode64(value):
# Restore omitted "=" padding: -len(value) % 4 is how many characters
# are needed to reach a multiple of four (e.g. length 10 needs "==").
data = base64.b64decode(
value + "=" * (-len(value) % 4), altchars=b"-_", validate=True
)
require(b64url(data) == value, "Noncanonical base64url")
return data
def point(value):
encoded = decode64(value)
require(len(encoded) == 65 and encoded[0] == 4, "Invalid P-256 encoding")
return ec.EllipticCurvePublicKey.from_encoded_point(ec.SECP256R1(), encoded)恢复的内容
对于请求记录,如果恢复出的 JSON 包含 format: "psp_request_v1",则 request_text 包含留存的请求文本。其他字段包括 reasoning_summaries(字符串数组)、request_text_truncated(布尔值)和 reasoning_summary_parts_omitted(非负整数)。解读结果时,请检查与截断有关的字段。其他类型的受保护内容可能采用不同的明文格式。
只要您的原始客户恢复密钥和快照仍然可用,即使 OpenAI 运行时密钥已经过期,您仍然可以恢复内容。请保留受认证保护的 expires_at 原值。encrypted_cot 中的数据块单独加密,客户仍然无法通过恢复流程读取其明文。