Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Este guia descreve como a criptografia e a descriptografia funcionam usando a API de criptografia do lado do cliente do Google Workspace.
É necessário permitir todos os serviços de provedor de identidade (IdP) usados pelos usuários
que compartilham arquivos criptografados. Geralmente, os detalhes necessários do IdP são encontrados no arquivo .well-known disponível publicamente. Caso contrário, entre em contato com o administrador do Google Workspace da organização para saber os detalhes do IdP.
Criptografar dados
Quando um usuário do Google Workspace solicita salvar ou armazenar dados criptografados no lado do cliente (CSE), o Google Workspace envia uma solicitação wrap
para o URL do endpoint do seu serviço de lista de controle de acesso à chave (KACLS) para criptografia.
Além das verificações de segurança opcionais, como as baseadas em perímetro e declarações JWT,
suas KACLS precisam realizar as seguintes etapas:
Verifique se os tokens de autorização e autenticação são do mesmo usuário
fazendo uma correspondência sem diferenciação de maiúsculas e minúsculas nas declarações de e-mail.
Quando o token de autenticação contém a declaração opcional google_email,
ela precisa ser comparada com a declaração de e-mail no token de autorização
usando uma abordagem sem diferenciação de maiúsculas e minúsculas. Não use a declaração de e-mail no token de autenticação para essa comparação.
Em cenários em que o token de autenticação não tem a declaração opcional google_email, a declaração de e-mail no token de autenticação deve ser comparada com a declaração de e-mail no token de autorização usando um método sem diferenciação de maiúsculas e minúsculas.
Em cenários em que o Google emite um token de autorização para um e-mail não associado a uma Conta do Google, a declaração email_type precisa estar presente.
Isso forma uma parte crucial do recurso de acesso de visitante, fornecendo informações valiosas para que as KACLs apliquem medidas de segurança adicionais a usuários externos.
Alguns exemplos de como um KACLS pode usar essas informações:
Para impor requisitos de geração de registros adicionais.
Para restringir o emissor de token de autenticação a um IdP convidado dedicado.
Para exigir declarações adicionais no token de autenticação.
Se um cliente não tiver configurado o acesso de convidado, todas as solicitações em que email_type estiver definido como google-visitor ou customer-idp poderão ser rejeitadas. As solicitações com um email_type de google ou com um email_type não definido ainda serão aceitas.
Quando o token de autenticação contém a declaração opcional delegated_to, ele também precisa conter a declaração resource_name, e essas duas declarações precisam ser comparadas com as declarações delegated_to e resource_name no token de autorização. As declarações delegated_to precisam ser comparadas usando uma abordagem independente de maiúsculas e minúsculas, e o resource_name nos tokens precisa corresponder ao resource_name da operação.
Verifique se a declaração role no token de autorização é writer ou
upgrader.
Verifique se a declaração kacls_url no token de autorização corresponde ao
URL atual do KACLS. Essa verificação permite detectar possíveis servidores man-in-the-middle configurados por pessoas de dentro da empresa ou administradores de domínio desonestos.
Faça uma verificação de perímetro usando declarações de autenticação e autorização.
Criptografe as seguintes partes usando um algoritmo de criptografia autenticada:
Chave de criptografia de dados (DEK)
Os valores resource_name e perimeter_id do token de autorização
Outros dados sensíveis
Registre a operação, incluindo o usuário que a originou, o resource_name e o motivo transmitido na solicitação.
Retorna um objeto binário opaco para ser armazenado pelo Google Workspace junto com
o objeto criptografado e enviado como está em qualquer operação de desencapsulamento
de chave subsequente. Ou veicule uma resposta de erro estruturada.
O objeto binário precisa conter a única cópia da DEK criptografada, e dados específicos da implementação podem ser armazenados nele.
Descriptografar dados
Quando um usuário do Google Workspace pede para abrir dados criptografados do lado do cliente (CSE),
o Google Workspace envia uma solicitação unwrap
para o URL do endpoint KACLS para descriptografia. Além das verificações de segurança opcionais, como as baseadas em perímetro e declaração de JWT, suas KACLS precisam realizar as seguintes etapas:
Verifique se os tokens de autorização e autenticação são do mesmo usuário
fazendo uma correspondência sem diferenciação de maiúsculas e minúsculas nas declarações de e-mail.
Quando o token de autenticação contém a declaração opcional google_email,
ela precisa ser comparada com a declaração de e-mail no token de autorização
usando uma abordagem sem diferenciação de maiúsculas e minúsculas. Não use a declaração de e-mail no token de autenticação para essa comparação.
Em cenários em que o token de autenticação não tem a declaração opcional google_email, a declaração de e-mail no token de autenticação deve ser comparada com a declaração de e-mail no token de autorização usando um método sem diferenciação de maiúsculas e minúsculas.
Em cenários em que o Google emite um token de autorização para um e-mail não associado a uma Conta do Google, a declaração email_type precisa estar presente.
Isso forma uma parte crucial do recurso de acesso de visitante, fornecendo informações valiosas para que as KACLs apliquem medidas de segurança adicionais a usuários externos.
Alguns exemplos de como um KACLS pode usar essas informações:
Para impor requisitos de geração de registros adicionais.
Para restringir o emissor de token de autenticação a um IdP convidado dedicado.
Para exigir declarações adicionais no token de autenticação.
Se um cliente não tiver configurado o acesso de convidado, todas as solicitações em que email_type estiver definido como google-visitor ou customer-idp poderão ser rejeitadas. As solicitações com um email_type de google ou com um email_type não definido ainda serão aceitas.
Quando o token de autenticação contém a declaração opcional delegated_to, ele também precisa conter a declaração resource_name, e essas duas declarações precisam ser comparadas com as declarações delegated_to e resource_name no token de autorização. As declarações delegated_to precisam ser comparadas usando uma abordagem independente de maiúsculas e minúsculas, e o resource_name nos tokens precisa corresponder ao resource_name da operação.
Verifique se a declaração role no token de autorização é reader ou
writer.
Verifique se a declaração kacls_url no token de autorização corresponde ao
URL atual do KACLS. Isso permite a detecção de possíveis servidores man-in-the-middle
configurados por pessoas de dentro ou administradores de domínio desonestos.
Descriptografe as seguintes partes usando um algoritmo de criptografia autenticada:
Chave de criptografia de dados (DEK)
Os valores resource_name e perimeter_id do token de autorização
Outros dados sensíveis
Verifique se o resource_name no token de autorização e no blob descriptografado
correspondem.
Faça uma verificação de perímetro usando declarações de autenticação e autorização.
Registre a operação, incluindo o usuário que a originou, o resource_name e o motivo transmitido na solicitação.
[null,null,["Última atualização 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)."]]
