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

Asymmetrische Schlüssel einrichten

Einen in der Cloud verwalteten öffentlichen Schlüssel bei OpenAI registrieren

Registriere ein asymmetrisches RSA-3072-Schlüsselpaar deines Cloud-Anbieters für die Verwendung mit OpenAI.

Dein privater Schlüssel bleibt in AWS KMS, Azure Key Vault, Google Cloud KMS oder Oracle Cloud Infrastructure (OCI) Vault. Bei der Registrierung speichert OpenAI eine Kopie des zugehörigen öffentlichen Schlüssels.

Mit der Registrierung eines Schlüssels konfigurierst du weder Produktfunktionen noch Speicher. In dieser Anleitung geht es um Schlüssel für die PSP-Entschlüsselung.

Voraussetzungen

  • Halte deine Organisations-ID bereit. Verwende dieselbe Organisation für die Vertrauensbeziehung mit deinem Cloud-Anbieter, die Registrierung und den API-Zugriff.
  • Erstelle einen Admin-API-Schlüssel für deine Organisation mit Lese- und Schreibzugriff auf externe Schlüssel. Lade ihn sicher in die Umgebungsvariable OPENAI_ADMIN_KEY. Projektschlüssel für die Inferenz funktionieren hierfür nicht.
  • Du brauchst die Berechtigung, einen aktivierten RSA-3072-Schlüssel zu erstellen und OpenAI den in dieser Anleitung beschriebenen Lesezugriff auf den öffentlichen Schlüssel zu gewähren.
  • Beschränke die Nutzung privater Schlüssel auf autorisierte Personen. Bewahre alte Schlüsselversionen auf, solange Datensätze von ihnen abhängen.

Cloud-Schlüssel einrichten

Führe vor der Registrierung die Schritte für deinen Cloud-Anbieter aus. Bei allen Anbietern verwendest du RSA-3072 und gewährst OpenAI ausschließlich Lesezugriff auf den öffentlichen Schlüssel und seine Metadaten.

Schlüssel registrieren

Die Beispiele verwenden curl und eine Bash-kompatible Shell. Lade OPENAI_ADMIN_KEY sicher und lege dann deine Organisations-ID fest:

API_BASE="https://api.openai.com/v1"
ORG_ID="<OPENAI_ORG_ID>"

: "${OPENAI_ADMIN_KEY:?Load your organization admin key securely}"

KEYS_URL="$API_BASE/organization/external_keys"

Registrierungsanfrage vorbereiten

Für purpose sind die Werte ekm (Standard) und psp_decryption zulässig. Verwende psp_decryption für die asymmetrischen Schlüssel in dieser Anleitung. Der Wert ekm ist für Enterprise Key Management (EKM) vorgesehen.

Speichere die Anfrage für deinen Anbieter als registration.json. Ersetze die Beispielwerte, da JSON keine Shellvariablen auflöst.

Anfrage für AWS KMS

{
  "type": "aws",
  "purpose": "psp_decryption",
  "name": "asymmetric-key-aws",
  "role_arn": "<CUSTOMER_ROLE_ARN>",
  "external_id": "<OPENAI_ORG_ID>",
  "kms_arn": "<CUSTOMER_KMS_KEY_ARN>"
}

Anfrage für Azure Key Vault

{
  "type": "azure",
  "purpose": "psp_decryption",
  "name": "asymmetric-key-azure",
  "tenant_id": "<CUSTOMER_TENANT_ID>",
  "vault_uri": "https://<CUSTOMER_VAULT_NAME>.vault.azure.net",
  "key_name": "<OPENAI_ORG_ID>--asymmetric-key",
  "key_version": "<CUSTOMER_KEY_VERSION>"
}

Anfrage für Google Cloud KMS

{
  "type": "gcp",
  "purpose": "psp_decryption",
  "name": "asymmetric-key-gcp",
  "workload_identity_project_number": "<CUSTOMER_GCP_PROJECT_NUMBER>",
  "workload_identity_pool_id": "openai-keys",
  "workload_identity_provider_id": "openai-google",
  "audience": "<OPENAI_ORG_ID>",
  "kms_project_id": "<CUSTOMER_KMS_PROJECT_ID>",
  "kms_key_ring_name": "asymmetric-keys",
  "kms_key_name": "asymmetric-key",
  "kms_key_location": "us-central1",
  "kms_key_version": "1"
}

Anfrage für OCI Vault

{
  "type": "oci",
  "purpose": "psp_decryption",
  "name": "asymmetric-key-oci",
  "region": "us-ashburn-1",
  "vault_ocid": "<CUSTOMER_VAULT_OCID>",
  "key_ocid": "<CUSTOMER_KEY_OCID>",
  "key_version_ocid": "<CUSTOMER_KEY_VERSION_OCID>"
}

1. Schlüssel registrieren und validieren

curl --fail-with-body -sS "$KEYS_URL" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID" \
  -H "Content-Type: application/json" \
  --data @registration.json

Bei der Registrierung prüft die API den Schlüssel, bevor sie ihn speichert. Bei Erfolg erhältst du HTTP 200 mit einer extkey-ID und deiner Anbieterkonfiguration. Die Antwort enthält beispielsweise folgende Felder:

{
  "id": "extkey_11111111111111111111111111111111",
  "object": "organization.external_key",
  "name": "asymmetric-key-gcp",
  "type": "gcp",
  "purpose": "psp_decryption",
  "api_project_ids": []
}

Speichere die zurückgegebene Registrierungs-ID:

KEY_ID="<EXTERNAL_KEY_ID>"

2. Schlüssel erneut validieren (optional)

GET gibt die gespeicherten Angaben zurück. POST /validate prüft erneut, ob der Zugriff weiterhin möglich ist und ob der aktuelle Schlüssel gültig ist und mit dem gespeicherten öffentlichen Schlüssel übereinstimmt. Dabei entschlüsselt die API keine Datensätze und aktualisiert auch nicht die gespeicherte Momentaufnahme.

curl --fail-with-body -sS "$KEYS_URL/$KEY_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID"
curl --fail-with-body -sS -X POST "$KEYS_URL/$KEY_ID/validate" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID"

Erwartete Antwort (HTTP 200):

{ "status": "success" }

Validiere den Schlüssel nach Änderungen am Schlüssel, an den Berechtigungen oder am Netzwerk erneut. Warte nach IAM-Änderungen, bis sie wirksam sind, bevor du es erneut versuchst.

Um deinen registrierten Schlüssel für die PSP-Entschlüsselung zu verwenden, wähle ihn für ein Projekt aus.

Schlüssel auflisten

Verwende purpose=psp_decryption, um die Registrierungen dieser asymmetrischen Schlüssel aufzulisten. Ohne Filter erhältst du Registrierungen für alle Verwendungszwecke. Mit purpose=ekm erhältst du nur EKM-Registrierungen.

curl --fail-with-body -sS --get "$KEYS_URL" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID" \
  --data-urlencode "purpose=psp_decryption" \
  --data-urlencode "order=asc" \
  --data-urlencode "limit=20"

Solange has_more den Wert true hat, ruf die nächste Seite ab, indem du after auf den Wert von last_id setzt. Lass purpose, order und limit unverändert.

Schlüssel ersetzen

  1. Erstelle in AWS einen Ersatzschlüssel oder in Azure, Google Cloud oder OCI eine neue Schlüsselversion und gewähre Lesezugriff darauf.
  2. Registriere den Ersatzschlüssel bzw. die neue Version.
  3. Wähle im Projekt die neue extkey-ID aus und überprüfe die Auswahl.

Jede Registrierung hält den Stand zum Zeitpunkt der Registrierung fest. Eine Schlüsselrotation in der Cloud aktualisiert die Registrierung nicht. Bewahre alte private Schlüssel auf, solange Datensätze von ihnen abhängen. Wenn du die Schlüsselauswahl änderst, werden bestehende Datensätze nicht migriert.

Schlüssel löschen

Hebe die Schlüsselauswahl auf oder wähle einen anderen Schlüssel aus. Führe diesen Schritt für jedes aktive Projekt aus, bevor du die Registrierung mit dem folgenden Befehl löschst:

curl --fail-with-body -sS -X DELETE "$KEYS_URL/$KEY_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID"

Nach dem Löschen der Registrierung erhältst du HTTP 200 mit object: "organization.external_key.deleted". Dein Schlüssel in der Cloud bleibt erhalten.

Fehlerbehebung

Fehler Was du prüfen solltest
401 oder 403 Verwende einen Admin-API-Schlüssel deiner Organisation und prüfe, ob er zur Registrierung externer Schlüssel berechtigt.
400 external_key_provider_error Prüfe die Vertrauensbeziehung mit deinem Cloud-Anbieter, die Leseberechtigungen und den Netzwerkzugriff. Prüfe außerdem, ob der Schlüssel aktiviert ist und den richtigen Algorithmus verwendet.
400 bei der Validierung der Anfrage Prüfe den Verwendungszweck und je nach Anbieter den ARN des konkreten AWS-Schlüssels oder die genaue Schlüsselversion in Azure, Google Cloud oder OCI.
Validierung des OCI-Schlüssels schlägt fehl Prüfe das Tag openai_organization_id am Schlüssel. Stelle sicher, dass der RSA-Schlüssel 3072 Bit lang und aktiviert ist, zum registrierten Vault gehört und OpenAI die auf diesen Vault und diesen Schlüssel beschränkten Leseberechtigungen hat.
404 Prüfe die Registrierungs-ID und die Organisation. Gelöschte Registrierungen und Registrierungen einer anderen Organisation kannst du nicht verwenden.
external_key_used_by_active_projects Hebe die Schlüsselauswahl in allen aktiven Projekten auf oder wähle dort einen anderen Schlüssel aus.
Schlüssel stimmt nicht mehr überein Registriere den Ersatzschlüssel und wähle seine neue ID aus.

Wenn du dich an den Support wendest, gib die Fehlermeldung und die x-request-id an. Gib niemals Zugangsdaten weiter.

Weiterführende Anleitungen