Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzo delle chiavi di crittografia gestite dal cliente (CMEK)

In questa pagina viene descritto come eseguire attività relative a: chiavi di crittografia gestite dal cliente (CMEK) per Firestore. Per ulteriori informazioni su CMEK in generale, inclusi quando e e scopri perché abilitarlo, consulta la documentazione di Cloud KMS.

Prepara le chiavi CMEK

Prima di poter creare un database Firestore protetto da CMEK, devi completare questi passaggi:

Richiedi l'accesso alla funzionalità CMEK Firestore.
Crea (o recupera) un agente di servizio Firestore.
Crea una chiave CMEK.
Configura le impostazioni IAM per quella chiave.

Completa questi passaggi per ogni progetto che conterrà la protezione CMEK e Firestore. Se in un secondo momento crei una nuova chiave CMEK, devi configurare le impostazioni IAM per quella chiave.

Richiedi l’accesso

Prima di creare un agente di servizio Firestore, richiedi l'accesso al funzionalità CMEK compilando questo modulo.

Crea un agente di servizio Firestore

Prima di creare una chiave CMEK, devi avere un Firestore agente di servizio, un tipo di account di servizio gestito da Google Firestore utilizza per accedere alla chiave.

Esegui il comando services Identity create per crea l'agente di servizio che Firestore utilizza per accedere alla CMEK per te. Questo comando crea l'account di servizio se non esiste già, la visualizza.

gcloud beta services identity create \
    --service=firestore.googleapis.com \
    --project FIRESTORE_PROJECT

Sostituisci FIRESTORE_PROJECT con il progetto che prevedi da utilizzare per i tuoi database Firestore.

Il comando visualizza l'ID agente di servizio, che formattato come un indirizzo email. Registra la stringa email di output, perché lo utilizzerai 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 esternamente chiave gestita che rendi disponibile con Cloud External Key Manager.

La posizione della chiave di Cloud KMS deve essere il corrisponde alla località del database Firestore che verrà utilizzata con.

Per le località di database regionali, utilizza lo stesso nome di località per keyring, chiave e database perché i nomi delle località una mappatura one-to-one.

Ad esempio, se vuoi creare un database protetto da CMEK in us-west1, crea un keyring e una chiave in us-west1.
Per le località di database con più regioni, utilizza il nome della località con più regioni KMS:
- Utilizza la località multiregionale di Cloud KMS us per la località a più regioni nam5 Firestore.
- Utilizza la località multiregionale di Cloud KMS europe per la località a più regioni eur3 Firestore.

Nel progetto Google Cloud in cui vuoi gestire le chiavi, completa quanto segue:

Abilita l'API Cloud KMS.
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 e poi crea una chiave Cloud EKM per renderla disponibili tramite Cloud KMS.

Configura le impostazioni IAM per la chiave

Console

Per concedere un ruolo Cloud KMS all'agente di servizio, esegui la seguire. Puoi anche concedere l'autorizzazione alla chiave o al keyring se vuoi una granularità inferiore.

Nella console Google Cloud, vai alla pagina IAM.

Vai alla pagina IAM
Fai clic su Aggiungi.
Inserisci l'ID con formato email per Firestore dell'agente di servizio di servizio di Google Cloud.
Seleziona il ruolo Autore crittografia/decrittografia CryptoKey Cloud KMS.
Fai clic su Salva.

gcloud

Concedi il ruolo cloudkms.cryptoKeyEncrypterDecrypter al tuo 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_PROJECT
```
Fornisci quanto segue:
- KMS_KEY: il nome che hai assegnato alla chiave
- KMS_KEYRING: il keyring KMS che contiene la chiave
- KMS_LOCATION : la regione che contiene il keyring
- SERVICE_AGENT_EMAIL: identificatore in formato email per l'agente di servizio a cui concedi l'accesso
- KMS_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 una protezione CMEK per configurare un database. Database Firestore esistenti protetti da Impossibile convertire la crittografia predefinita di Google per 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à di Firestore per il database
DATABASE_ID: un ID per il database
KMS_KEY_NAME: il nome assegnato alla chiave. Utilizza il nome completo della risorsa per la chiave nel formato:

projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING_ID/cryptoKeys/KMS_KEY_ID
FIRESTORE_PROJECT: il progetto da utilizzare per Database Firestore

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.

Da impostare sull'ID risorsa completo di una chiave Cloud KMS. Solo una chiave nello stesso posizione in cui questo database è consentito.

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, consulta 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 google_firestore_database risorsa. Per ulteriori informazioni ed esempi, vedi 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 Database Firestore
DATABASE_ID: un ID per il database
FIRESTORE_DATABASE_LOCATION: la località di Firestore per il database
DATABASE_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 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 dovrebbe funzionare come in un database criptato predefinito di Google. Ad esempio, non è necessario fornire una chiave per ogni richiesta.

Visualizza la chiave in uso

gcloud

Puoi utilizzare lo i database descrivono gcloud CLI per confermare la configurazione CMEK del database:

gcloud firestore databases describe --database=DATABASE_ID --project=FIRESTORE_PROJECT

Nella risposta dovresti vedere le informazioni relative a CMEK nel campo cmekConfig simile al seguente:

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 del tuo 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 avere più versioni di chiavi attive.

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. Da impostare sull'ID risorsa completo di una chiave Cloud KMS. Solo una chiave nello stesso posizione in cui questo database è consentito.

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, consulta 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 questi passaggi:

Visualizza le versioni della chiave in uso per un database
Disabilitare le versioni della chiave
Attendi che la modifica venga applicata e controlla se i dati non sono più accessibili. In genere le modifiche diventano effettive entro pochi minuti ma l'operazione può richiedere fino a tre ore.

Quando una chiave utilizzata da un database viene disabilitata, il risultato sarà FAILED_PRECONDITION eccezione con dettagli aggiuntivi 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)"
      }
    ]
  }
}

Abilita una chiave

Per riattivare una chiave associata a un database:

Visualizza le versioni della chiave in uso per un database
Abilita le versioni della chiave
Attendi che la modifica venga applicata e controlla se i dati non sono più accessibili. In genere le modifiche diventano effettive entro pochi minuti ma l'operazione può richiedere 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, è bene familiarità con Cloud Audit Logs.

Gli audit log di accesso ai dati di Cloud KMS mostrano quando Firestore o qualsiasi altro prodotto configurato per utilizzare il tuo La chiave CMEK effettua chiamate di crittografia/decrittografia a Cloud KMS. Firestore non invia una chiamata di crittografia/decrittografia su ogni dato richiesta, ma gestisce un poller che controlla periodicamente la chiave. La i risultati del polling 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.

Vai a Cloud Logging

Limita le voci di log alla chiave Cloud KMS aggiungendo il token 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_LOCATION

Fornisci quanto segue:

KMS_KEY: il nome della chiave CMEK
KMS_KEYRING: il keyring KMS che contiene la chiave
KMS_LOCATION: posizione del chiave e del keyring

Il log mostra un paio di voci di log ogni cinque minuti circa per database. Le voci di log sono simili a questi 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, consulta Informazioni sui log di controllo l'interpretazione degli audit log.

Configura un criterio dell'organizzazione CMEK

Per specificare i requisiti di conformità della crittografia per Firestore nella tua organizzazione, utilizza un vincolo del criterio dell'organizzazione CMEK.

Richiedi protezione CMEK

Configura constraints/gcp.restrictNonCmekServices per richiedere CMEK per Creazione di database Firestore. Imposta il vincolo su deny e aggiungi firestore.googleapis.com all'elenco di elementi 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, consulta Creazione e modifica dei criteri.

Dopo l'applicazione del criterio, ricevi un'eccezione FAILED_PRECONDITION e un messaggio di errore se provi a 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."
          }
        ]

Limitare l'uso delle chiavi per CMEK

Per limitare le chiavi Cloud KMS utilizzate per la protezione CMEK, configurare il vincolo constraints/gcp.restrictCmekCryptoKeyProjects.

Come vincolo di elenco, i valori accettati sono indicatori della gerarchia delle risorse (ad ad esempio projects/PROJECT_ID, under:folders/FOLDER_ID e under:organizations/ORGANIZATION_ID). Utilizza questo vincolo configurando di indicatori della gerarchia delle risorse e l'impostazione del vincolo su Consenti. Questa configurazione limita i servizi supportati in modo che sia possibile scegliere le chiavi CMEK solo dai progetti, dalle cartelle e dalle organizzazioni elencati. Richieste di creazione Le risorse protette da CMEK nei servizi configurati non avranno esito positivo senza Chiave Firestore 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 entrate in vigore le norme, riceverai un'eccezione (FAILED_PRECONDITION) e un messaggio di errore se violi il vincolo. Un'eccezione ha il seguente aspetto:

{
  "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."
          }
        ]
      }
    ]
  }
}

Passaggi successivi

Leggi la panoramica di Firestore e CMEK