קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
במדריך הזה מוסבר איך הצפנה ופענוח פועלים באמצעות Google Workspace Client-side Encryption API.
צריך להוסיף לרשימת ההיתרים את כל שירותי ספק הזהויות (IdP) שמשמשים משתמשים שמשתפים קבצים מוצפנים. בדרך כלל אפשר למצוא את הפרטים הנדרשים של ספק הזהויות בקובץ ה-.well-known שזמין לציבור. אם לא, צריך לפנות לאדמין של Google Workspace בארגון כדי לקבל את הפרטים של ספק הזהויות.
הצפנת נתונים
כשמשתמש ב-Google Workspace מבקש לשמור או לאחסן נתונים מוצפנים בצד הלקוח (CSE), Google Workspace שולחת בקשת wrap להצפנה לכתובת ה-URL של נקודת הקצה של שירות רשימת בקרת הגישה למפתחות (KACLS). בנוסף לבדיקות אבטחה אופציונליות, כמו בדיקות היקפיות ובדיקות שמבוססות על טענות JWT, מערכת KACLS צריכה לבצע את השלבים הבאים:
כדי לוודא שאסימוני ההרשאה והאימות הם של אותו משתמש, צריך לבצע התאמה לא תלוית-רישיות לטענות לגבי כתובת האימייל.
אם אסימון האימות מכיל את טענת google_email האופציונלית, צריך להשוות אותה לטענת האימייל באסימון ההרשאה באמצעות גישה לא תלוית-רישיות. אל תשתמשו בתביעת הבעלות על כתובת האימייל בטוקן האימות לצורך ההשוואה הזו.
בתרחישים שבהם אסימון האימות לא כולל את טענת google_email האופציונלית, צריך להשוות בין טענת האימייל באסימון האימות לבין טענת האימייל באסימון ההרשאה, באמצעות שיטה שלא מבחינה בין אותיות רישיות לאותיות קטנות.
בתרחישים שבהם Google מנפיקה אסימון הרשאה לאימייל שלא משויך לחשבון Google, email_typeהתביעה חייבת להיות נוכחת. המידע הזה הוא חלק חשוב בתכונת הגישה לאורחים, והוא מספק ל-KACLS מידע חשוב כדי לאכוף אמצעי אבטחה נוספים על משתמשים חיצוניים.
דוגמאות לשימושים של KACLS במידע הזה:
להטיל דרישות נוספות בנוגע לרישום ביומן.
כדי להגביל את מנפיק טוקן האימות ל-IdP ייעודי לאורחים.
כדי לדרוש הצהרות נוספות בטוקן האימות.
אם לקוח לא הגדיר גישת אורח, יכול להיות שכל הבקשות שבהן email_type מוגדר כ-google-visitor או כ-customer-idp יידחו. צריך להמשיך לאשר בקשות עם email_type של google או עם email_type שלא הוגדר.
אם אסימון האימות מכיל את הטענה האופציונלית delegated_to, הוא צריך להכיל גם את הטענה resource_name, ויש להשוות בין שתי הטענות האלה לבין הטענות delegated_to ו-resource_name באסימון ההרשאה. צריך להשוות את ההצהרות delegated_to בלי להתחשב באותיות רישיות, והערך resource_name באסימונים צריך להיות זהה לערך resource_name של הפעולה.
בודקים שהערך של התביעה role באסימון ההרשאה הוא writer או upgrader.
בודקים שהצהרת kacls_url באסימון ההרשאה תואמת לכתובת ה-URL הנוכחית של KACLS. הבדיקה הזו מאפשרת לזהות שרתים פוטנציאליים של מתקפת 'אדם באמצע' שהוגדרו על ידי משתמשים פנימיים או אדמינים של דומיין סורר.
ביצוע בדיקה היקפית באמצעות טענות אימות והרשאה.
הצפנה של החלקים הבאים באמצעות אלגוריתם הצפנה מאומת:
רישום הפעולה ביומן, כולל המשתמש שיזם אותה, resource_name והסיבה שהועברה בבקשה.
החזרת אובייקט בינארי אטום לאחסון על ידי Google Workspace לצד האובייקט המוצפן, ושליחתו כמו שהוא בכל פעולת ביטול עטיפה של מפתח בהמשך. או להציג תשובה עם שגיאה מובנית.
האובייקט הבינארי צריך להכיל את העותק היחיד של ה-DEK המוצפן. אפשר לאחסן בו נתונים ספציפיים להטמעה.
פענוח נתונים
כשמשתמש ב-Google Workspace מבקש לפתוח נתונים מוצפנים בצד הלקוח (CSE), Google Workspace שולחת בקשת unwrap לכתובת ה-URL של נקודת הקצה של KACLS לצורך פענוח. בנוסף לבדיקות אבטחה אופציונליות, כמו בדיקות היקפיות ובדיקות שמבוססות על טענות JWT, מערכת KACLS חייבת לבצע את השלבים הבאים:
כדי לוודא שאסימוני ההרשאה והאימות הם של אותו משתמש, צריך לבצע התאמה לא תלוית-רישיות לטענות לגבי כתובת האימייל.
אם אסימון האימות מכיל את טענת google_email האופציונלית, צריך להשוות אותה לטענת האימייל באסימון ההרשאה באמצעות גישה לא תלוית-רישיות. אל תשתמשו בתביעת הבעלות על כתובת האימייל בטוקן האימות לצורך ההשוואה הזו.
בתרחישים שבהם אסימון האימות לא כולל את טענת google_email האופציונלית, צריך להשוות בין טענת האימייל באסימון האימות לבין טענת האימייל באסימון ההרשאה, באמצעות שיטה שלא מבחינה בין אותיות רישיות לאותיות קטנות.
בתרחישים שבהם Google מנפיקה אסימון הרשאה לאימייל שלא משויך לחשבון Google, email_typeהתביעה חייבת להיות נוכחת. המידע הזה הוא חלק חשוב בתכונת הגישה לאורחים, והוא מספק ל-KACLS מידע חשוב כדי לאכוף אמצעי אבטחה נוספים על משתמשים חיצוניים.
דוגמאות לשימושים של KACLS במידע הזה:
להטיל דרישות נוספות בנוגע לרישום ביומן.
כדי להגביל את מנפיק טוקן האימות ל-IdP ייעודי לאורחים.
כדי לדרוש הצהרות נוספות בטוקן האימות.
אם לקוח לא הגדיר גישת אורח, יכול להיות שכל הבקשות שבהן email_type מוגדר כ-google-visitor או כ-customer-idp יידחו. צריך להמשיך לאשר בקשות עם email_type של google או עם email_type שלא הוגדר.
אם אסימון האימות מכיל את הטענה האופציונלית delegated_to, הוא צריך להכיל גם את הטענה resource_name, ויש להשוות בין שתי הטענות האלה לבין הטענות delegated_to ו-resource_name באסימון ההרשאה. צריך להשוות את ההצהרות delegated_to בלי להתחשב באותיות רישיות, והערך resource_name באסימונים צריך להיות זהה לערך resource_name של הפעולה.
בודקים שהערך של התביעה role באסימון ההרשאה הוא reader או writer.
בודקים שהצהרת kacls_url באסימון ההרשאה תואמת לכתובת ה-URL הנוכחית של KACLS. כך אפשר לזהות שרתי פוטנציאליים של מתקפת 'אדם באמצע' שהוגדרו על ידי משתמשים פנימיים או מנהלי דומיין לא מורשים.
מפענחים את החלקים הבאים באמצעות אלגוריתם הצפנה מאומת:
[[["התוכן קל להבנה","easyToUnderstand","thumb-up"],["התוכן עזר לי לפתור בעיה","solvedMyProblem","thumb-up"],["סיבה אחרת","otherUp","thumb-up"]],[["חסרים לי מידע או פרטים","missingTheInformationINeed","thumb-down"],["התוכן מורכב מדי או עם יותר מדי שלבים","tooComplicatedTooManySteps","thumb-down"],["התוכן לא עדכני","outOfDate","thumb-down"],["בעיה בתרגום","translationIssue","thumb-down"],["בעיה בדוגמאות/בקוד","samplesCodeIssue","thumb-down"],["סיבה אחרת","otherDown","thumb-down"]],["עדכון אחרון: 2025-08-04 (שעון UTC)."],[[["\u003cp\u003eThis guide outlines the process of encrypting and decrypting data using the Google Workspace Client-side Encryption API, leveraging a Key Access and Control List Service (KACLS).\u003c/p\u003e\n"],["\u003cp\u003eDuring encryption, the KACLS validates the user, encrypts the data encryption key (DEK) and other sensitive data, logs the operation, and returns an opaque binary object containing the encrypted DEK to Google Workspace for storage.\u003c/p\u003e\n"],["\u003cp\u003eFor decryption, the KACLS validates the user, decrypts the DEK and associated data, verifies the resource name, performs a perimeter check, logs the operation, and returns the unwrapped DEK to Google Workspace.\u003c/p\u003e\n"],["\u003cp\u003eBefore sharing encrypted files, ensure to allowlist any Identity Provider (IdP) services used by the intended recipients, which typically involves obtaining IdP details from their publicly available .well-known file or contacting their Google Workspace administrator.\u003c/p\u003e\n"]]],["When users encrypt data, the KACLS must validate user authentication and authorization tokens, ensuring matching email claims and specific role and URL claims. It encrypts the Data Encryption Key (DEK), `resource_name`, `perimeter_id`, and other sensitive data, logs the operation, and returns an encrypted object. For decryption, the process mirrors encryption, validating tokens, decrypting the data, verifying `resource_name`, performing perimeter checks, logging, and returning the DEK. Guest access requires extra checks. Identity provider services must be allowlisted.\n"],null,["# Encrypt & decrypt data\n\nThis guide describes how encryption and decryption works using the Google Workspace Client-side Encryption API.\n\nYou must allowlist any Identity Provider (IdP) services used by users\nsharing encrypted files. You can usually find the required IdP details in their\npublicly-available .well-known file; otherwise, contact the organization's\nGoogle Workspace administrator for their IdP details.\n\nEncrypt data\n------------\n\nWhen a Google Workspace user requests to save or store client-side encrypted\n(CSE) data, Google Workspace sends a [`wrap`](/workspace/cse/reference/wrap)\nrequest to your Key Access Control List Service (KACLS) endpoint URL for encryption.\nIn addition to optional security checks, such as perimeter and JWT claim-based checks,\nyour KACLS must perform the following steps:\n\n1. Validate the requesting user.\n\n - Validate both the [authentication token](/workspace/cse/reference/authentication-tokens) and [authorization token](/workspace/cse/reference/authorization-tokens).\n - Check that authorization and authentication tokens are for the same user by doing a case-insensitive match on the email claims.\n - When the authentication token contains the optional `google_email` claim, it must be compared against the email claim in the authorization token using a case-insensitive approach. Don't use the email claim within the authentication token for this comparison.\n - In scenarios where the authentication token lacks the optional `google_email` claim, the email claim within the authentication token should be compared with the email claim in the authorization token, using a case-insensitive method.\n - In scenarios where Google issues an authorization token for an email not associated with a Google Account, the `email_type` claim must be present. This forms a crucial part of the Guest Access feature, providing valuable information for KACLS to enforce additional security measures on external users.\n - Some examples of how a KACLS can use this information include:\n - To impose additional logging requirements.\n - To restrict the authentication token issuer to a dedicated Guest IdP.\n - To require additional claims on the authentication token.\n - If a customer has not configured Guest Access, then all requests where `email_type` is set to `google-visitor` or `customer-idp` can be rejected. Requests with an `email_type` of `google` or with an unset `email_type` should continue to be accepted.\n - When the authentication token contains the optional `delegated_to` claim, it must also contain the `resource_name` claim, and these two claims must be compared against the `delegated_to` and `resource_name` claims in the authorization token. The `delegated_to` claims should be compared using a case-insensitive approach, and the `resource_name` in the tokens should match the `resource_name` of the operation.\n - Check that the `role` claim in the authorization token is `writer` or `upgrader`.\n - Check that the `kacls_url` claim in the authorization token matches the current KACLS URL. This check allows detection of potential man-in-the-middle servers configured by insiders or rogue domain administrators.\n - Perform a perimeter check using both authentication and authorization claims.\n2. Encrypt the following parts using an authenticated encryption algorithm:\n\n - Data Encryption Key (DEK)\n - The `resource_name` and `perimeter_id` values from the authorization token\n - Any additional sensitive data\n3. Log the operation, including the user originating it, the `resource_name` and\n the reason passed in the request.\n\n4. Return an opaque binary object to be stored by Google Workspace alongside\n the encrypted object and sent as-is in any subsequent key unwrapping\n operation. Or, serve a [structured error reply](/workspace/cse/reference/structured-errors).\n\n - The binary object should contain the only copy of the encrypted DEK, implementation specific data can be stored in it.\n\n| **Note:** Do not store the DEK in your KACLS system. Instead, encrypt it and return it in the `wrapped_key` object to prevent discrepancies for the lifetime of the file. Google doesn't send deletion requests to the KACLS when objects are deleted.\n\nDecrypt data\n------------\n\nWhen a Google Workspace user requests to open client-side encrypted (CSE) data,\nGoogle Workspace sends an [`unwrap`](/workspace/cse/reference/unwrap) request\nto your KACLS endpoint URL for decryption. In addition to optional security\nchecks, such as perimeter and JWT claim-based checks, your KACLS must perform\nthe following steps:\n\n1. Validate the requesting user.\n\n - Validate both the [authentication token](/workspace/cse/reference/authentication-tokens) and [authorization token](/workspace/cse/reference/authorization-tokens).\n - Check that authorization and authentication tokens are for the same user by doing a case-insensitive match on the email claims.\n - When the authentication token contains the optional `google_email` claim, it must be compared against the email claim in the authorization token using a case-insensitive approach. Don't use the email claim within the authentication token for this comparison.\n - In scenarios where the authentication token lacks the optional `google_email` claim, the email claim within the authentication token should be compared with the email claim in the authorization token, using a case-insensitive method.\n - In scenarios where Google issues an authorization token for an email not associated with a Google Account, the `email_type` claim must be present. This forms a crucial part of the Guest Access feature, providing valuable information for KACLS to enforce additional security measures on external users.\n - Some examples of how a KACLS can use this information include:\n - To impose additional logging requirements.\n - To restrict the authentication token issuer to a dedicated Guest IdP.\n - To require additional claims on the authentication token.\n - If a customer has not configured Guest Access, then all requests where `email_type` is set to `google-visitor` or `customer-idp` can be rejected. Requests with an `email_type` of `google` or with an unset `email_type` should continue to be accepted.\n - When the authentication token contains the optional `delegated_to` claim, it must also contain the `resource_name` claim, and these two claims must be compared against the `delegated_to` and `resource_name` claims in the authorization token. The `delegated_to` claims should be compared using a case-insensitive approach, and the `resource_name` in the tokens should match the `resource_name` of the operation.\n - Check that the `role` claim in the authorization token is `reader` or `writer`.\n - Check that the `kacls_url` claim in the authorization token matches the current KACLS URL. This allows detection of potential man-in-the-middle servers configured by insiders or rogue domain administrators.\n2. Decrypt the following parts using an authenticated encryption algorithm:\n\n - Data Encryption Key (DEK)\n - The `resource_name` and `perimeter_id` values from the authorization token\n - Any additional sensitive data\n3. Check that the `resource_name` in the authorization token and decrypted blob\n match.\n\n4. Perform a perimeter check using both authentication and authorization claims.\n\n5. Log the operation, including the user originating it, the `resource_name` and\n the reason passed in the request.\n\n6. Return the unwrapped DEK or a [structured error reply](/workspace/cse/reference/structured-errors).\n\n| **Note:** To decrypt [Google Takeout](https://support.google.com/a/answer/100458) requests, see [`takeout_unwrap`](/workspace/cse/reference/takeout_unwrap)."]]
