מפתחות הצפנה בניהול הלקוח (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. ‫Conversational Analytics API הוא מוצר בשירות Gemini Data Analytics‏ (geminidataanalytics.googleapis.com).

מפתחות הצפנה בניהול הלקוח (CMEK) למשאבים של Conversational Analytics API

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

אפשר להשתמש ב-CMEK ל-Conversational Analytics API רק במיקומים אזוריים ובמספר אזורים, ולא במיקום global. כדי לראות את המיקומים שכל מקור נתונים תומך בהם, עיינו בקטע מיקומי נתונים נתמכים.

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

מפתחות CMEK ל-Conversational Analytics API מגינים על הנתונים הבאים במצב מנוחה:

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

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

  • במשאבי DataAgent, ההצפנה שמוגדרת כברירת מחדל ב-Google מגינה על שדות של מטא-נתונים כמו name,‏ display_name,‏ description,‏ labels,‏ create_time,‏ update_time,‏ delete_time,‏ purge_time ו-kms_key.
  • במשאבי Conversation, ההצפנה שמוגדרת כברירת מחדל ב-Google מגינה על שדות של מטא-נתונים כמו name,‏ agents,‏ labels,‏ create_time,‏ last_used_time ו-kms_key.

מגבלות

אלה המגבלות של CMEK ב-Conversational Analytics API:

  • צריך להגדיר את CMEK כשיוצרים את המשאב. אי אפשר להוסיף או לשנות אותו במשאב קיים.
  • אין תמיכה במדיניות ארגונית של CMEK.
  • המפתח של Cloud KMS והמשאב של Conversational Analytics API צריכים להיות באותו מיקום.
  • אין תמיכה באזור global.
  • אפשר להשתמש רק במפתח 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

    ב-Google Cloud CLI, מריצים את הפקודות הבאות של gcloud services enable כדי להפעיל את 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. יוצרים אוסף מפתחות ומפתח של Cloud KMS באותו מיקום שבו נמצאים המשאבים של Conversational Analytics API. מידע נוסף זמין במאמר יצירת מפתח.

  3. יוצרים את סוכני השירות שמנוהלים על ידי 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 .

  4. מקצים את התפקיד Cloud KMS CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter) בממשק לניהול זהויות והרשאות גישה (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. \
  --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. \
  --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.
  • אם תפקיד ה-IAM‏ cloudkms.cryptoKeyEncrypterDecrypter בוטל מסוכן השירות 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 EKM), פעולות ההצפנה והפענוח נספרות במסגרת המכסות של Cloud EKM בפרויקט שמכיל את המפתח.

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

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