Koleksiyonlar ile düzeninizi koruyun
İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.
Bu kılavuzda, Google Workspace Client-side Encryption API kullanılarak şifreleme ve şifre çözme işlemlerinin nasıl çalıştığı açıklanmaktadır.
Şifrelenmiş dosyaları paylaşan kullanıcılar tarafından kullanılan tüm kimlik sağlayıcı (IdP) hizmetlerini izin verilenler listesine eklemeniz gerekir. Gerekli IdP ayrıntılarını genellikle kuruluşun herkese açık .well-known dosyasında bulabilirsiniz. Aksi takdirde, IdP ayrıntılarını öğrenmek için kuruluşun Google Workspace yöneticisiyle iletişime geçin.
Verileri şifreleme
Bir Google Workspace kullanıcısı, istemci tarafı şifrelenmiş (İTŞ) verileri kaydetmek veya depolamak istediğinde Google Workspace, şifreleme için Anahtar Erişim Kontrol Listesi Hizmeti (KACLS) uç nokta URL'nize bir wrap isteği gönderir.
Çevre ve JWT talebine dayalı kontroller gibi isteğe bağlı güvenlik kontrollerine ek olarak KACLS'niz aşağıdaki adımları uygulamalıdır:
E-posta taleplerinde büyük/küçük harfe duyarsız bir eşleşme yaparak yetkilendirme ve kimlik doğrulama jetonlarının aynı kullanıcıya ait olduğunu kontrol edin.
Kimlik doğrulama jetonu isteğe bağlı google_email talebini içerdiğinde, büyük/küçük harfe duyarsız bir yaklaşımla yetkilendirme jetonundaki e-posta talebiyle karşılaştırılması gerekir. Bu karşılaştırma için kimlik doğrulama jetonundaki e-posta talebini kullanmayın.
Kimlik doğrulama jetonunda isteğe bağlı google_email talebinin olmadığı senaryolarda, kimlik doğrulama jetonundaki e-posta talebi, büyük/küçük harfe duyarsız bir yöntem kullanılarak yetkilendirme jetonundaki e-posta talebiyle karşılaştırılmalıdır.
Google'ın, bir Google Hesabı ile ilişkilendirilmemiş bir e-posta için yetkilendirme jetonu verdiği senaryolarda email_type talebi bulunmalıdır.
Bu, konuk erişimi özelliğinin önemli bir parçasını oluşturur ve KACL'lerin harici kullanıcılara ek güvenlik önlemleri uygulaması için değerli bilgiler sağlar.
KACLS'nin bu bilgileri nasıl kullanabileceğine dair bazı örnekler:
Ek günlük kaydı koşulları uygulamak için.
Kimlik doğrulama jetonu yayıncısını özel bir misafir IdP'siyle kısıtlamak için kullanılır.
Kimlik doğrulama jetonunda ek taleplerde bulunmak için.
Bir müşteri Misafir Erişimini yapılandırmadıysa email_type değerinin google-visitor veya customer-idp olarak ayarlandığı tüm istekler reddedilebilir. email_type değeri google olan veya email_type değeri ayarlanmamış istekler kabul edilmeye devam etmelidir.
Kimlik doğrulama jetonu isteğe bağlı delegated_to talebini içerdiğinde resource_name talebini de içermesi gerekir ve bu iki talep, yetkilendirme jetonundaki delegated_to ve resource_name talepleriyle karşılaştırılmalıdır. delegated_to talepleri büyük/küçük harfe duyarsız bir yaklaşımla karşılaştırılmalı ve jetonlardaki resource_name, işlemin resource_name ile eşleşmelidir.
Yetkilendirme jetonundaki role talebinin writer veya upgrader olduğunu kontrol edin.
Yetkilendirme jetonundaki kacls_url talebinin, mevcut KACLS URL'siyle eşleştiğinden emin olun. Bu kontrol, kuruluş içinden kişiler veya kötü niyetli alan yöneticileri tarafından yapılandırılan olası araya girme saldırısı sunucularının tespit edilmesine olanak tanır.
Hem kimlik doğrulama hem de yetkilendirme taleplerini kullanarak bir çevre kontrolü gerçekleştirin.
Aşağıdaki bölümleri kimliği doğrulanmış bir şifreleme algoritması kullanarak şifreleyin:
Veri Şifreleme Anahtarı (DEK)
Yetkilendirme jetonundaki resource_name ve perimeter_id değerleri
Diğer hassas veriler
İşlemi, işlemi başlatan kullanıcı, resource_name ve istekte iletilen neden de dahil olmak üzere günlüğe kaydedin.
Şifrelenmiş nesneyle birlikte Google Workspace tarafından depolanacak ve sonraki anahtar sarmalama açma işlemlerinde olduğu gibi gönderilecek opak bir ikili nesne döndürür. Alternatif olarak, yapılandırılmış bir hata yanıtı da sunabilirsiniz.
İkili nesne, şifrelenmiş DEK'nin tek kopyasını içermelidir.
Uygulamaya özgü veriler burada depolanabilir.
Verilerin şifresini çözme
Bir Google Workspace kullanıcısı, istemci tarafı şifrelemeli (İTŞ) verileri açmayı istediğinde Google Workspace, şifre çözme işlemi için KACLS uç nokta URL'nize bir unwrap isteği gönderir. Çevre ve JWT talebine dayalı kontroller gibi isteğe bağlı güvenlik kontrollerine ek olarak, KACLS'niz aşağıdaki adımları uygulamalıdır:
E-posta taleplerinde büyük/küçük harfe duyarsız bir eşleşme yaparak yetkilendirme ve kimlik doğrulama jetonlarının aynı kullanıcıya ait olduğunu kontrol edin.
Kimlik doğrulama jetonu isteğe bağlı google_email talebini içerdiğinde, büyük/küçük harfe duyarsız bir yaklaşımla yetkilendirme jetonundaki e-posta talebiyle karşılaştırılması gerekir. Bu karşılaştırma için kimlik doğrulama jetonundaki e-posta talebini kullanmayın.
Kimlik doğrulama jetonunda isteğe bağlı google_email talebinin olmadığı senaryolarda, kimlik doğrulama jetonundaki e-posta talebi, büyük/küçük harfe duyarsız bir yöntem kullanılarak yetkilendirme jetonundaki e-posta talebiyle karşılaştırılmalıdır.
Google'ın, bir Google Hesabı ile ilişkilendirilmemiş bir e-posta için yetkilendirme jetonu verdiği senaryolarda email_type talebi bulunmalıdır.
Bu, konuk erişimi özelliğinin önemli bir parçasını oluşturur ve KACL'lerin harici kullanıcılara ek güvenlik önlemleri uygulaması için değerli bilgiler sağlar.
KACLS'nin bu bilgileri nasıl kullanabileceğine dair bazı örnekler:
Ek günlük kaydı koşulları uygulamak için.
Kimlik doğrulama jetonu yayıncısını özel bir misafir IdP'siyle kısıtlamak için kullanılır.
Kimlik doğrulama jetonunda ek taleplerde bulunmak için.
Bir müşteri Misafir Erişimini yapılandırmadıysa email_type değerinin google-visitor veya customer-idp olarak ayarlandığı tüm istekler reddedilebilir. email_type değeri google olan veya email_type değeri ayarlanmamış istekler kabul edilmeye devam etmelidir.
Kimlik doğrulama jetonu isteğe bağlı delegated_to talebini içerdiğinde resource_name talebini de içermesi gerekir ve bu iki talep, yetkilendirme jetonundaki delegated_to ve resource_name talepleriyle karşılaştırılmalıdır. delegated_to talepleri büyük/küçük harfe duyarsız bir yaklaşımla karşılaştırılmalı ve jetonlardaki resource_name, işlemin resource_name ile eşleşmelidir.
Yetkilendirme jetonundaki role talebinin reader veya writer olduğunu kontrol edin.
Yetkilendirme jetonundaki kacls_url talebinin, mevcut KACLS URL'siyle eşleştiğinden emin olun. Bu sayede, kuruluş içinden kişiler veya kötü niyetli alan yöneticileri tarafından yapılandırılan olası ortadaki adam sunucuları tespit edilebilir.
Aşağıdaki bölümleri kimliği doğrulanmış bir şifreleme algoritması kullanarak şifrelerini çözün:
Veri Şifreleme Anahtarı (DEK)
Yetkilendirme jetonundaki resource_name ve perimeter_id değerleri
[null,null,["Son güncelleme tarihi: 2025-08-29 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)."]]
