تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يوضّح هذا الدليل طريقة عمل التشفير وفك التشفير باستخدام واجهة برمجة التطبيقات لميزة "التشفير من جهة العميل" في Google Workspace.
يجب إضافة أي خدمات موفِّر هوية (IdP) يستخدمها المستخدمون الذين يشاركون الملفات المشفَّرة إلى القائمة المسموح بها. يمكنك عادةً العثور على تفاصيل موفِّر الهوية المطلوبة في ملف .well-known المتاح للجميع، وإلا يمكنك التواصل مع مشرف Google Workspace في المؤسسة للحصول على تفاصيل موفِّر الهوية.
تشفير البيانات
عندما يطلب مستخدم Google Workspace حفظ بيانات مشفَّرة من جهة العميل (CSE) أو تخزينها، يرسل Google Workspace طلب wrap إلى عنوان URL لنقطة نهاية خدمة إدارة مفاتيح التشفير (KACLS) من أجل التشفير.
بالإضافة إلى عمليات فحص الأمان الاختيارية، مثل عمليات الفحص المستندة إلى المحيط الخارجي ومطالبات JWT، يجب أن تنفّذ خدمة KACLS الخطوات التالية:
تأكَّد من أنّ رموز التفويض والمصادقة المميزة تخص المستخدم نفسه من خلال إجراء مطابقة غير حساسة لحالة الأحرف في مطالبات البريد الإلكتروني.
عندما يحتوي رمز المصادقة المميز على مطالبة google_email الاختيارية،
يجب مقارنتها بمطالبة البريد الإلكتروني في رمز الموافقة المميز
باستخدام طريقة غير حساسة لحالة الأحرف. لا تستخدِم مطالبة البريد الإلكتروني ضمن رمز المصادقة المميز لإجراء هذه المقارنة.
في الحالات التي لا يتضمّن فيها رمز المصادقة المميز مطالبة google_email الاختيارية، يجب مقارنة مطالبة البريد الإلكتروني في رمز المصادقة المميز بمطالبة البريد الإلكتروني في رمز التفويض المميز، باستخدام طريقة غير حساسة لحالة الأحرف.
في الحالات التي تصدر فيها Google رمزًا مميزًا للتفويض لعنوان بريد إلكتروني غير مرتبط بحساب على Google، يجب أن يكون الادعاء email_type موجودًا.
يشكّل ذلك جزءًا مهمًا من ميزة "وصول الضيوف"، إذ يوفّر معلومات قيّمة لقوائم التحكّم بالوصول إلى المفاتيح (KACL) من أجل فرض تدابير أمان إضافية على المستخدمين الخارجيين.
في ما يلي بعض الأمثلة على كيفية استخدام نظام KACLS لهذه المعلومات:
لفرض متطلبات تسجيل إضافية
لتقييد جهة إصدار رمز المصادقة المميز بموفِّر هوية مخصّص لجلسات الضيوف
لفرض مطالبات إضافية على رمز المصادقة المميز
إذا لم يضبط العميل إعدادات "وصول الضيوف"، يمكن رفض جميع الطلبات التي تم ضبط 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 بجانب العنصر المشفّر وسيتم إرساله كما هو في أي عملية لاحقة لفك تشفير المفتاح. أو يمكنك عرض ردّ منظَّم يفيد بحدوث خطأ.
يجب أن يحتوي العنصر الثنائي على النسخة الوحيدة من مفتاح تشفير البيانات المشفَّر، ويمكن تخزين البيانات الخاصة بالتنفيذ فيه.
فك تشفير البيانات
عندما يطلب مستخدم Google Workspace فتح بيانات مشفَّرة من جهة العميل (CSE)، يرسل Google Workspace طلب unwrap إلى عنوان URL لنقطة نهاية KACLS لفك التشفير. بالإضافة إلى عمليات فحص الأمان الاختيارية، مثل عمليات الفحص المستندة إلى المحيط الخارجي ومطالبات JWT، يجب أن تنفّذ خدمة KACLS الخطوات التالية:
تأكَّد من أنّ رموز التفويض والمصادقة المميزة تخص المستخدم نفسه من خلال إجراء مطابقة غير حساسة لحالة الأحرف في مطالبات البريد الإلكتروني.
عندما يحتوي رمز المصادقة المميز على مطالبة google_email الاختيارية،
يجب مقارنتها بمطالبة البريد الإلكتروني في رمز الموافقة المميز
باستخدام طريقة غير حساسة لحالة الأحرف. لا تستخدِم مطالبة البريد الإلكتروني ضمن رمز المصادقة المميز لإجراء هذه المقارنة.
في الحالات التي لا يتضمّن فيها رمز المصادقة المميز مطالبة google_email الاختيارية، يجب مقارنة مطالبة البريد الإلكتروني في رمز المصادقة المميز بمطالبة البريد الإلكتروني في رمز التفويض المميز، باستخدام طريقة غير حساسة لحالة الأحرف.
في الحالات التي تصدر فيها Google رمزًا مميزًا للتفويض لعنوان بريد إلكتروني غير مرتبط بحساب على Google، يجب أن يكون الادعاء email_type موجودًا.
يشكّل ذلك جزءًا مهمًا من ميزة "وصول الضيوف"، إذ يوفّر معلومات قيّمة لقوائم التحكّم بالوصول إلى المفاتيح (KACL) من أجل فرض تدابير أمان إضافية على المستخدمين الخارجيين.
في ما يلي بعض الأمثلة على كيفية استخدام نظام KACLS لهذه المعلومات:
لفرض متطلبات تسجيل إضافية
لتقييد جهة إصدار رمز المصادقة المميز بموفِّر هوية مخصّص لجلسات الضيوف
لفرض مطالبات إضافية على رمز المصادقة المميز
إذا لم يضبط العميل إعدادات "وصول الضيوف"، يمكن رفض جميع الطلبات التي تم ضبط 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)."]]
