Questa pagina descrive come eseguire attività relative alle chiavi di crittografia gestite dal cliente (CMEK) per Firestore in modalità Datastore. Per ulteriori informazioni su CMEK in generale, inclusi quando e perché abilitarla, consulta la documentazione di Cloud KMS.
Prepara le chiavi CMEK
Prima di poter creare un database in modalità Datastore protetto da CMEK, devi completare i seguenti passaggi:
- Crea (o recupera) un agente di servizio in modalità Datastore.
- Crea una chiave CMEK.
- Configura le impostazioni IAM per la chiave.
Completa questi passaggi per ogni progetto che conterrà database Firestore protetti da CMEK. Se in seguito crei una nuova chiave CMEK, devi configurare le impostazioni IAM per quella chiave.
Crea un agente di servizio in modalità Datastore
Prima di creare una chiave CMEK, devi avere un agente di servizio in modalità Datastore, ovvero un tipo di account di servizio gestito da Google che viene utilizzato dalla modalità Datastore per accedere alla chiave.
Esegui il comando services Identity create per creare l'agente di servizio utilizzato dalla modalità Datastore per accedere alla chiave CMEK per tuo conto. Questo comando crea l'account di servizio, se non esiste già, lo visualizza.
gcloud beta services identity create \
--service=firestore.googleapis.com \
--project FIRESTORE_PROJECT
Sostituisci FIRESTORE_PROJECT con il progetto che prevedi di utilizzare per i database in modalità Datastore.
Il comando mostra l'ID agente di servizio, che ha il formato di un indirizzo email. Registra la stringa dell'email di output, perché la userai in un passaggio successivo.
Service identity created: service-xxx@gcp-sa-firestore.iam.gserviceaccount.com
Crea una chiave
Puoi utilizzare una chiave creata direttamente in Cloud KMS o una chiave gestita esternamente che rendi disponibile con Cloud External Key Manager.
La posizione della chiave di Cloud KMS deve essere la stessa del database in modalità Datastore con cui verrà utilizzato.
Per le località dei database a livello di regione, utilizza lo stesso nome di località per keyring, chiave e database, poiché i nomi delle località hanno una mappatura one-to-one.
Ad esempio, se vuoi creare un database protetto da CMEK in
us-west1, crea un keyring e una chiave inus-west1.Per le località dei database con più regioni, utilizza il nome della località località con più regioni KMS:
- Utilizza la località a più regioni
usdi Cloud KMS per la località a più regioni in modalità Datastorenam5. - Utilizza la località a più regioni
europedi Cloud KMS per la località a più regioni in modalità Datastoreeur3.
- Utilizza la località a più regioni
Nel progetto Google Cloud in cui vuoi gestire le chiavi, completa quanto segue:
Crea un keyring e una chiave utilizzando una delle seguenti opzioni:
- Crea il keyring e la chiave direttamente in Cloud KMS.
- Utilizza una chiave gestita esternamente. Crea la chiave esterna, quindi crea una chiave Cloud EKM per renderla disponibile tramite Cloud KMS.
Configura le impostazioni IAM per la chiave
Console
Per concedere un ruolo Cloud KMS all'agente di servizio: Puoi anche concedere l'autorizzazione a livello di chiave o keyring se vuoi una granularità inferiore.
Nella console Google Cloud, vai alla pagina IAM.
Fai clic su Aggiungi.
Inserisci l'ID in formato email per l'agente di servizio in modalità Datastore.
Seleziona il ruolo Autore crittografia/decriptazione CryptoKey Cloud KMS.
Fai clic su Salva.
gcloud
Concedi il ruolo
cloudkms.cryptoKeyEncrypterDecrypterall'agente di servizio: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_PROJECTFornisci quanto segue:
KMS_KEY: il nome assegnato alla chiaveKMS_KEYRING: il keyring KMS contenente la chiaveKMS_LOCATION: la regione che contiene il keyringSERVICE_AGENT_EMAIL: l'identificatore in formato email dell'agente di servizio a cui stai concedendo l'accessoKMS_PROJECT: il progetto che contiene la chiave
Il terminale dovrebbe visualizzare una risposta simile alla seguente:
Updated IAM policy for key KMS_KEY. bindings: - members: - serviceAccount: service-{project-number}@gcp-sa-firestore.iam.gserviceaccount.com role: roles/cloudkms.cryptoKeyEncrypterDecrypter
Crea un database abilitato per CMEK
Dopo aver creato e configurato le chiavi CMEK, puoi creare un database protetto da CMEK. I database esistenti in modalità Datastore protetti dalla crittografia predefinita di Google non possono essere convertiti in modo da utilizzare CMEK; puoi scegliere solo un tipo di crittografia e una chiave al momento della creazione.
gcloud
gcloud alpha firestore databases create --location=FIRESTORE_DATABASE_LOCATION \
--database=DATABASE_ID \
--kms-key-name=KMS_KEY_NAME \
--project=FIRESTORE_PROJECT
Fornisci quanto segue:
FIRESTORE_DATABASE_LOCATION: la località in modalità Datastore per il databaseDATABASE_ID: un ID per il databaseKMS_KEY_NAME: il nome assegnato alla chiave. Utilizza il nome completo della risorsa per la chiave nel seguente formato:projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING_ID/cryptoKeys/KMS_KEY_IDFIRESTORE_PROJECT: il progetto da utilizzare per il database in modalità Datastore
API REST
Richiesta HTTP:
POST https://firestore.googleapis.com/v1/projects/{FIRESOTRE_PROJECT}/databases
Nel corpo della richiesta, configura CMEK nel campo cmek_config.kms_key_name.
Imposta l'ID risorsa completo di una chiave Cloud KMS. È consentita solo una chiave nella stessa posizione del database.
Questo valore deve essere l'ID risorsa della chiave Cloud KMS nel formato projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}
Per maggiori dettagli sugli altri campi, vedi la pagina database create.
Esempio di richiesta:
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
Per creare un database abilitato per CMEK, utilizza la risorsa google_firestore_database. Per ulteriori informazioni ed esempi, consulta
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"
}
}
Fornisci quanto segue:
FIRESTORE_PROJECT: il progetto da utilizzare per il database in modalità DatastoreDATABASE_ID: un ID per il databaseFIRESTORE_DATABASE_LOCATION: la località in modalità Datastore per il databaseDATABASE_TYPE: FIRESTORE_NATIVE per la modalità Native o DATASTORE_MODE per la modalità Datastore.KMS_KEY_NAME: il nome assegnato alla chiave. Utilizza il nome completo della risorsa per la chiave nel seguente formato:projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING_ID/cryptoKeys/KMS_KEY_ID
Accedi a un database protetto da CMEK
Tutte le operazioni di lettura, scrittura e query inviate a un database protetto da CMEK dovrebbero funzionare come con un database criptato predefinito di Google. Ad esempio, non è necessario fornire una chiave per ogni richiesta.
Visualizza la chiave in uso
gcloud
Puoi utilizzare il comando gcloud CLI databases describe per confermare la configurazione CMEK del database:
gcloud firestore databases describe --database=DATABASE_ID --project=FIRESTORE_PROJECT
Dovresti vedere informazioni CMEK nel campo cmekConfig nella risposta simili a queste:
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
La risposta include le seguenti informazioni:
kmsKeyName: il nome completo della risorsa della chiave utilizzata per criptare il database protetto da CMEK.activeKeyVersion: un elenco di tutte le versioni della chiave attualmente in uso dal database protetto da CMEK. Durante la rotazione della chiave, possono esserci più versioni attive della chiave.
API REST
Richiesta HTTP:
GET https://firestore.googleapis.com/v1/{name=projects/FIRESTORE_PROJECT/databases/DATABASE_ID}
Nel corpo della richiesta, configura CMEK nel campo cmek_config.kms_key_name.
Imposta l'ID risorsa completo di una chiave Cloud KMS. È consentita solo una chiave nella stessa posizione del database.
Questo valore deve essere l'ID risorsa della chiave Cloud KMS nel formato projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}
Per maggiori dettagli sugli altri campi, vedi la pagina database create.
Esempio di richiesta e risposta:
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"
]
},
……
}
Disattivare una chiave
Per disabilitare una chiave associata a un database, completa quanto segue:
- Visualizza le versioni della chiave in uso per un database
- Disabilita queste versioni della chiave
- Attendi l'applicazione della modifica e verifica se i dati non sono più accessibili. In genere l'applicazione delle modifiche richiede pochi minuti, ma in alcuni casi può essere necessario attendere fino a tre ore.
Quando una chiave utilizzata da un database viene disabilitata, dovresti ricevere un'eccezione FAILED_PRECONDITION con ulteriori dettagli nel messaggio di errore, ad esempio:
{
"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)"
}
]
}
}
Attiva una chiave
Per riabilitare una chiave associata a un database, completa quanto segue:
- Visualizza le versioni della chiave in uso per un database
- Abilita le versioni della chiave
- Attendi l'applicazione della modifica e verifica se i dati non sono più accessibili. In genere l'applicazione delle modifiche richiede pochi minuti, ma in alcuni casi può essere necessario attendere fino a tre ore.
Visualizza audit log per una chiave Cloud KMS
Prima di abilitare gli audit log di accesso ai dati di Cloud KMS, devi acquisire familiarità con Cloud Audit Logs.
Gli audit log di accesso ai dati di Cloud KMS mostrano quando la modalità Datastore o qualsiasi altro prodotto configurato per utilizzare la tua chiave CMEK effettua chiamate di crittografia/decriptazione a Cloud KMS. La modalità Datastore non esegue una chiamata di crittografia/decrittografia su ogni richiesta di dati, ma mantiene un poller che controlla periodicamente la chiave. I risultati del sondaggio vengono visualizzati negli audit log.
Puoi configurare e interagire con gli audit log nella console Google Cloud:
Assicurati che il logging sia abilitato per l'API Cloud KMS nel tuo progetto.
Vai a Cloud Logging nella console Google Cloud.
Limita le voci di log alla chiave Cloud KMS aggiungendo le seguenti righe a Query Builder:
resource.type="cloudkms_cryptokey" resource.labels.key_ring_id = KMS_KEYRING resource.labels.crypto_key_id = KMS_KEY resource.labels.location=KMS_LOCATIONFornisci quanto segue:
KMS_KEY: il nome della chiave CMEKKMS_KEYRING: il keyring KMS contenente la chiaveKMS_LOCATION: la posizione della chiave e del keyring
Il log mostra un paio di voci di log circa ogni cinque minuti per database. Le voci di log sono simili ai seguenti esempi:
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"
Per maggiori dettagli sull'interpretazione degli audit log, consulta Informazioni sugli audit log.
Configura un criterio dell'organizzazione CMEK
Per specificare i requisiti di conformità della crittografia per i database in modalità Datastore nella tua organizzazione, utilizza un vincolo del criterio dell'organizzazione CMEK.
Richiedi la protezione CMEK
Configura constraints/gcp.restrictNonCmekServices per richiedere una CMEK per la creazione del database in modalità Datastore. Imposta il vincolo su deny e aggiungi firestore.googleapis.com all'elenco di tipi non consentiti, ad esempio:
gcloud resource-manager org-policies deny gcp.restrictNonCmekServices is:firestore.googleapis.com --project=FIRESTORE_PROJECT
Sostituisci FIRESTORE_PROJECT con il progetto da limitare.
Per saperne di più sulla configurazione dei criteri dell'organizzazione, vedi Creazione e modifica dei criteri.
Una volta applicato il criterio, riceverai un'eccezione FAILED_PRECONDITION e un messaggio di errore se tenti di creare un database non CMEK nel progetto interessato. Ad esempio, un'eccezione ha il seguente aspetto:
{
"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."
}
]
Limita l'utilizzo delle chiavi per CMEK
Per limitare le chiavi Cloud KMS utilizzate per la protezione CMEK, configura il vincolo constraints/gcp.restrictCmekCryptoKeyProjects.
Come vincolo dell'elenco, i valori accettati sono indicatori della gerarchia delle risorse (ad esempio, projects/PROJECT_ID, under:folders/FOLDER_ID e under:organizations/ORGANIZATION_ID). Utilizza questo vincolo configurando un elenco di indicatori di gerarchia delle risorse e impostando il vincolo su Allow.
Questa configurazione limita i servizi supportati in modo che le chiavi CMEK possano essere scelte solo dai progetti, dalle cartelle e dalle organizzazioni elencati. Le richieste per creare risorse protette da CMEK nei servizi configurati non hanno esito positivo senza una chiave in modalità Datastore da una delle risorse consentite.
L'esempio seguente consente solo le chiavi da ALLOWED_KEY_PROJECT_ID per i database protetti da CMEK nel progetto specificato:
gcloud resource-manager org-policies allow gcp.restrictCmekCryptoKeyProjects \ under:projects/ALLOWED_KEY_PROJECT_ID \ --project=FIRESTORE_PROJECT
Una volta applicato il criterio, riceverai un'eccezione FAILED_PRECONDITION e un messaggio di errore se violi il vincolo. Un'eccezione è simile alla seguente:
{
"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."
}
]
}
]
}
}