Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzo delle chiavi di crittografia gestite dal cliente (CMEK)

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, incluso quando e perché attivarlo, consulta la documentazione di Cloud KMS.

Prepara le chiavi CMEK

Prima di poter creare un database in modalità Datastore protetto tramite CMEK, devi completare i seguenti passaggi:

Richiedi l'accesso alla funzionalità CMEK in modalità Datastore.
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 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 in modalità Datastore, richiedi l'accesso al funzionalità CMEK compilando questo modulo.

Crea un agente di servizio in modalità Datastore

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

Esegui il comando services Identity create per crea l'agente di servizio che la modalità Datastore utilizza per accedere a 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 di utilizzare per i database in modalità Datastore.

Il comando visualizza l'ID agente di servizio, che formattato come un indirizzo email. Prendi nota della stringa email di output, poiché la 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 una chiave con gestione esterna che rendi disponibile con Cloud External Key Manager.

La posizione della chiave Cloud KMS deve essere uguale alla posizione del database in modalità Datastore con cui verrà utilizzata.

Per le località dei database regionali, utilizza lo stesso nome della località per il portachiavi, la chiave e il database perché i nomi delle località hanno una mappatura uno a uno.

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à dei database multiregione, utilizza il nome della località della località multiregione KMS:
- Utilizza la posizione multiregionale us di Cloud KMS per la posizione multiregionale nam5 della modalità Datastore.
- Utilizza la località a più regioni europe di Cloud KMS per la località a più regioni eur3 in modalità Datastore.

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

Abilita l'API Cloud KMS.
Crea un mazzo di chiavi 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 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 in formato email per l'agente di servizio in modalità Datastore.
Seleziona il ruolo Cloud KMS CryptoKey Encrypter/Decrypter.
Fai clic su Salva.

gcloud

Concedi il ruolo cloudkms.cryptoKeyEncrypterDecrypter all'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: la raccolta di chiavi 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. I database esistenti in modalità Datastore protetti dalla crittografia predefinita di Google non possono essere convertiti per l'utilizzo di CMEK. Puoi scegliere un tipo di crittografia e una chiave solo 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 posizione della modalità Datastore 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 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.

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 il database in modalità Datastore
DATABASE_ID: un ID per il database
FIRESTORE_DATABASE_LOCATION: la località in modalità Datastore per il database
DATABASE_TYPE: FIRESTORE_NATIVE per la modalità nativa 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

Accedere a un database protetto tramite 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.

Visualizzare la chiave in uso

gcloud

Puoi utilizzare il comando gcloud CLI databases describe per confermare la configurazione della crittografia gestita dal cliente 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. Impostato 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 ulteriori 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 disattivare una chiave associata a un database:

Visualizzare le versioni delle chiavi 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 è disattivata, 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)"
      }
    ]
  }
}

Abilita una chiave

Per riattivare una chiave associata a un database:

Visualizzare le versioni delle chiavi 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.

I log di controllo dell'accesso ai dati di Cloud KMS mostrano quando la modalità Datastore o altri prodotti configurati per utilizzare la chiave CMEK effettuano chiamate di crittografia/decrittografia a Cloud KMS. La modalità Datastore non emette una chiamata di crittografia/decrittografia per ogni richiesta di dati, ma gestisce un poller che controlla la chiave periodicamente. I risultati del polling vengono visualizzati nei log di controllo.

Puoi configurare e interagire con i log di controllo 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 informazioni dettagliate sull'interpretazione dei log di controllo, consulta Informazioni sugli audit log.

Configura un criterio dell'organizzazione CMEK

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

Richiedi protezione CMEK

Configura constraints/gcp.restrictNonCmekServices in modo che richieda 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 scoprire di più sulla configurazione dei criteri dell'organizzazione, consulta Creare e modificare i 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'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 della gerarchia delle risorse e impostando il vincolo su Consenti. Questa configurazione limita i servizi supportati in modo che le chiavi CMEK possano essere scelte solo tra i progetti, le cartelle e le organizzazioni elencati. Richieste di creazione Le risorse protette da CMEK nei servizi configurati non avranno esito positivo senza Chiave in modalità Datastore da una delle risorse consentite.

L'esempio seguente consente solo le chiavi di ALLOWED_KEY_PROJECT_ID per i database protetti tramite 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 della modalità Datastore e CMEK