Nutzerdaten verschlüsseln

Die Data Manager API unterstützt die Verschlüsselung von Daten mit den folgenden Schlüsselverwaltungsdiensten:

Die Unterstützung für einige Anwendungsfälle unterscheidet sich je nach Key Management Service (KMS):

Kategorie Anwendungsfall Google Cloud KMS AWS KMS
Zielgruppen Zielgruppenmitglieder senden
Ereignisse Offline-Conversions oder erweiterte Conversions für Leads
Ereignisse Google Ads-Conversions in Form von Ladenverkäufen
Ereignisse Google Ads-Conversions mit mehreren Quellen
Ereignisse Google Analytics-Ereignisse aus mehreren Quellen

Google Cloud KMS einrichten

So richten Sie Google Cloud KMS-Ressourcen für die Verschlüsselung ein:

Google Cloud-Befehlszeile einrichten

  1. Installieren und initialisieren Sie die Google Cloud-Befehlszeile.

  2. Klicken Sie auf Cloud KMS aktivieren, um ein neues Google Cloud-Projekt auszuwählen oder zu erstellen und den Cloud Key Management Service zu aktivieren.

    Cloud KMS aktivieren

  3. Verwenden Sie den Befehl gcloud config set, um Ihr Projekt in Ihrer Umgebung festzulegen. Mit gcloud config list können Sie prüfen, ob das Projekt bereits in Ihrer Umgebung festgelegt ist.

    Wenn kein project festgelegt ist oder Sie ein anderes Projekt für Ihren Schlüssel verwenden möchten, führen Sie gcloud config set aus:

    gcloud config set project PROJECT_ID

Schlüssel erstellen

Weitere Informationen finden Sie unter Cloud Key Management Service – Übersicht.

  1. Schlüsselbund erstellen

    gcloud kms keyrings create KEY_RING_NAME \
    --location KEY_RING_LOCATION

    Weitere Informationen finden Sie unter Schlüsselbund erstellen.

  2. Erstellen Sie einen Schlüssel im Schlüsselbund. ROTATION_PERIOD gibt das Intervall für die Rotation des Schlüssels an und NEXT_ROTATION_TIME gibt das Datum und die Uhrzeit an, zu der die erste Rotation erfolgen soll.

    Wenn Sie den Schlüssel beispielsweise alle 30 Tage rotieren und die erste Rotation in einer Woche durchführen möchten, setzen Sie ROTATION_PERIOD auf 30d und NEXT_ROTATION_TIME auf $(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"

    Weitere Informationen finden Sie unter Schlüssel erstellen.

Workload Identity-Poolanbieter erstellen

Dieser Abschnitt bietet einen kurzen Überblick über die Workload Identity-Föderation. Weitere Informationen finden Sie unter Workload Identity-Föderation.

  1. Erstellen Sie einen Workload Identity-Pool (WIP). Der location für den Pool muss global sein.

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

    Weitere Informationen finden Sie unter Workload Identity-Pools und -Anbieter verwalten.

  2. Erstellen Sie einen Workload Identity-Poolanbieter. Mit dem Argument --attribute-condition wird geprüft, ob der Aufrufer ein Dienstkonto für den vertraulichen Abgleich ist.

    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. Weisen Sie dem WIP-Anbieter die Rolle „Key Decrypter“ zu.

    # 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. Wenn Sie Ereignisdaten für Offline-Conversions und erweiterte Conversions für Leads verschlüsseln möchten, weisen Sie dem Google-Dienstkonto datamanager-api@datamanager-ga.iam.gserviceaccount.com die Rolle „Schlüsselentschlüsseler“ zu.

    # 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"

Fahren Sie mit dem Abschnitt Daten verschlüsseln fort.

AWS KMS einrichten

So richten Sie AWS KMS-Ressourcen für die Verschlüsselung ein:

AWS-Befehlszeile einrichten

  1. Installieren Sie die AWS-Befehlszeile.

  2. Führen Sie den folgenden Befehl aus, um die Installation zu prüfen:

    aws --version

    Hier ist ein Snippet der Ausgabe für eine erfolgreiche Installation:

    aws-cli/2.31.12 Python/3.13.7 ...

AWS-Nutzer einrichten und anmelden

  1. Erfüllen Sie die Voraussetzungen für die Verwendung der AWS-Befehlszeile.
  2. Melden Sie sich bei einer IAM Identity Center-Sitzung an.

Schlüssel erstellen

  1. Erstellen Sie einen symmetrischen KMS-Schlüssel (KEK).

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

    Notieren Sie sich den Arn unter KeyMetadata in der Ausgabe. Sie benötigen diesen Amazon Resource Name (ARN) in anderen Schritten.

    AWS_KEY_ARN

  2. Optional: Erstellen Sie einen Schlüsselalias mit einem Aliasnamen Ihrer Wahl.

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

    Ein Alias ist nicht erforderlich, aber nützlich, um Befehle für die AWS-Befehlszeile zu erstellen. Sie können den Schlüssel-ARN beispielsweise mit dem Alias abrufen:

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

OpenID Connect-Identitätsanbieter erstellen

OpenID Connect-Identitätsanbieter (OIDC) erstellen Sie müssen diesen Schritt nur einmal pro AWS-Konto ausführen.

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

Notieren Sie sich den ARN des OIDC-Anbieters aus der Ausgabe. Sie benötigen diese Angabe in anderen Schritten.

AWS_OIDC_PROVIDER_ARN

IAM-Richtlinie erstellen

  1. Erstellen Sie eine JSON-Datei mit dem Namen kms-decrypt-policy.json und folgendem Inhalt:

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

  2. Erstellen Sie eine IAM-Richtlinie mit der JSON-Datei und einem Richtliniennamen Ihrer Wahl.

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

    Notieren Sie sich den ARN der IAM-Richtlinie in der Ausgabe. Sie benötigen diese Angabe in anderen Schritten.

    AWS_IAM_POLICY_ARN

IAM-Rolle erstellen und anhängen

  1. Erstellen Sie eine JSON-Datei mit dem Namen role-trust-policy.json und folgendem Inhalt sowie dem ARN des OIDC-Anbieters aus dem vorherigen Schritt:

    {
    "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. Erstellen Sie eine IAM-Rolle mit einem Rollennamen Ihrer Wahl.

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

  3. Hängen Sie die Rollenrichtlinie an die IAM-Richtlinie an.

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

Daten verschlüsseln

Für die Verschlüsselung in der Data Manager API ist ein Datenverschlüsselungsschlüssel (Data Encryption Key, DEK) erforderlich. Ein DEK ist ein symmetrischer Schlüssel, den Sie zum Verschlüsseln von Daten verwenden. Ihr DEK wird mit dem Schlüsselverschlüsselungsschlüssel (Key Encryption Key, KEK) von Google Cloud oder AWS KMS verschlüsselt. Sie senden den verschlüsselten DEK, den KEK-URI und den WIP-Anbieter als Teil der Anfrage.

Wenn Sie die Daten in der Anfrage für die Verschlüsselung vorbereiten möchten, folgen Sie den Formatierungs- und Hash-Richtlinien, die Sie auch für unverschlüsselte Daten verwenden würden.

Verschlüsseln Sie keine Werte, die nicht gehasht sind. Hashen Sie beispielsweise nicht die region_code, postal_code, city oder administrative_area eines AddressInfo.

Nachdem die Daten für jedes Feld formatiert und gehasht wurden, verschlüsseln Sie den Hash-Wert mit den folgenden Schritten:

  1. Codieren Sie die Hash-Bytes mit der Base64-Codierung.

  2. Verschlüsseln Sie den Base64-codierten Hash mit Ihrem DEK. Da die erforderliche Chiffre XCHACHA20_POLY1305 ist, erfordert die Tink-Funktion encrypt() einen zugehörigen Datenparameter. Dieser Parameter muss leer sein (z. B. b"" in Python oder new byte[0] in Java). Wenn Sie null oder einen nicht leeren Wert übergeben, kann die Data Manager API die Daten nicht entschlüsseln.

  3. Codieren Sie die Ausgabe des Verschlüsselungsprozesses entweder mit der Hexadezimal- oder der Base64-Codierung.

  4. Verwenden Sie den codierten Wert für das Feld.

  5. Legen Sie encryption_info und encoding für die Anfrage fest.

Ändern Sie im letzten Schritt IngestAudienceMembersRequest oder IngestEventsRequest, um anzugeben, dass Sie Ihre Daten verschlüsselt haben:

  • Legen Sie das Feld encryption_info fest.

  • Setzen Sie das Feld encoding auf die Codierung, die zum Codieren der verschlüsselten Feldwerte verwendet wurde.

Hier ist ein Snippet einer Anfrage mit einem Google Cloud KMS-Schlüssel und den Feldern für Verschlüsselung und Codierung:

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

Wenn Sie die Bibliothek und Dienstprogramme der Data Manager API verwenden möchten, um eine Anfrage zu erstellen und zu senden, sehen Sie sich das IngestAudienceMembers-Codebeispiel für Java oder das ingest_audience_members-Codebeispiel für Python an.

Diagnoseinformationen auf Verschlüsselungsprobleme prüfen

Nachdem Sie verschlüsselte Daten hochgeladen haben, können Sie mithilfe der Diagnose nach Warnungen im Zusammenhang mit der Verschlüsselung suchen, z. B. PROCESSING_WARNING_REASON_KEK_PERMISSION_DENIED oder PROCESSING_WARNING_REASON_DEK_DECRYPTION_ERROR. Beheben Sie alle Warnungen in der Diagnose, senden Sie die Anfragen noch einmal und prüfen Sie, ob nach Ihren Änderungen keine Warnungen mehr zurückgegeben werden.

Zurück
Nutzerdaten formatieren
Weiter
API-Fehler verstehen