מפתחות הצפנה בניהול הלקוח (CMEK)

כברירת מחדל, Gemini Data Analytics מצפין את התוכן של הלקוחות במצב מנוחה. ‫Gemini Data Analytics מטפל בהצפנה בשבילכם בלי שתצטרכו לבצע פעולות נוספות. האפשרות הזו נקראת הצפנת ברירת המחדל של Google.

אם אתם רוצים לשלוט במפתחות ההצפנה, אתם יכולים להשתמש במפתחות הצפנה בניהול הלקוח (CMEK) ב-Cloud KMS עם שירותים שמשולבים עם CMEK, כולל Gemini Data Analytics. שימוש במפתחות Cloud KMS מאפשר לכם לשלוט ברמת ההגנה, במיקום, בלוח הזמנים של הרוטציה, בשימוש ובהרשאות הגישה, ובגבולות הקריפטוגרפיים. בנוסף, באמצעות Cloud KMS תוכלו לצפות ביומני ביקורת ולשלוט במחזורי החיים של המפתחות. במקום ש-Google תהיה הבעלים של מפתחות ההצפנה של המפתחות (KEK) הסימטריים שמגנים על הנתונים שלכם ותנהל אותם, אתם שולטים במפתחות האלה ומנהלים אותם ב-Cloud KMS.

אחרי שמגדירים את המשאבים עם CMEK, הגישה למשאבים של Gemini Data Analytics דומה לשימוש בהצפנת ברירת המחדל של Google. מידע נוסף על אפשרויות ההצפנה זמין במאמר מפתחות הצפנה בניהול הלקוח (CMEK).

בדף הזה מוסבר איך להשתמש במפתחות הצפנה בניהול הלקוח (CMEK) כדי להגן על נתונים שמשמשים את Conversational Analytics API עם מקורות נתונים של Looker. ‫Conversational Analytics API הוא מוצר בשירות Gemini Data Analytics‏ (geminidataanalytics.googleapis.com).

CMEK למשאבים של Conversational Analytics API

כשמגדירים CMEK למשאב Conversational Analytics API, המפתח שצוין ב-Cloud KMS מצפין את המידע האישי הרגיש במצב מנוחה. אפשר להגדיר CMEK למשאבי DataAgent ו-Conversation בנפרד.

אפשר להגדיר CMEK רק בזמן יצירת המשאב. כדי להשתמש ב-CMEK, צריך לציין את השדה kms_key כשיוצרים משאב DataAgent או Conversation. אי אפשר להוסיף או לשנות מפתח Cloud KMS במשאב קיים.

מה מוגן באמצעות CMEK

התכונה CMEK for the Conversational Analytics API מגנה על הנתונים הבאים במצב מנוחה:

  • משאבי DataAgent: כל תוכן הליבה של הלקוח בשדות data_analytics_agent, ‏ staging_context, ‏ published_context ו-last_published_context. הם כוללים שדות כמו system_instruction ו-example_queries.
  • Conversation משאבים: כל ההודעות והיסטוריית המצב.

הנתונים הבאים לא מוצפנים באמצעות מפתח ה-CMEK של הלקוח. במקום זאת, הנתונים האלה מוגנים באמצעות ההצפנה שמוגדרת כברירת מחדל ב-Google:

  • DataAgent מקורות מידע: שדות של מטא-נתונים, כולל name, ‏ display_name, ‏ description, ‏ labels, ‏ create_time, ‏ update_time, ‏ delete_time, ‏ purge_time ו-kms_key
  • Conversation resources: שדות של מטא-נתונים, כולל name, ‏ agents, ‏ labels, ‏ create_time, ‏ last_used_time ו-kms_key

מגבלות

יש מגבלות על CMEK ל-Conversational Analytics API:

  • צריך להגדיר את CMEK כשיוצרים את המשאב. אי אפשר להוסיף אותו למשאב קיים או לשנות אותו במשאב קיים.
  • המפתח של Cloud KMS ומשאב ה-API של ניתוח שיחות צריכים להיות באותו מיקום. אין תמיכה באזור global.
  • לגבי משאבים של Conversational Analytics API, ‏ CMEK נתמך באזור us-east4.
  • במשאבי Conversational Analytics API, ‏ CMEK נתמך רק במקורות נתונים של Looker.
  • אפשר להשתמש רק במפתח CMEK אחד לכל פרויקט לכל אזור עבור כל המשאבים Conversation באותו פרויקט ואזור.

לפני שמתחילים

לפני שמשתמשים ב-CMEK עם Conversational Analytics API, צריך לבצע את השלבים הבאים:

  1. מפעילים את ממשקי ה-API הנדרשים במסוף Google Cloud או ב-Google Cloud CLI.

    המסוף

    מפעילים את ממשקי ה-API הבאים במסוף Google Cloud בפרויקט Google Cloud .

    הפעלת Gemini Data Analytics API

    הפעלת Gemini for Google Cloud API

    הפעלת Cloud Key Management Service API

    gcloud

    מריצים את הפקודות הבאות של gcloud services enable ב-Google Cloud CLI כדי להפעיל את Gemini Data Analytics API, את Gemini for Google Cloud API ואת Cloud Key Management Service API, בהתאמה:

    gcloud services enable geminidataanalytics.googleapis.com --project=project_id
gcloud services enable cloudaicompanion.googleapis.com --project=project_id
gcloud services enable cloudkms.googleapis.com --project=project_id

    בפקודות לדוגמה של ה-CLI של gcloud שמופיעות למעלה, מחליפים את project_id במזהה הפרויקט שלכם ב- Google Cloud .

  2. מוסיפים את הפרויקט לרשימת ההיתרים.

    כדי להשתמש ב-CMEK עם Gemini Data Analytics, צריך להוסיף את פרויקט Google Cloud לרשימת ההיתרים. כדי לבקש להוסיף את הפרויקט לרשימת ההיתרים, שולחים את מזהה הפרויקט באמצעות הטופס להוספה לרשימת ההיתרים של GDA CMEK. הוספת הפרויקט לרשימת ההיתרים נמשכת בערך יום עד יומיים.

  3. יוצרים אוסף מפתחות ומפתח ב-Cloud KMS באותו מיקום שבו נמצאים משאבי Conversational Analytics API. מידע נוסף זמין במאמר יצירת מפתח.

  4. יוצרים את סוכני השירות בניהול Google, שנקראים גם חשבונות שירות לכל מוצר לכל פרויקט (P4SA), אם הם עדיין לא קיימים. סוכני השירות האלה נדרשים כדי לאפשר לשירותים שמשתתפים בהגנה על משאבי Conversational Analytics API באמצעות CMEK לגשת למפתח Cloud KMS שלכם.

    מריצים את הפקודות הבאות של gcloud כדי ליצור את סוכני השירות:

    ‫
    gcloud beta services identity create --service=geminidataanalytics.googleapis.com --project PROJECT_ID
gcloud beta services identity create --service=cloudaicompanion.googleapis.com --project PROJECT_ID
    מחליפים את PROJECT_ID במזהה הפרויקט ב- Google Cloud .

  5. צריך להעניק את התפקיד Cloud KMS CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter) ב-Identity and Access Management‏ (IAM) לשני סוכני השירות שיצרתם בשלב הקודם, כדי לאפשר לשירות Gemini Data Analytics להשתמש במפתח Cloud KMS שלכם להצפנה ולפענוח של הנתונים ב-Conversational Analytics API.

    נותנים הרשאה לסוכן השירות של Gemini Data Analytics:

    gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID

    נותנים הרשאה לסוכן השירות של Gemini for Google Cloud API:

    gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudaicompanion.iam.gserviceaccount.com \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID

    בדוגמאות הקוד הקודמות, מחליפים את ערכי הדוגמה באופן הבא:

    • ‫KEY_NAME: השם של מפתח Cloud KMS.
    • ‫KEY_LOCATION: האזור של אוסף המפתחות (לדוגמה, us-east4).
    • ‫KEY_RING_NAME: השם של אוסף המפתחות.
    • ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud שבו אתם יוצרים משאבי API.
    • ‫KMS_PROJECT_ID: מזהה הפרויקט שבו נוצר המפתח. אפשר להשתמש באותו פרויקט שבו יוצרים משאבי API.

הגנה על משאבים באמצעות CMEK

בקטע הזה נסביר איך להגן על משאב חדש מסוג DataAgent או Conversation באמצעות CMEK, על ידי שימוש ב-API בארכיטקטורת REST כדי לציין מפתח Cloud KMS בשדה kms_key במהלך יצירת המשאב.

אפשר להפעיל את CMEK רק כשיוצרים משאב מסוג DataAgent או Conversation.

מפתח CMEK צריך להיות באותו אזור שבו נמצא המשאב שהוא מגן עליו. מידע נוסף מופיע בקטע מגבלות.

הגנה על משאב DataAgent באמצעות CMEK

כדי להגן על משאב חדש של DataAgent באמצעות CMEK, מציינים מפתח Cloud KMS בשדה kms_key כשיוצרים את סוכן הנתונים.

Python SDK

בדוגמה הבאה אפשר לראות איך מציינים מפתח Cloud KMS כשיוצרים משאב DataAgent באמצעות Python SDK. דוגמה לבקשה מלאה מופיעה במאמר createיצירת סוכן נתונים באמצעות Python SDK.

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Region of your key ring

if key_project == "":
  key_project = billing_project

kms_key_data_agent = f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

data_agent = geminidataanalytics.DataAgent()
data_agent.data_analytics_agent.published_context = published_context
data_agent.kms_key = kms_key_data_agent

בדוגמה הקודמת, מחליפים את הערכים באופן הבא:

  • ‫BILLING_PROJECT_ID: מזהה הפרויקט לחיוב.
  • ‫KEY_RING_NAME: השם של אוסף המפתחות ב-Cloud KMS.
  • ‫KEY_NAME: השם של מפתח Cloud KMS.
  • ‫KMS_PROJECT_ID: מזהה הפרויקט שבו נוצר המפתח. אם לא מציינים ערך, המערכת משתמשת ב-billing_project.
  • ‫LOCATION: האזור של אוסף המפתחות.

HTTP

בדוגמה הבאה מוצג אופן ההגדרה של מפתח Cloud KMS בגוף הבקשה כשיוצרים משאב DataAgent באמצעות HTTP ו-Python. דוגמה לבקשת create מלאה מופיעה במאמר איך יוצרים סוכן נתונים באמצעות HTTP ו-Python.

data_agent_payload = {
      "name": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
      "description": "This is the description of data_agent_1.",
      # If using CMEK, include the kms_key field.
      "kms_key": f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}",
      "data_analytics_agent": {
          "published_context": {
              "datasource_references": looker_data_source,
              "system_instruction": system_instruction,
          }
      }
  }

בדוגמה הקודמת, מחליפים את הערכים באופן הבא:

  • ‫KMS_PROJECT_ID: מזהה הפרויקט שבו נוצר המפתח.
  • ‫LOCATION: האזור של אוסף המפתחות.
  • ‫KEY_RING_NAME: השם של אוסף המפתחות ב-Cloud KMS.
  • ‫KEY_NAME: השם של מפתח Cloud KMS.

הגנה על משאב Conversation באמצעות CMEK

כדי להגן על משאב חדש של Conversation באמצעות CMEK, מציינים מפתח Cloud KMS בשדה kms_key כשיוצרים את השיחה.

Python SDK

בדוגמה הבאה אפשר לראות איך מציינים מפתח Cloud KMS כשיוצרים משאב Conversation באמצעות Python SDK. דוגמה לבקשה מלאה מופיעה במאמר createיצירת סוכן נתונים באמצעות Python SDK.

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Region of your key ring

if key_project == "":
  key_project = billing_project

kms_key_conversation = f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

conversation = geminidataanalytics.Conversation()
conversation.agents = [f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"]
conversation.kms_key = kms_key_conversation

בדוגמה הקודמת, מחליפים את הערכים באופן הבא:

  • ‫BILLING_PROJECT_ID: מזהה הפרויקט לחיוב.
  • ‫KEY_RING_NAME: השם של אוסף המפתחות ב-Cloud KMS.
  • ‫KEY_NAME: השם של מפתח Cloud KMS.
  • ‫KMS_PROJECT_ID: מזהה הפרויקט שבו נוצר המפתח. אם לא מציינים ערך, המערכת משתמשת ב-billing_project.
  • ‫LOCATION: האזור של אוסף המפתחות.

HTTP

בדוגמה הבאה מוצג אופן ההגדרה של מפתח Cloud KMS בגוף הבקשה כשיוצרים משאב Conversation באמצעות HTTP ו-Python. דוגמה לבקשת create מלאה מופיעה במאמר איך יוצרים סוכן נתונים באמצעות HTTP ו-Python.

conversation_payload = {
    "agents": [
        f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
    ],
    "name": f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}",
    # If using CMEK, include the kms_key field.
    "kms_key": f"projects/{key_project}/locations/{location}/keyRings/{key_ring_name}/cryptoKeys/{key_name}"
}

בדוגמה הקודמת, מחליפים את הערכים באופן הבא:

  • ‫KMS_PROJECT_ID: מזהה הפרויקט שבו נוצר המפתח.
  • ‫LOCATION: האזור של אוסף המפתחות.
  • ‫KEY_RING_NAME: השם של אוסף המפתחות ב-Cloud KMS.
  • ‫KEY_NAME: השם של מפתח Cloud KMS.

פתרון בעיות

בקטע הזה מפורטות בעיות נפוצות ושיקולים חשובים כשמשתמשים ב-CMEK עם Conversational Analytics API.

שינויים מרכזיים במצב

אם גרסת מפתח של Cloud KMS שמגנה על משאב של Conversational Analytics API הופכת ללא זמינה, לא תהיה לכם יותר גישה לנתונים שמוצפנים על ידי המפתח הזה. אם תנסו לגשת לנתונים מוגנים כשהמפתח לא זמין, למשל על ידי קריאת ההקשר של משאב DataAgent או גישה להיסטוריה של Conversation, הבקשה תיכשל. השגיאה שמוחזרת תלויה בסיבה לכך שהמפתח לא זמין:

  • אם גרסת המפתח מושבתת או מושמדת, הפעולה בדרך כלל נכשלת עם שגיאה FAILED_PRECONDITION.
  • אם תבוטל הרשאת התפקיד cloudkms.cryptoKeyEncrypterDecrypter ב-IAM לסוכן השירות gcp-sa-geminidataanalytics או gcp-sa-cloudaicompanion, הפעולה בדרך כלל תיכשל עם השגיאה PERMISSION_DENIED או NOT_FOUND.

גם כשהמפתח לא זמין, עדיין אפשר לבצע פעולות שלא דורשות פענוח של התוכן, כמו מחיקה של משאב DataAgent או Conversation.

כדי לשחזר את הגישה לנתונים מוצפנים, צריך להפעיל מחדש את המפתח ולוודא שלסוכני השירות יש את הרשאות ה-IAM הנדרשות, כפי שמתואר בקטע לפני שמתחילים.

מכסות Cloud KMS ו-Conversational Analytics API

כשמשתמשים ב-CMEK ב-Conversational Analytics API, הפרויקטים יכולים לנצל את מכסות הבקשות הקריפטוגרפיות של Cloud KMS. לדוגמה, כדי לקרוא משאב DataAgent או לגשת להיסטוריה של Conversation שמוגנים באמצעות CMEK, צריך ש-Cloud KMS יפענח את הנתונים.

פעולות הצפנה ופענוח באמצעות מפתחות CMEK משפיעות על המכסות של Cloud KMS באופן הבא:

  • כשמשתמשים במפתחות CMEK של תוכנה שנוצרו ב-Cloud KMS, לא נצרכת מכסת Cloud KMS.
  • מפתחות CMEK בחומרה – לפעמים נקראים מפתחות Cloud HSM – פעולות ההצפנה והפענוח נספרות במסגרת המכסות של Cloud HSM בפרויקט שמכיל את המפתח.
  • במקרה של מפתחות CMEK חיצוניים – שלפעמים נקראים מפתחות Cloud EKM – פעולות ההצפנה והפענוח נספרות במכסות של Cloud EKM בפרויקט שמכיל את המפתח.

מידע נוסף מופיע במאמר מכסות ב-Cloud KMS.

המאמרים הבאים