Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

PSP-Datensätze entschlüsseln

Gespeicherte Kundeninhalte mit deinem in der Cloud verwalteten Schlüssel lesen

Mit der PSP-Entschlüsselung kannst du den Inhalt von PSP-Datensätzen in deinem angebundenen Cloud-Speicher lesen. Dafür verwendest du einen asymmetrischen Schlüssel, über den du die Kontrolle hast.

Sobald dir der Datensatz und die zugehörigen ursprünglichen Schlüsselmetadaten vorliegen, kannst du ihn mit dem Schlüsselverwaltungsdienst deines Cloud-Anbieters und lokalem Code entschlüsseln. Dafür brauchst du keine OpenAI-API aufzurufen.

Dieser Leitfaden gilt für ZDR mit PSP. Er gilt nicht für Private Retention mit PSP. Dort werden die Datensätze in einer von OpenAI verwalteten Infrastruktur gespeichert.

Dein Cloud-Schlüsselverwaltungsdienst entschlüsselt eine kleine Wiederherstellungskapsel. Mit dem daraus gewonnenen Geheimnis entschlüsselt deine Anwendung den Datensatz lokal. Dein privater Schlüssel bleibt im Cloud-Schlüsselverwaltungsdienst.

Im Anhang findest du den Aufbau des Datensatzpakets und ein Python-Beispiel.

Voraussetzungen

  • Aktiviere die PSP-Entschlüsselung, binde deinen Speicher an und wähle einen Wiederherstellungsschlüssel aus. Siehe PSP-Entschlüsselung und Asymmetrische Schlüssel einrichten.
  • Erteile deiner Anwendung die Berechtigungen, das gespeicherte Objekt zu lesen und den ursprünglichen RSA-3072-Wiederherstellungsschlüssel des Datensatzes zur Entschlüsselung zu verwenden.
  • Bewahre die ursprüngliche Registrierung, den öffentlichen Schlüssel und den Cloud-Schlüssel in genau der verwendeten Version auf, solange Datensätze davon abhängen.

Mit deinem Schlüssel kannst du nur Datensätze entschlüsseln, bei deren Speicherung die PSP-Entschlüsselung für diesen Schlüssel aktiviert war. Bereits vorhandene Datensätze werden nicht konvertiert.

Einen Datensatz entschlüsseln

1. Datensatz lesen

Lies den Datensatz aus deinem Cloud-Speicher. Wenn er durch eine zusätzliche EKM-Verschlüsselungsschicht geschützt ist, entschlüssle zuerst diese Schicht mit der ursprünglichen EKM-Konfiguration.

Bei OCI EKM benötigt deine Wiederherstellungsanwendung außerdem die Berechtigung KEY_DECRYPT für den ursprünglichen AES-Schlüssel. Verwende beim Entschlüsseln dieser Schicht die Schlüsselversion und die dem Geltungsbereich zugeordneten Daten der Verschlüsselungsschicht unverändert.

Parse das resultierende JSON-Paket mit den Feldern protected_record und customer_access. Den Aufbau zeigt der Abschnitt Paketformat. Hat customer_access den Wert null, ist die PSP-Entschlüsselung für diesen Datensatz nicht verfügbar.

2. Ursprünglichen Schlüssel auswählen

Suche mithilfe von customer_access.customer_key_id in deinen gespeicherten Registrierungsmetadaten nach dem ursprünglichen Cloud-Schlüssel und seiner Version. Du kannst die Registrierung auch über die Admin API abrufen. Rufe dazu GET /v1/organization/external_keys/{customer_key_id} mit einem Admin-API-Schlüssel deiner Organisation auf. Siehe Schlüsselregistrierung abrufen.

Prüfe den Fingerabdruck des öffentlichen Schlüssels und verwende den Cloud-Schlüssel in genau der angegebenen Version. Bewahre den privaten Schlüssel in deinem Cloud-Schlüsselverwaltungsdienst auf. Gib ihn niemals an OpenAI weiter.

3. Wiederherstellungskapsel entschlüsseln

Dekodiere customer_access.recovery_secret und sende den dekodierten Wert an deinen Cloud-Schlüsselverwaltungsdienst, um ihn mit RSA-OAEP-SHA256 zu entschlüsseln.

Rufe bei OCI Vault die Operation Decrypt am kryptografischen Endpunkt deines Vaults mit den folgenden Feldern auf.

Feld Wert
keyId Der Wert von key_ocid aus der ursprünglichen Registrierung
keyVersionId Der exakte Wert von key_version_ocid aus der ursprünglichen Registrierung
encryptionAlgorithm RSA_OAEP_SHA_256
ciphertext Die mit Standard-Base64 kodierten Bytes des verschlüsselten Wiederherstellungsgeheimnisses

Das Paket verwendet die base64url-Kodierung. Dekodiere recovery_secret und kodiere die erhaltenen Bytes anschließend für OCI mit Standard-Base64. Dekodiere den Base64-Wert im Feld plaintext der Antwort. Damit erhältst du die Wiederherstellungskapsel für Schritt 4. Den Datensatz selbst entschlüsselst du erst in diesem Schritt.

Die OCI-Identität deiner Wiederherstellungsanwendung benötigt die Berechtigung KEY_DECRYPT für den ursprünglichen RSA-Schlüssel. Diese Berechtigung ist unabhängig vom Lesezugriff von OpenAI auf den öffentlichen Schlüssel. Halte die ursprüngliche Schlüsselversion auch nach der Schlüsselrotation verfügbar. Lass associatedData bei dieser RSA-Operation weg.

4. Inhalt entschlüsseln und überprüfen

Verwende das Python-Beispiel, um die Bindung der Kapsel an den Datensatz zu prüfen und den Inhalt lokal zu entschlüsseln.

Gib den Inhalt erst zurück, wenn alle Prüfungen und die AES-GCM-Authentifizierung erfolgreich waren.

Ergebnis prüfen

Bei erfolgreicher Entschlüsselung erhältst du authentifizierten UTF-8-Inhalt. Datensätze zu Anfragen enthalten request_text und Metadaten, aus denen hervorgeht, ob Inhalte gekürzt wurden. Siehe Wiederhergestellte Inhalte.

Fehlerbehebung

Ergebnis Was du prüfen solltest
customer_access hat den Wert null Beim Speichern des Datensatzes war die PSP-Entschlüsselung für keinen Wiederherstellungsschlüssel aktiviert. Die nachträgliche Auswahl eines Schlüssels aktiviert die PSP-Entschlüsselung für diesen Datensatz nicht.
KMS-Zugriff verweigert oder Schlüssel nicht verfügbar Prüfe, ob du die Berechtigung zum Entschlüsseln hast und ob der ursprüngliche Cloud-Schlüssel in der benötigten Version verfügbar ist.
Fingerabdruck oder Bindung stimmt nicht überein Prüfe, ob du den richtigen Datensatz und die ursprüngliche Registrierung verwendest. Verändere keine authentifizierten Felder und verwende keinen anderen Schlüssel.
AES-GCM-Authentifizierung schlägt fehl Prüfe die Eingaben für das Python-Beispiel. Gib auch keine Teile des Klartexts zurück.

Weiterführende Leitfäden

Anhang: Referenz zu Format und Entschlüsselung

Dieser Anhang beschreibt Version 1 des Pakets und Version v4 des geschützten Datensatzes. Mit dem folgenden Python-Beispiel kannst du die lokale Entschlüsselung ohne OpenAI-Bibliotheken implementieren.

Paketformat

Das Objekt enthält UTF-8-kodiertes JSON mit der folgenden Struktur. Angaben in spitzen Klammern sind Platzhalter.

{
  "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 enthält verschlüsselte Inhalte der Gedankenkette. Diese Inhalte lassen sich mit deinem Wiederherstellungsschlüssel nicht entschlüsseln. Das Array kann leer sein.

Python-Beispiel

Entschlüssle zunächst eine gegebenenfalls vorhandene separate EKM-Verschlüsselungsschicht und anschließend die Wiederherstellungskapsel mit dem ursprünglichen Cloud-Schlüssel. Danach kannst du das folgende Beispiel verwenden. Der Code prüft den Fingerabdruck des Schlüssels, die Bindung der Kapsel an den Datensatz, den wiederhergestellten Skalar und den Fingerabdruck des Laufzeitschlüssels. Anschließend authentifiziert und entschlüsselt er die Nutzdaten.

Installiere pyhpke, cryptography und rfc8785 in deiner Python-Umgebung. Übergib die folgenden Argumente an recover_record:

  • bundle_json: Das innere Datensatzpaket als Bytefolge mit UTF-8-kodiertem JSON.
  • capsule: Die Bytes, die dein Cloud-Schlüsselverwaltungsdienst zurückgibt.
  • original_key_id: Die ID der ursprünglichen Schlüsselregistrierung aus Schritt 2.
  • original_public_key_pem: Der öffentliche RSA-Schlüssel dieser Cloud-Schlüsselversion im PEM-Format als Bytefolge.

Die Funktion gibt den entschlüsselten Inhalt als UTF-8-Zeichenkette zurück. Schlägt eine Prüfung fehl, bricht die Funktion die Wiederherstellung ab.

Einen PSP-Datensatz entschlüsseln
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)

Wiederhergestellte Inhalte

Wenn das wiederhergestellte JSON eines Anfragedatensatzes format: "psp_request_v1" enthält, findest du in request_text den gespeicherten Anfragetext. Die weiteren Felder sind reasoning_summaries (Array von Zeichenketten), request_text_truncated (boolescher Wert) und reasoning_summary_parts_omitted (nicht negative Ganzzahl). Prüfe bei der Auswertung des Ergebnisses die Felder, die Kürzungen anzeigen. Andere geschützte Inhaltstypen können andere Klartextformate verwenden.

Du kannst Inhalte auch nach Ablauf des OpenAI-Laufzeitschlüssels wiederherstellen, sofern dein ursprünglicher Wiederherstellungsschlüssel und dein Snapshot weiterhin verfügbar sind. Lass den authentifizierten Wert von expires_at unverändert. Die separat verschlüsselten encrypted_cot-Blobs lassen sich mit deinem Wiederherstellungsschlüssel weiterhin nicht entschlüsseln.