如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

解密 PSP 記錄

使用雲端管理的金鑰讀取保留的客戶內容

透過 PSP 解密功能,你可以使用自己掌控的非對稱金鑰,讀取已連接的雲端儲存空間中的 PSP 記錄內容。

取得記錄及其原始金鑰中繼資料後,即可使用雲端金鑰管理服務和本機程式碼解密,無須呼叫 OpenAI API。

本指南適用於搭配 PSP 使用 ZDR 的情境。若搭配 PSP 使用私人保留功能,記錄會儲存在 OpenAI 管理的基礎設施中,因此不適用本指南。

雲端金鑰管理服務會解密一個小型復原膠囊。應用程式接著使用從膠囊中復原的祕密值,在本機解密記錄。私密金鑰會留在雲端金鑰管理服務中。

附錄列出了記錄封裝格式,並提供 Python 範例。

開始前的準備

  • 啟用 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. 解密並驗證內容

使用 Python 範例確認膠囊與該筆記錄的繫結關係,並在本機解密內容。

所有檢查與 AES-GCM 驗證皆通過後,才可傳回內容。

檢查結果

解密成功後,會傳回已通過驗證的 UTF-8 內容。請求記錄包含 request_text,以及指出內容是否遭截斷的中繼資料。請參閱復原的內容。

疑難排解

結果 檢查項目
customer_access 為 null 寫入該筆記錄時,未針對復原金鑰啟用 PSP 解密功能。事後選取金鑰也無法為該筆記錄啟用 PSP 解密功能。
KMS 拒絕存取或金鑰無法使用 確認你具有解密權限,且原始雲端金鑰及其對應版本仍可使用。
指紋或繫結不符 核對要解密的記錄和原始註冊資料。請勿修改受驗證保護的欄位,也不要改用其他金鑰。
AES-GCM 驗證失敗 檢查傳入 Python 範例的資料。請勿傳回部分明文。

相關指南

附錄:格式與解密參考資料

本附錄適用於版本 1 的封裝和版本 v4 的受保護記錄。你可以使用下方的 Python 範例實作本機解密,無須使用 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 包含已加密的思路鏈內容。客戶復原金鑰無法解密這些內容。此陣列可能為空。

Python 範例

如果記錄另有 EKM 儲存封套,請先解密封套。接著,使用原始雲端金鑰解密復原膠囊,再執行下方範例。範例會先檢查金鑰指紋、膠囊與記錄的繫結關係、復原出的純量,以及執行階段公開金鑰的指紋,然後驗證並解密酬載。

在 Python 環境中安裝 pyhpke、cryptography 和 rfc8785。將下列輸入傳給 recover_record:

  • bundle_json:內層記錄封裝,以 UTF-8 編碼的 JSON 位元組表示。
  • capsule:雲端金鑰管理服務傳回的位元組。
  • original_key_id:步驟 2 中的原始金鑰註冊 ID。
  • original_public_key_pem:該版本雲端金鑰的 RSA 公開金鑰,以 PEM 格式的位元組表示。

函式會以 UTF-8 字串傳回解密後的內容。只要有一項檢查失敗,復原作業就會停止。

解密 PSP 記錄
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 資料區塊。