با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
این راهنما نحوه کارکرد رمزگذاری و رمزگشایی با استفاده از Google Workspace Client-side Encryption API را شرح می دهد.
شما باید هر گونه خدمات ارائه دهنده هویت (IdP) را که توسط کاربرانی که فایل های رمزگذاری شده را به اشتراک می گذارند استفاده می کنند، لیست کنید. معمولاً می‌توانید جزئیات IdP مورد نیاز را در فایل .well-known آن‌ها که در دسترس عموم است، بیابید. در غیر این صورت، برای اطلاع از جزئیات IdP با سرپرست Google Workspace سازمان تماس بگیرید.
داده ها را رمزگذاری کنید
وقتی کاربر Google Workspace درخواست ذخیره یا ذخیره داده‌های رمزگذاری‌شده (CSE) سمت سرویس گیرنده را می‌دهد، Google Workspace یک درخواست wrap برای رمزگذاری به URL نقطه پایانی سرویس فهرست کنترل دسترسی کلید (KACLS) ارسال می‌کند. علاوه بر بررسی‌های امنیتی اختیاری، مانند بررسی‌های مبتنی بر ادعای محیطی و JWT، KACLS شما باید مراحل زیر را انجام دهد:
با انجام تطبیق بدون حروف بزرگ و کوچک در ادعاهای ایمیل، بررسی کنید که نشانه‌های مجوز و احراز هویت برای یک کاربر باشد.
هنگامی که رمز احراز هویت حاوی ادعای اختیاری google_email است، باید با استفاده از رویکردی که به حروف بزرگ و کوچک حساس نیست، با ادعای ایمیل در کد مجوز مقایسه شود. برای این مقایسه از ادعای ایمیل در نشانه احراز هویت استفاده نکنید.
در سناریوهایی که نشانه احراز هویت فاقد ادعای اختیاری google_email است، ادعای ایمیل در کد احراز هویت باید با ادعای ایمیل در کد مجوز، با استفاده از روشی که به حروف کوچک و بزرگ حساس نیست، مقایسه شود.
در سناریوهایی که Google برای ایمیلی که با حساب Google مرتبط نیست، کد مجوز صادر می‌کند، ادعای email_type باید وجود داشته باشد. این بخش مهمی از ویژگی دسترسی مهمان را تشکیل می دهد و اطلاعات ارزشمندی را برای KACLS فراهم می کند تا اقدامات امنیتی بیشتری را بر روی کاربران خارجی اعمال کند.
چند نمونه از نحوه استفاده KACLS از این اطلاعات عبارتند از:
برای تحمیل الزامات اضافی برای ورود به سیستم.
برای محدود کردن صادرکننده رمز احراز هویت به یک Guest 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 مطابقت داشته باشد. این بررسی اجازه می دهد تا سرورهای بالقوه مرد میانی را که توسط خودی ها یا مدیران سرکش دامنه پیکربندی شده اند، شناسایی کند.
با استفاده از هر دو ادعای احراز هویت و مجوز، یک بررسی محیطی انجام دهید.
قسمت های زیر را با استفاده از یک الگوریتم رمزگذاری تایید شده رمزگذاری کنید:
کلید رمزگذاری داده ها (DEK)
مقادیر resource_name و perimeter_id از توکن مجوز
هر گونه داده حساس اضافی
عملیات را ثبت کنید، از جمله کاربر ایجاد کننده آن، 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 از این اطلاعات عبارتند از:
برای تحمیل الزامات اضافی برای ورود به سیستم.
برای محدود کردن صادرکننده رمز احراز هویت به یک Guest 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 مطابقت داشته باشد. این اجازه می دهد تا سرورهای بالقوه Man-in-the-Middle را که توسط خودی ها یا مدیران دامنه های سرکش پیکربندی شده اند شناسایی کنید.
قسمت های زیر را با استفاده از یک الگوریتم رمزگذاری تایید شده رمزگشایی کنید:
کلید رمزگذاری داده ها (DEK)
مقادیر resource_name و perimeter_id از توکن مجوز
هر گونه داده حساس اضافی
بررسی کنید که resource_name در نشانه مجوز و لکه رمزگشایی شده مطابقت داشته باشد.
با استفاده از هر دو ادعای احراز هویت و مجوز، یک بررسی محیطی انجام دهید.
عملیات را ثبت کنید، از جمله کاربر ایجاد کننده آن، resource_name و دلیل ارسال شده در درخواست.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[[["\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)."]]
