Cripta i dati utente

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

Il supporto per 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 Invio di membri del segmento di pubblico
Eventi Conversioni offline o conversioni avanzate per i lead
Eventi Conversioni di vendite in negozio di Google Ads
Eventi Eventi inviati come origine dati aggiuntiva a una destinazione Google Ads
Eventi Eventi inviati come origine dati aggiuntiva a una destinazione Google Analytics

Configurare Google Cloud KMS

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

Configurare 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 attivare il Cloud Key Management Service, fai clic su Attiva Cloud KMS.

    Attiva Cloud KMS

  3. Per impostare il progetto nel tuo ambiente, utilizza il gcloud config set comando. 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 ulteriori informazioni, consulta la panoramica di Cloud Key Management Service.

  1. Crea un keyring.

    gcloud kms keyrings create KEY_RING_NAME \
    --location KEY_RING_LOCATION

    Per ulteriori informazioni, consulta Creare un keyring.

  2. Crea una chiave nel keyring. Il ROTATION_PERIOD indica l' intervallo di rotazione della chiave, mentre il 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 ulteriori informazioni, consulta Creare una chiave.

Crea un provider 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). La location del pool deve essere global.

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

    Per ulteriori informazioni, consulta Gestire i fornitori e i pool di identità del workload.

  2. Crea un provider 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 decrittatore della chiave 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 degli eventi per le conversioni offline e le conversioni avanzate per i lead, concedi il ruolo di utilità 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 Criptare i dati.

Configurare AWS KMS

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

Configurare l'interfaccia a riga di comando di AWS

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

  2. Esegui questo comando per verificare l'installazione:

    aws --version

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

    aws-cli/2.31.12 Python/3.13.7 ...

Configurare un utente AWS ed eseguire l'accesso

  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. Avrai bisogno di questo nome risorsa Amazon (ARN) in altri passaggi.

    AWS_KEY_ARN

  2. (Facoltativo) Crea un alias della chiave utilizzando un nome di 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 comandi dell'interfaccia a riga di comando di 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 ogni 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 nell'output. Ti servirà in altri passaggi.

AWS_OIDC_PROVIDER_ARN

Crea un criterio 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 un criterio IAM utilizzando il file JSON e un nome di criterio di tua scelta.

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

    Prendi nota dell'ARN del criterio IAM nell'output. Ti servirà in altri passaggi.

    AWS_IAM_POLICY_ARN

Crea e allega 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 ruolo di tua scelta.

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

  3. Allega il criterio del ruolo al criterio IAM.

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

Criptare 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. Invii la DEK criptata, l'URI della KEK e il provider WIP come parte della richiesta.

Per preparare i dati nella richiesta per la 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, region_code o postal_code di un AddressInfo.

Una volta che i dati di ogni campo sono formattati e sottoposti ad hashing, cripta il valore sottoposto ad hashing seguendo questi passaggi:

  1. Codifica i byte di hash utilizzando la codifica Base64.
  2. Cripta l'hash codificato in Base64 utilizzando la DEK.
  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 dati:

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

Ecco un 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.

Controllare la diagnostica per verificare la presenza di problemi di crittografia

Dopo aver caricato i dati criptati, utilizza la diagnostica per verificare la presenza di 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 di nuovo le richieste e verifica che la diagnostica non restituisca più avvisi dopo le modifiche.

Indietro
Formattare i dati utente
Avanti
Informazioni sugli errori API