تشفير بيانات المستخدمين

تتيح Data Manager API تشفير البيانات باستخدام خدمات إدارة المفاتيح التالية:

يختلف الدعم لبعض حالات الاستخدام حسب خدمة إدارة المفاتيح (KMS):

الفئة حالة الاستخدام Google Cloud KMS AWS KMS
شرائح الجمهور إرسال أعضاء شريحة الجمهور
الأحداث الإحالات الناجحة غير الإلكترونية أو الإحالات الناجحة المحسّنة للعملاء المحتملين
الأحداث الإحالات الناجحة للمبيعات في المتاجر على "إعلانات Google"
الأحداث الأحداث المُرسَلة كمصدر بيانات إضافي إلى وجهة في "إعلانات Google"
الأحداث الأحداث المُرسَلة كمصدر بيانات إضافي إلى وجهة في "إحصاءات Google"

إعداد Google Cloud KMS

في ما يلي خطوات إعداد موارد Google Cloud KMS للتشفير.

إعداد واجهة سطر الأوامر في Google Cloud

  1. ثبِّت واجهة سطر الأوامر في Google Cloud وأعِدّها.

  2. لاختيار مشروع Google Cloud جديد أو إنشائه وتفعيل الـ Cloud Key Management Service، انقر على تفعيل Cloud KMS.

    تفعيل Cloud KMS

  3. لضبط مشروعك في بيئتك، استخدِم الأمر gcloud config set. للتحقّق مما إذا كان المشروع قد تم ضبطه في بيئتك، شغِّل الأمر gcloud config list.

    إذا لم يتم ضبط project أو أردت استخدام مشروع مختلف لمفتاحك، شغِّل الأمر gcloud config set:

    gcloud config set project PROJECT_ID

إنشاء مفتاح

لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على Cloud Key Management Service.

  1. أنشئ سلسلة مفاتيح.

    gcloud kms keyrings create KEY_RING_NAME \
    --location KEY_RING_LOCATION

    لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء سلسلة مفاتيح.

  2. أنشئ مفتاحًا في سلسلة المفاتيح. يشير ROTATION_PERIOD إلى الفترة الزمنية لتغيير المفتاح، ويشير NEXT_ROTATION_TIME إلى التاريخ والوقت اللذين يجب أن يحدث فيهما التغيير الأول.

    على سبيل المثال، لتغيير المفتاح كل 30 يومًا وإجراء التغيير الأول بعد أسبوع واحد، اضبط ROTATION_PERIOD على 30d و NEXT_ROTATION_TIME على $(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"

    لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء مفتاح.

إنشاء موفِّر لمجموعة معلومات تعريفية للمعالجة

يقدّم هذا القسم نظرة عامة موجزة على Workload Identity Federation. لمزيد من المعلومات، يُرجى الاطّلاع على Workload Identity Federation.

  1. أنشئ مجموعة معلومات تعريفية للمعالجة (WIP). يجب أن يكون location للمجموعة global.

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

    لمزيد من المعلومات، يُرجى الاطّلاع على إدارة موفّري ومجموعات المعلومات التعريفية.

  2. أنشئ موفِّرًا لمجموعة معلومات تعريفية للمعالجة. تتحقّق الوسيطة --attribute-condition من أنّ مقدّم الطلب هو حساب خدمة مطابقة مراعية للخصوصية.

    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. امنح دور فك تشفير المفتاح لموفِّر 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. إذا أردت تشفير بيانات الأحداث للإحالات الناجحة غير الإلكترونية و الإحالات الناجحة المحسّنة للعملاء المحتملين، امنح دور فك تشفير المفتاح لحساب خدمة 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"

انتقِل إلى قسم تشفير البيانات.

إعداد AWS KMS

في ما يلي خطوات إعداد موارد AWS KMS للتشفير.

إعداد واجهة سطر الأوامر في AWS

  1. ثبِّت واجهة سطر الأوامر في AWS.

  2. شغِّل الأمر التالي للتحقّق من عملية التثبيت:

    aws --version

    في ما يلي مقتطف من الناتج لعملية تثبيت ناجحة:

    aws-cli/2.31.12 Python/3.13.7 ...

إعداد مستخدم في AWS وتسجيل الدخول

  1. أكمِل المتطلبات الأساسية لاستخدام واجهة سطر الأوامر في AWS.
  2. سجِّل الدخول إلى جلسة IAM Identity Center.

إنشاء مفتاح

  1. أنشئ مفتاح تشفير متماثلاً في KMS (KEK).

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

    سجِّل Arn ضِمن KeyMetadata في الناتج. ستحتاج إلى اسم مورد Amazon Amazon (ARN) هذا في خطوات أخرى.

    AWS_KEY_ARN

  2. اختياري: أنشئ اسمًا بديلًا للمفتاح باستخدام اسم بديل من اختيارك.

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

    ليس الاسم البديل مطلوبًا، ولكنّه مفيد لإنشاء أوامر واجهة سطر الأوامر في AWS. على سبيل المثال، يمكنك استرداد ARN للمفتاح باستخدام الاسم البديل:

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

إنشاء موفِّر هوية اتصال OpenID

أنشئ موفِّر هوية اتصال OpenID ‏ (OIDC). عليك تنفيذ هذه الخطوة مرة واحدة فقط لكل حساب على AWS.

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

سجِّل ARN لموفِّر OIDC من الناتج. ستحتاج إلى هذا في خطوات أخرى.

AWS_OIDC_PROVIDER_ARN

إنشاء سياسة IAM

  1. أنشئ ملف JSON باسم kms-decrypt-policy.json يتضمّن المحتوى التالي:

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

  2. أنشئ سياسة IAM باستخدام ملف JSON و اسم سياسة من اختيارك.

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

    سجِّل ARN لسياسة IAM في الناتج. ستحتاج إلى هذا في خطوات أخرى.

    AWS_IAM_POLICY_ARN

إنشاء دور IAM وإرفاقه

  1. أنشئ ملف JSON باسم role-trust-policy.json يتضمّن المحتوى التالي وARN لموفِّر OIDC من الخطوة السابقة:

    {
    "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. أنشئ دور IAM باسم دور من اختيارك.

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

  3. أرفِق سياسة الدور بسياسة IAM.

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

تشفير البيانات

يتطلّب التشفير في Data Manager API مفتاح تشفير بيانات (DEK). مفتاح تشفير البيانات هو مفتاح متماثل تستخدمه لتشفير البيانات. يتم تشفير مفتاح تشفير البيانات باستخدام مفتاح تشفير المفتاح (KEK) في Google Cloud أو AWS KMS. أرسِل مفتاح تشفير البيانات المشفّر وURI لمفتاح تشفير المفتاح وموفِّر WIP كجزء من الطلب.

لإعداد البيانات في الطلب للتشفير، اتّبِع إرشادات التنسيق والتجزئة نفسها التي تستخدمها للبيانات غير المشفّرة.

لا تشفِّر القيم غير المجزّأة. على سبيل المثال، الـ region_code أو postal_code في AddressInfo.

بعد تنسيق بيانات كل حقل وتجزئتها، شفِّر القيمة المجزّأة باستخدام الخطوات التالية:

  1. رمِّز وحدات البايت المجزّأة باستخدام ترميز Base64.
  2. شفِّر التجزئة المرمّزة بـ Base64 باستخدام مفتاح تشفير البيانات.
  3. رمِّز الناتج من عملية التشفير باستخدام ترميز سداسي عشري أو ترميز Base64.
  4. استخدِم القيمة المرمّزة للحقل.
  5. اضبط encryption_info و encoding في الطلب.

لإكمال الخطوة الأخيرة، عدِّل الـ IngestAudienceMembersRequest أو الـ IngestEventsRequest للإشارة إلى أنّك شفّرت بياناتك:

  • اضبط حقل encryption_info.
  • اضبط حقل encoding على الترميز المستخدَم لترميز قيم الحقول المشفّرة.

في ما يلي مقتطف من طلب يستخدم مفتاح Google Cloud KMS مع ضبط حقلَي التشفير والترميز:

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

لاستخدام مكتبة Data Manager API والأدوات المساعدة لإنشاء طلب وإرساله، يُرجى الاطّلاع على عينة التعليمات البرمجية IngestAudienceMembers للغة Java أو عينة التعليمات البرمجية ingest_audience_members للغة Python.

التحقّق من بيانات التشخيص بحثًا عن مشاكل التشفير

بعد تحميل البيانات المشفّرة، استخدِم بيانات التشخيص للتحقّق من أي تحذيرات متعلقة بالتشفير، مثل PROCESSING_WARNING_REASON_KEK_PERMISSION_DENIED أو PROCESSING_WARNING_REASON_DEK_DECRYPTION_ERROR. عالِج أي تحذيرات في بيانات التشخيص، وأرسِل الطلبات مرة أخرى، وتأكَّد من أنّ بيانات التشخيص لم تعُد تعرض تحذيرات بعد إجراء التغييرات.

السابق
تنسيق بيانات المستخدمين
التالي
التعرّف على أخطاء واجهة برمجة التطبيقات