Auf dieser Seite wird beschrieben, wie Sie Aufgaben im Zusammenhang mit vom Kunden verwalteten Verschlüsselungsschlüsseln (CMEK) für Firestore im Datastore-Modus ausführen. Weitere Informationen zu CMEK und deren Aktivierung finden Sie in der Cloud KMS-Dokumentation.
CMEK-Schlüssel vorbereiten
Bevor Sie eine CMEK-geschützte Datenbank im Datastore-Modus erstellen können, müssen Sie die folgenden Schritte ausführen:
- Dienst-Agent im Datastore-Modus erstellen oder abrufen
- Erstellen Sie einen CMEK-Schlüssel.
- Konfigurieren Sie die IAM-Einstellungen für diesen Schlüssel.
Führen Sie diese Schritte für jedes Projekt aus, das CMEK-geschützte Firestore-Datenbanken enthalten soll. Wenn Sie später einen neuen CMEK-Schlüssel erstellen, müssen Sie die IAM-Einstellungen für diesen Schlüssel konfigurieren.
Dienst-Agent im Datastore-Modus erstellen
Bevor Sie einen CMEK-Schlüssel erstellen, benötigen Sie einen Dienst-Agent im Datastore-Modus. Das ist ein von Google verwaltetes Dienstkonto, mit dem der Datastore-Modus auf den Schlüssel zugreift.
Führen Sie den Befehl services Identity create aus, um den Dienst-Agent zu erstellen, den der Datastore-Modus verwendet, um in Ihrem Namen auf den CMEK-Schlüssel zuzugreifen. Mit diesem Befehl wird das Dienstkonto erstellt, falls es noch nicht vorhanden ist, und es wird angezeigt.
gcloud beta services identity create \
--service=firestore.googleapis.com \
--project FIRESTORE_PROJECT
Ersetzen Sie FIRESTORE_PROJECT durch das Projekt, das Sie für Ihre Datenbanken im Datastore-Modus verwenden möchten.
Der Befehl zeigt die Dienst-Agent-ID an, die wie eine E-Mail-Adresse formatiert ist. Zeichnen Sie den Ausgabe-E-Mail-String auf, da Sie ihn in einem späteren Schritt benötigen.
Service identity created: service-xxx@gcp-sa-firestore.iam.gserviceaccount.com
Schlüssel erstellen
Sie können einen Schlüssel verwenden, der direkt in Cloud KMS erstellt wurde, oder einen extern verwalteten Schlüssel, den Sie mit Cloud External Key Manager zur Verfügung stellen.
Der Speicherort des Cloud KMS-Schlüssels muss mit dem Standort der Datenbank im Datastore-Modus übereinstimmen, mit der er verwendet wird.
Verwenden Sie für regionale Datenbankstandorte denselben Standortnamen für Schlüsselbund, Schlüssel und Datenbank, da die Standortnamen eine 1:1-Zuordnung haben.
Wenn Sie beispielsweise eine CMEK-geschützte Datenbank in
us-west1erstellen möchten, erstellen Sie einen Schlüsselbund und einen Schlüssel inus-west1.Verwenden Sie für multiregionale Datenbankstandorte den Standortnamen des multiregionalen KMS-Standorts:
- Verwenden Sie den multiregionalen Standort
usvon Cloud KMS für den multiregionalen Standortnam5im Datastore-Modus. - Verwenden Sie den multiregionalen Standort
europevon Cloud KMS für den multiregionalen Standorteur3im Datastore-Modus.
- Verwenden Sie den multiregionalen Standort
Führen Sie in dem Google Cloud-Projekt, in dem Sie Ihre Schlüssel verwalten möchten, die folgenden Schritte aus:
Erstellen Sie einen Schlüsselbund und einen Schlüssel mit einer der folgenden Optionen:
- Erstellen Sie den Schlüsselbund und den Schlüssel direkt in Cloud KMS.
- Verwenden Sie einen extern verwalteten Schlüssel. Erstellen Sie den externen Schlüssel und erstellen Sie dann einen Cloud EKM-Schlüssel, um den Schlüssel über Cloud KMS verfügbar zu machen.
IAM-Einstellungen für den Schlüssel konfigurieren
Console
So weisen Sie Ihrem Dienst-Agent eine Cloud KMS-Rolle zu. Sie können auch eine Berechtigung auf Schlüssel- oder Schlüsselbundebene gewähren, wenn Sie einen niedrigeren Detaillierungsgrad benötigen.
Öffnen Sie in der Google Cloud Console die Seite IAM.
Klicken Sie auf Hinzufügen.
Geben Sie die ID im E-Mail-Format für den Dienst-Agent für den Datastore-Modus ein.
Wählen Sie die Rolle Cloud KMS CryptoKey-Verschlüsseler/Entschlüsseler aus.
Klicken Sie auf Speichern.
gcloud
Weisen Sie Ihrem Dienst-Agent die Rolle
cloudkms.cryptoKeyEncrypterDecrypterzu:gcloud kms keys add-iam-policy-binding KMS_KEY \ --keyring KMS_KEYRING\ --location KMS_LOCATION \ --member serviceAccount:SERVICE_AGENT_EMAIL \ --role roles/cloudkms.cryptoKeyEncrypterDecrypter \ --project KMS_PROJECTMachen Sie folgende Angaben:
KMS_KEY: Name, den Sie dem Schlüssel zugewiesen habenKMS_KEYRING: Der KMS-Schlüsselbund, der den Schlüssel enthältKMS_LOCATION: Region, die den Schlüsselbund enthältSERVICE_AGENT_EMAIL: die wie eine E-Mail-Adresse formatierte Kennzeichnung für den Dienst-Agent, dem Sie Zugriff gewährenKMS_PROJECT: das Projekt, das den Schlüssel enthält
Das Terminal sollte in etwa folgende Antwort anzeigen:
Updated IAM policy for key KMS_KEY. bindings: - members: - serviceAccount: service-{project-number}@gcp-sa-firestore.iam.gserviceaccount.com role: roles/cloudkms.cryptoKeyEncrypterDecrypter
CMEK-fähige Datenbank erstellen
Nachdem Ihre CMEK-Schlüssel erstellt und konfiguriert wurden, können Sie eine CMEK-geschützte Datenbank erstellen. Vorhandene Datenbanken im Datastore-Modus, die durch die Google-Standardverschlüsselung geschützt sind, können nicht in die Verwendung von CMEK konvertiert werden. Sie können nur bei der Erstellung einen Verschlüsselungstyp und Schlüssel auswählen.
gcloud
gcloud alpha firestore databases create --location=FIRESTORE_DATABASE_LOCATION \
--database=DATABASE_ID \
--kms-key-name=KMS_KEY_NAME \
--project=FIRESTORE_PROJECT
Machen Sie folgende Angaben:
FIRESTORE_DATABASE_LOCATION: Standort der Datenbank im Datastore-ModusDATABASE_ID: eine ID für die DatenbankKMS_KEY_NAME: der Name, den Sie dem Schlüssel zugewiesen haben. Verwenden Sie den vollständigen Ressourcennamen für den Schlüssel im folgenden Format:projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING_ID/cryptoKeys/KMS_KEY_IDFIRESTORE_PROJECT: das für die Datenbank im Datastore-Modus zu verwendende Projekt
REST API
HTTP-Anfrage:
POST https://firestore.googleapis.com/v1/projects/{FIRESOTRE_PROJECT}/databases
Konfigurieren Sie im Anfragetext den CMEK im Feld cmek_config.kms_key_name.
Legen Sie dafür die vollständige Ressourcen-ID eines Cloud KMS-Schlüssels fest. Es ist nur ein Schlüssel zulässig, der sich am selben Speicherort wie diese Datenbank befindet.
Dieser Wert sollte die Ressourcen-ID des Cloud KMS-Schlüssels im Format projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID} sein.
Weitere Informationen zu anderen Feldern finden Sie auf der Seite database create.
Beispielanfrage:
curl -X POST 'https://firestore.googleapis.com/v1/projects/FIRESTORE_PROJECT/databases?databaseId={DATABASE_ID}' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-type: application/json" \
-d '{
"type":"FIRESTORE_NATIVE",
"locationId":"{FIRESTORE_DATABASE_LOCATION}",
"cmekConfig": {
"kmsKeyName":"projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING_ID/cryptoKeys/KMS_KEY_ID"
}
}'
Terraform
Verwenden Sie die Ressource google_firestore_database, um eine CMEK-fähige Datenbank zu erstellen. Weitere Informationen und Beispiele finden Sie unter google_firestore_database.
resource "google_firestore_database" "database" {
project = "FIRESTORE_PROJECT"
name = "DATABASE_ID"
location_id = "FIRESTORE_DATABASE_LOCATION"
type = "DATABASE_TYPE"
cmek_config {
kms_key_name = "KMS_KEY_NAME"
}
}
Machen Sie folgende Angaben:
FIRESTORE_PROJECT: das für die Datenbank im Datastore-Modus zu verwendende ProjektDATABASE_ID: eine ID für die DatenbankFIRESTORE_DATABASE_LOCATION: Standort der Datenbank im Datastore-ModusDATABASE_TYPE: entweder FIRESTORE_NATIVE für den nativen Modus oder DATASTORE_MODE für den Datastore-Modus.KMS_KEY_NAME: der Name, den Sie dem Schlüssel zugewiesen haben. Verwenden Sie den vollständigen Ressourcennamen für den Schlüssel im folgenden Format:projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING_ID/cryptoKeys/KMS_KEY_ID
Auf eine CMEK-geschützte Datenbank zugreifen
Alle Lese-, Schreib- und Abfragevorgänge, die an eine CMEK-geschützte Datenbank gesendet werden, sollten genauso funktionieren wie mit einer standardmäßig verschlüsselten Google-Datenbank. Sie müssen beispielsweise nicht für jede Anfrage einen Schlüssel angeben.
Verwendeten Schlüssel anzeigen
gcloud
Mit dem gcloud CLI-Befehl databases describe können Sie die CMEK-Konfiguration der Datenbank prüfen:
gcloud firestore databases describe --database=DATABASE_ID --project=FIRESTORE_PROJECT
Im Feld cmekConfig der Antwort sollten CMEK-Informationen in etwa so angezeigt werden:
cmekConfig:
activeKeyVersion:
- projects/PROJECT_ID/locations/us/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME/cryptoKeyVersions/1
kmsKeyName: projects/PROJECT_ID/locations/us/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME
locationId: nam5
name: projects/PROJECT_ID/databases/DATABASE_ID
Die Antwort enthält die folgenden Informationen:
kmsKeyName: der vollständige Name der Schlüsselressource des Schlüssels, der zum Verschlüsseln Ihrer CMEK-geschützten Datenbank verwendet wird.activeKeyVersion: Eine Liste aller Schlüsselversionen, die derzeit von der CMEK-geschützten Datenbank verwendet werden. Während der Schlüsselrotation können mehrere aktive Schlüsselversionen vorhanden sein.
REST API
HTTP-Anfrage:
GET https://firestore.googleapis.com/v1/{name=projects/FIRESTORE_PROJECT/databases/DATABASE_ID}
Konfigurieren Sie im Anfragetext den CMEK im Feld cmek_config.kms_key_name.
Legen Sie dafür die vollständige Ressourcen-ID eines Cloud KMS-Schlüssels fest. Es ist nur ein Schlüssel zulässig, der sich am selben Speicherort wie diese Datenbank befindet.
Dieser Wert sollte die Ressourcen-ID des Cloud KMS-Schlüssels im Format projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID} sein.
Weitere Informationen zu anderen Feldern finden Sie auf der Seite database create.
Beispiel für eine Anfrage und Antwort:
curl 'https://firestore.googleapis.com/v1/projects/FIRESTORE_PROJECT/databases/{DATABASE_ID}' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-type: application/json"
—----------------------------------------- Response —--------------------------------------------
{
"name": "projects/FIRESTORE_PROJECT/databases/{DATABASE_ID}",
"locationId": "{FIRESTORE_DATABASE_LOCATION}",
"type": "FIRESTORE_NATIVE",
"cmekConfig": {
"kmsKeyName": "projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}",
"activeKeyVersion": [
"projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}/cryptoKeyVersions/1"
]
},
……
}
Schlüssel deaktivieren
So deaktivieren Sie einen mit einer Datenbank verknüpften Schlüssel:
- Für eine Datenbank verwendete Schlüsselversionen ansehen
- Diese Schlüsselversionen deaktivieren
- Warten Sie, bis die Änderung wirksam wird, und prüfen Sie, ob die Daten nicht mehr zugänglich sind. Änderungen werden normalerweise innerhalb weniger Minuten wirksam, es kann jedoch auch bis zu 3 Stunden dauern.
Wenn ein von einer Datenbank verwendeter Schlüssel deaktiviert ist, wird die Ausnahme FAILED_PRECONDITION mit zusätzlichen Details in der Fehlermeldung zurückgegeben, z. B.:
{
"error": {
"code": 400,
"message": "The customer-managed encryption key required by the requested resource is not accessible. Error reason: generic::permission_denied: Permission 'cloudkms.cryptoKeyVersions.useToEncrypt' denied on resource 'projects/FIRESTORE_PROJECT/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}' (or it may not exist).",
"status": "FAILED_PRECONDITION",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "The customer-managed encryption key required by the requested resource is not accessible. Error reason: generic::permission_denied: Permission 'cloudkms.cryptoKeyVersions.useToEncrypt' denied on resource 'projects/FIRESTORE_PROJECT/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}' (or it may not exist)"
}
]
}
}
Schlüssel aktivieren
So aktivieren Sie einen mit einer Datenbank verknüpften Schlüssel wieder:
- Für eine Datenbank verwendete Schlüsselversionen ansehen
- Schlüsselversionen aktivieren
- Warten Sie, bis die Änderung wirksam wird, und prüfen Sie, ob die Daten nicht mehr zugänglich sind. Änderungen werden normalerweise innerhalb weniger Minuten wirksam, es kann jedoch auch bis zu 3 Stunden dauern.
Audit-Logs für einen Cloud KMS-Schlüssel aufrufen
Bevor Sie Audit-Logs für den Cloud KMS-Datenzugriff aktivieren, sollten Sie mit Cloud-Audit-Logs vertraut sein.
Audit-Logs zum Cloud KMS-Datenzugriff zeigen, wann der Datastore-Modus oder andere Produkte, die für die Verwendung Ihres CMEK-Schlüssels konfiguriert sind, Verschlüsselungs-/Entschlüsselungsversuche an Cloud KMS ausführen. Im Datastore-Modus wird nicht bei jeder Datenanfrage ein Verschlüsselungs-/Entschlüsselungsaufruf ausgeführt, sondern ein Abfragedienst verwendet, der den Schlüssel regelmäßig prüft. Die Abfrageergebnisse werden in den Audit-Logs angezeigt.
Sie können die Audit-Logs in der Google Cloud Console einrichten und mit ihnen interagieren:
Achten Sie darauf, dass für die Cloud KMS API in Ihrem Projekt Logging aktiviert ist.
Rufen Sie in der Google Cloud Console Cloud Logging auf.
Beschränken Sie die Logeinträge auf Ihren Cloud KMS-Schlüssel, indem Sie dem Query Builder die folgenden Zeilen hinzufügen:
resource.type="cloudkms_cryptokey" resource.labels.key_ring_id = KMS_KEYRING resource.labels.crypto_key_id = KMS_KEY resource.labels.location=KMS_LOCATIONMachen Sie folgende Angaben:
KMS_KEY: Name des CMEK-SchlüsselsKMS_KEYRING: Der KMS-Schlüsselbund, der den Schlüssel enthältKMS_LOCATION: der Speicherort von Schlüssel und Schlüsselbund
Das Protokoll enthält einige Logeinträge, die etwa alle fünf Minuten pro Datenbank stammen. Die Logeinträge sehen in etwa so aus:
Info 2021-03-20 08:02:24.869 EDT Cloudkms.googleapis.com Decrypt projects/cloud-kms-project/locations/us-central1/keyRings/firestore-keys/cryptoKeys/my-cmek-key service-123456789123@gcp-sa-firestore.iam.gserviceaccount.com audit_log, method: "Decrypt", principal_email: "service-1234567891011@gcp-sa-firestore.iam.gserviceaccount.com" Info 2021-03-20 08:02:24.913 EDT Cloudkms.googleapis.com Encrypt projects/cloud-kms-project/locations/us-central1/keyRings/firestore-keys/cryptoKeys/my-cmek-key service-123456789123@gcp-sa-firestore.iam.gserviceaccount.com audit_log, method: "Encrypt", principal_email: "service-123456789123@gcp-sa-firestore.iam.gserviceaccount.com"
Weitere Informationen zum Auswerten von Audit-Logs finden Sie unter Audit-Logs verstehen.
CMEK-Organisationsrichtlinie konfigurieren
Verwenden Sie eine Einschränkung für die CMEK-Organisationsrichtlinie, um die Anforderungen an die Verschlüsselungscompliance für Datenbanken im Datastore-Modus in Ihrer Organisation festzulegen.
CMEK-Schutz verlangen
Konfigurieren Sie constraints/gcp.restrictNonCmekServices so, dass ein CMEK zum Erstellen von Datenbanken im Datastore-Modus erforderlich ist. Legen Sie die Einschränkung auf deny fest und fügen Sie firestore.googleapis.com der Sperrliste hinzu. Beispiel:
gcloud resource-manager org-policies deny gcp.restrictNonCmekServices is:firestore.googleapis.com --project=FIRESTORE_PROJECT
Ersetzen Sie FIRESTORE_PROJECT durch das Projekt, das eingeschränkt werden soll.
Weitere Informationen zum Konfigurieren von Organisationsrichtlinien finden Sie unter Richtlinien erstellen und bearbeiten.
Nachdem die Richtlinie in Kraft getreten ist, erhalten Sie eine FAILED_PRECONDITION-Ausnahme und eine Fehlermeldung, wenn Sie versuchen, im betroffenen Projekt eine nicht CMEK-geschützte Datenbank zu erstellen. Eine Ausnahme sieht beispielsweise so aus:
{
"error": {
"code": 400,
"message": "Constraint 'constraints/gcp.restrictNonCmekServices' violated for 'projects/FIRESTORE_PROJECT' attempting to perform the operation 'google.firestore.admin.v1.FirestoreAdmin.CreateDatabase' with violated value 'firestore.googleapis.com'. See https://cloud.google.com/resource-manager/docs/organization-policy/org-policy-constraints for more information.",
"status": "FAILED_PRECONDITION",
"details": [
{
"@type": "type.googleapis.com/google.rpc.PreconditionFailure",
"violations": [
{
"type": "constraints/gcp.restrictNonCmekServices",
"subject": "orgpolicy:projects/FIRESTORE_PROJECT",
"description": "Constraint 'constraints/gcp.restrictNonCmekServices' violated for 'projects/FIRESTORE_PROJECT' attempting to perform the operation 'google.firestore.admin.v1.FirestoreAdmin.CreateDatabase' with violated value 'firestore.googleapis.com'. See https://cloud.google.com/resource-manager/docs/organization-policy/org-policy-constraints for more information."
}
]
Verwendung von Schlüsseln für CMEK beschränken
Konfigurieren Sie die Einschränkung constraints/gcp.restrictCmekCryptoKeyProjects, um einzuschränken, welche Cloud KMS-Schlüssel für den CMEK-Schutz verwendet werden.
Als Listeneinschränkung sind die zulässigen Werte Indikatoren für die Ressourcenhierarchie (z. B. projects/PROJECT_ID, under:folders/FOLDER_ID und under:organizations/ORGANIZATION_ID). Konfigurieren Sie für diese Einschränkung eine Liste mit Indikatoren für die Ressourcenhierarchie und legen Sie für die Einschränkung Zulassen fest.
Diese Konfiguration schränkt die unterstützten Dienste ein, sodass CMEK-Schlüssel nur aus den aufgeführten Projekten, Ordnern und Organisationen ausgewählt werden können. Anfragen zum Erstellen von CMEK-geschützten Ressourcen in konfigurierten Diensten sind ohne einen Schlüssel im Datastore-Modus aus einer der zulässigen Ressourcen nicht erfolgreich.
Im folgenden Beispiel sind nur Schlüssel aus dem ALLOWED_KEY_PROJECT_ID für CMEK-geschützte Datenbanken im angegebenen Projekt zulässig:
gcloud resource-manager org-policies allow gcp.restrictCmekCryptoKeyProjects \ under:projects/ALLOWED_KEY_PROJECT_ID \ --project=FIRESTORE_PROJECT
Nachdem die Richtlinie in Kraft getreten ist, erhalten Sie eine FAILED_PRECONDITION-Ausnahme und eine Fehlermeldung, wenn Sie gegen die Einschränkung verstoßen. Eine Ausnahme sieht so aus:
{
"error": {
"code": 400,
"message": "Constraint 'constraints/gcp.restrictCmekCryptoKeyProjects' violated for 'projects/FIRESTORE_PROJECT' attempting to perform the operation 'google.firestore.admin.v1.FirestoreAdmin.CreateDatabase' with violated value 'projects/{NOT_ALLOWED_KEY_PROJECT}'. See https://cloud.google.com/resource-manager/docs/organization-policy/org-policy-constraints for more information.",
"status": "FAILED_PRECONDITION",
"details": [
{
"@type": "type.googleapis.com/google.rpc.PreconditionFailure",
"violations": [
{
"type": "constraints/gcp.restrictCmekCryptoKeyProjects",
"subject": "orgpolicy:projects/FIRESTORE_PROJECT",
"description": "Constraint 'constraints/gcp.restrictCmekCryptoKeyProjects' violated for 'projects/FIRESTORE_PROJECT' attempting to perform the operation 'google.firestore.admin.v1.FirestoreAdmin.CreateDatabase' with violated value 'projects/{NOT_ALLOWED_KEY_PROJECT}'. See https://cloud.google.com/resource-manager/docs/organization-policy/org-policy-constraints for more information."
}
]
}
]
}
}