رمزگذاری داده‌های کاربر

‫Data Manager API از رمزگذاری داده‌ها بااستفاده از سرویس‌های مدیریت کلید زیر پشتیبانی می‌کند:

پشتیبانی از برخی موارد استفاده براساس سرویس مدیریت کلید (KMS) متفاوت است:

دسته کاربرد Google Cloud KMS AWS KMS
مخاطبان ارسال اعضای مخاطب
رویدادها تبدیل‌های آفلاین یا تبدیل‌های بهبودیافته برای مشتریان بالقوه
رویدادها تبدیل‌های فروش فروشگاهی Google Ads
رویدادها تبدیل‌های چندمنبعی Google Ads
رویدادها رویدادهای چندمنبعی Google Analytics

راه‌اندازی 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 نشان‌دهنده تاریخ و زمانی است که اولین چرخش باید انجام شود.

    برای مثال، برای چرخش کلید هر ۳۰ روز یک‌بار و انجام اولین چرخش در ۱ هفته، 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 را ببینید.

  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 (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 Connect

ارائه‌دهنده هویت OpenID Connect (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. بااستفاده از فایل JSON و نام خط‌مشی انتخابی‌تان، خط‌مشی IAM ایجاد کنید.

    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) نیاز دارد. DEK کلیدی متقارن است که از آن برای رمزگذاری داده‌ها استفاده می‌کنید. «کلید رمزگذاری داده» شما بااستفاده از کلید رمزگذاری کلید (KEK) Google Cloud یا AWS KMS رمزگذاری می‌شود. DEK رمزگذاری‌شده، URI مربوط به KEK، و ارائه‌دهنده WIP را به‌عنوان بخشی از درخواست ارسال می‌کنید.

برای آماده‌سازی داده‌ها در درخواست رمزگذاری، همان دستورالعمل‌های قالب‌بندی و درهم‌سازی را که برای داده‌های رمزگذاری‌نشده استفاده می‌کنید دنبال کنید.

مقادیر درهم‌سازی‌نشده را رمزگذاری نکنید. برای مثال، region_code، postal_code، city، یا administrative_area AddressInfo را درهم‌سازی نکنید.

وقتی داده‌های هر فیلد قالب‌بندی و درهم‌سازی شد، مقدار درهم‌سازی‌شده را بااستفاده از مراحل زیر رمزگذاری کنید:

  1. بایت‌های درهم‌سازی را بااستفاده از کدبندی Base64 کدبندی کنید.

  2. درهم‌سازی کدبندی‌شده با Base64 را بااستفاده از DEK خود رمزگذاری کنید. چون رمز لازم XCHACHA20_POLY1305 است، تابع encrypt() Tink به پارامتر داده مرتبط نیاز دارد. این پارامتر باید خالی باشد (برای مثال، b"" در Python یا new byte[0] در Java). اگر null یا مقدار غیرخالی را ارسال کنید، Data Manager API نمی‌تواند داده‌ها را رمزگشایی کند.

  3. خروجی فرایند رمزگذاری را بااستفاده از کدبندی hex یا 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 استفاده کنید. به هرگونه هشدار در عیب‌یابی رسیدگی کنید، درخواست‌ها را دوباره ارسال کنید، و بررسی کنید که عیب‌یابی پس‌از تغییرات شما دیگر هشداری برنگرداند.

قبلی
قالب‌بندی داده‌های کاربر
بعدی
آشنایی با خطاهای میانای برنامه‌سازی کاربردی