Cripta i dati utente

L'API Data Manager supporta la crittografia dei dati utilizzando i seguenti servizi di gestione delle chiavi:

Il supporto di alcuni casi d'uso varia in base al servizio di gestione delle chiavi (KMS):

Categoria Caso d'uso Google Cloud KMS AWS KMS
Segmenti di pubblico Invia membri del segmento di pubblico
Eventi Conversioni offline o conversioni avanzate per i lead
Eventi Conversioni per le vendite in negozio di Google Ads
Eventi Conversioni multisorgente di Google Ads
Eventi Eventi da più origini di Google Analytics

Configura Google Cloud KMS

Ecco i passaggi per configurare le risorse Google Cloud KMS per la crittografia.

Configura l'interfaccia a riga di comando di Google Cloud

  1. Installa e inizializza l'interfaccia a riga di comando di Google Cloud.

  2. Per selezionare o creare un nuovo progetto Google Cloud e abilitare Cloud Key Management Service, fai clic su Abilita Cloud KMS.

    Abilita Cloud KMS

  3. Per impostare il progetto nel tuo ambiente, utilizza il comando gcloud config set. Per verificare se il progetto è già impostato nel tuo ambiente, esegui gcloud config list.

    Se non è impostato alcun project o se vuoi utilizzare un progetto diverso per la chiave, esegui gcloud config set:

    gcloud config set project PROJECT_ID

Crea una chiave

Per saperne di più, consulta la panoramica di Cloud Key Management Service.

  1. Crea chiavi automatizzate.

    gcloud kms keyrings create KEY_RING_NAME \
    --location KEY_RING_LOCATION

    Per saperne di più, consulta Crea chiavi automatizzate.

  2. Crea una chiave nella chiave automatizzata. ROTATION_PERIOD indica l'intervallo di rotazione della chiave, mentre NEXT_ROTATION_TIME indica la data e l'ora in cui deve avvenire la prima rotazione.

    Ad esempio, per ruotare la chiave ogni 30 giorni ed eseguire la prima rotazione tra una settimana, imposta ROTATION_PERIOD su 30d e NEXT_ROTATION_TIME su $(date --utc --date="next week" --iso-8601=seconds).

    gcloud kms keys create KEY_NAME \
    --keyring KEY_RING_NAME \
    --location KEY_RING_LOCATION \
    --purpose "encryption" \
    --rotation-period ROTATION_PERIOD \
    --next-rotation-time "NEXT_ROTATION_TIME"

    Per saperne di più, consulta Crea una chiave.

Crea un provider di pool di identità del workload

Questa sezione fornisce una breve panoramica della federazione delle identità per i workload. Per ulteriori informazioni, consulta Federazione delle identità per i workload.

  1. Crea un pool di identità del workload (WIP). Il valore location per il pool deve essere global.

    gcloud iam workload-identity-pools create WIP_ID \
   --location=global \
   --display-name="WIP_DISPLAY_NAME" \
   --description="WIP_DESCRIPTION"

    Per saperne di più, consulta Gestisci i provider e i pool di identità del workload.

  2. Crea un provider di pool di identità del workload. L'argomento --attribute-condition verifica che il chiamante sia un service account di corrispondenza confidenziale.

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
   --location=global \
   --workload-identity-pool=WIP_ID \
   --display-name="PROVIDER_DISPLAY_NAME" \
   --description="PROVIDER_DESCRIPTION" \
   --attribute-mapping="google.subject=assertion.sub,google.groups=[\"PROVIDER_ID\"]" \
   --attribute-condition="assertion.swname == 'CONFIDENTIAL_SPACE' &&
     'STABLE' in assertion.submods.confidential_space.support_attributes &&
     ['cfm-services@admcloud-cfm-services.iam.gserviceaccount.com'].exists(
         a, a in assertion.google_service_accounts) &&
     'ECDSA_P256_SHA256:6b1f357b59e9407fb017ca0e3e783b2bd5acbfea6c83dd82971a4150df5b25f9'
     in assertion.submods.container.image_signatures.map(sig, sig.signature_algorithm+':'+sig.key_id)" \
   --issuer-uri="https://confidentialcomputing.googleapis.com" \
   --allowed-audiences="https://sts.googleapis.com"

  3. Concedi il ruolo di decrittografia delle chiavi al provider WIP.

    # Grants the role to the WIP provider.
gcloud kms keys add-iam-policy-binding KEY_NAME \
    --keyring KEY_RING_NAME \
    --location KEY_RING_LOCATION \
    --member "principalSet://iam.googleapis.com/projects/PROJECT_ID/locations/global/workloadIdentityPools/WIP_ID/group/PROVIDER_ID" \
    --role "roles/cloudkms.cryptoKeyDecrypter"

  4. Se vuoi criptare i dati sugli eventi per le conversioni offline e le conversioni avanzate per i lead, concedi il ruolo di decrittografia della chiave al service account Google datamanager-api@datamanager-ga.iam.gserviceaccount.com.

    # Grants the role to the Google service account.
gcloud kms keys add-iam-policy-binding KEY_NAME \
    --keyring KEY_RING_NAME \
    --location KEY_RING_LOCATION \
    --member "serviceAccount:datamanager-api@datamanager-ga.iam.gserviceaccount.com" \
    --role "roles/cloudkms.cryptoKeyDecrypter"

Vai alla sezione Cripta i dati.

Configura AWS KMS

Ecco i passaggi per configurare le risorse AWS KMS per la crittografia.

Configura l'interfaccia a riga di comando AWS

  1. Installa l'interfaccia a riga di comando AWS.

  2. Esegui questo comando per verificare l'installazione:

    aws --version

    Ecco uno snippet dell'output per un'installazione riuscita:

    aws-cli/2.31.12 Python/3.13.7 ...

Configura un utente AWS e accedi

  1. Completa i prerequisiti per l'utilizzo dell'interfaccia a riga di comando di AWS.
  2. Accedi a una sessione di IAM Identity Center.

Crea una chiave

  1. Crea una chiave KMS simmetrica (KEK).

    aws kms create-key \
  --key-usage ENCRYPT_DECRYPT \
  --key-spec SYMMETRIC_DEFAULT \
  --description "KEK for Confidential Matching Data Encryption"

    Prendi nota di Arn in KeyMetadata nell'output. Ti servirà questo Amazon Resource Name (ARN) in altri passaggi.

    AWS_KEY_ARN

  2. (Facoltativo) Crea un alias della chiave utilizzando un nome alias di tua scelta.

    aws kms create-alias \
  --alias-name "alias/AWS_KEY_ALIAS" \
  --target-key-id AWS_KEY_ARN

    Un alias non è obbligatorio, ma è utile per creare i comandi dell'interfaccia a riga di comando AWS. Ad esempio, puoi recuperare l'ARN della chiave utilizzando l'alias:

    aws kms describe-key --key-id "alias/AWS_KEY_ALIAS" \
  --query 'KeyMetadata.Arn' \
  --output text

Crea un provider di identità OpenID Connect

Crea un provider di identità OpenID Connect (OIDC). Devi eseguire questo passaggio una sola volta per account AWS.

aws iam create-open-id-connect-provider \
  --url https://confidentialcomputing.googleapis.com \
  --client-id-list AUDIENCE \
  --thumbprint-list "08745487e891c19e3078c1f2a07e452950ef36f6"

Prendi nota dell'ARN del provider OIDC dall'output. Ti servirà nei passaggi successivi.

AWS_OIDC_PROVIDER_ARN

Crea una policy IAM

  1. Crea un file JSON denominato kms-decrypt-policy.json con i seguenti contenuti:

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": "AWS_KEY_ARN"
    }
  ]
}

  2. Crea una policy IAM utilizzando il file JSON e un nome della policy a tua scelta.

    aws iam create-policy \
  --policy-name "AWS_POLICY_NAME" \
  --policy-document file://kms-decrypt-policy.json

    Prendi nota dell'ARN della policy IAM nell'output. Ti servirà nei passaggi successivi.

    AWS_IAM_POLICY_ARN

Crea e collega un ruolo IAM

  1. Crea un file JSON denominato role-trust-policy.json con i seguenti contenuti e l'ARN del provider OIDC del passaggio precedente:

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "AWS_OIDC_PROVIDER_ARN"
            },
            "Action": [
                "sts:AssumeRoleWithWebIdentity",
                "sts:TagSession"
            ],
            "Condition": {
                "StringEquals": {
                    "confidentialcomputing.googleapis.com:aud": "cfm-awsresource",
                    "aws:RequestTag/swname": "CONFIDENTIAL_SPACE",
                    "aws:RequestTag/container.signatures.key_ids": "6b1f357b59e9407fb017ca0e3e783b2bd5acbfea6c83dd82971a4150df5b25f9"
                },
                "StringLike": {
                    "aws:RequestTag/confidential_space.support_attributes": "*STABLE*"
                }
            }
        }
    ]
}

  2. Crea un ruolo IAM con un nome di tua scelta.

    aws iam create-role \
  --role-name "AWS_IAM_ROLE_NAME" \
  --assume-role-policy-document file://role-trust-policy.json

  3. Collega la policy del ruolo alla policy IAM.

    aws iam attach-role-policy \
  --role-name "AWS_IAM_ROLE_NAME" \
  --policy-arn "AWS_IAM_POLICY_ARN"

Cripta i dati

La crittografia nell'API Data Manager richiede una chiave di crittografia dei dati (DEK). Una DEK è una chiave simmetrica che utilizzi per criptare i dati. La DEK viene criptata utilizzando la chiave di crittografia della chiave (KEK) di Google Cloud o AWS KMS. Invia la DEK criptata, l'URI della KEK e il provider WIP come parte della richiesta.

Per preparare i dati nella richiesta di crittografia, segui le stesse linee guida per la formattazione e l'hashing che utilizzeresti per i dati non criptati.

Non criptare i valori non sottoposti ad hashing. Ad esempio, non eseguire l'hashing di region_code, postal_code, city o administrative_area di un AddressInfo.

Una volta formattati e sottoposti ad hashing i dati di ogni campo, crittografa il valore hash seguendo questi passaggi:

  1. Codifica i byte dell'hash utilizzando la codifica Base64.

  2. Cripta l'hash con codifica Base64 utilizzando la DEK. Poiché la crittografia richiesta è XCHACHA20_POLY1305, la funzione encrypt() di Tink richiede un parametro di dati associato. Questo parametro deve essere vuoto (ad esempio, b"" in Python o new byte[0] in Java). Se passi null o un valore non vuoto, l'API Data Manager non può decriptare i dati.

  3. Codifica l'output del processo di crittografia utilizzando la codifica esadecimale o Base64.

  4. Utilizza il valore codificato per il campo.

  5. Imposta encryption_info e encoding nella richiesta.

Per completare l'ultimo passaggio, modifica IngestAudienceMembersRequest o IngestEventsRequest per indicare che hai criptato i tuoi dati:

  • Imposta il campo encryption_info.

  • Imposta il campo encoding sulla codifica utilizzata per codificare i valori dei campi criptati.

Ecco uno snippet di una richiesta che utilizza una chiave Google Cloud KMS e con i campi di crittografia e codifica impostati:

{
  ...
  "encryptionInfo": {
    "gcpWrappedKeyInfo": {
      "kekUri": "gcp-kms://projects/PROJECT_ID/locations/KEY_RING_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME",
      "wipProvider": "projects/PROJECT_ID/locations/global/workloadIdentityPools/WIP_ID/providers/PROVIDER_ID",
      "keyType": "XCHACHA20_POLY1305",
      "encryptedDek": "ENCRYPTED_DEK"
    }
  },
  "encoding": "ENCODING"
}

Per utilizzare la libreria e le utilità dell'API Data Manager per creare e inviare una richiesta, consulta l'esempio di codice IngestAudienceMembers per Java o l'esempio di codice ingest_audience_members per Python.

Controlla la diagnostica per verificare la presenza di problemi di crittografia

Dopo aver caricato i dati criptati, utilizza la diagnostica per verificare la presenza di eventuali avvisi relativi alla crittografia, ad esempio PROCESSING_WARNING_REASON_KEK_PERMISSION_DENIED o PROCESSING_WARNING_REASON_DEK_DECRYPTION_ERROR. Risolvi eventuali avvisi nella diagnostica, invia nuovamente le richieste e verifica che la diagnostica non restituisca più avvisi dopo le modifiche.

Indietro
Formattare i dati utente
Avanti
Informazioni sugli errori API