Criptografar e descriptografar dados

Este guia descreve como a criptografia e a descriptografia funcionam usando a API Google Workspace Client-side Encryption.

Você precisa adicionar à lista de permissões todos os serviços de provedor de identidade (IdP) usados por usuários que compartilham arquivos criptografados. Geralmente, os detalhes do IdP necessários 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 receber os detalhes do IdP.

Criptografar dados

Quando um usuário do Google Workspace solicita salvar ou armazenar dados criptografados do lado do cliente (CSE), o Google Workspace envia uma wrap solicitação para o URL do endpoint da lista de controle de acesso de chaves (KACLS, na sigla em inglês) para criptografia. Além de verificações de segurança opcionais, como verificações de perímetro e baseadas em declarações JWT, seu KACLS precisa realizar as seguintes etapas:

  1. Validar o usuário solicitante.

    • Validar o token de autenticação e o token de autorização.
    • Verificar se os tokens de autorização e autenticação são do mesmo usuário fazendo uma correspondência sem distinção entre 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 distinção entre 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 precisa ser comparada com a declaração de e-mail no token de autorização, usando um método sem distinção entre 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 convidado, fornecendo informações valiosas para que o KACLS aplique medidas de segurança adicionais a usuários externos.
      • Alguns exemplos de como um KACLS pode usar essas informações incluem:
      • Para impor requisitos de registro adicionais.
      • Para restringir o emissor do token de autenticação a um IdP de 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 precisam continuar sendo 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 sem distinção entre 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 do KACLS atual. Essa verificação permite a detecção de possíveis servidores man-in-the-middle configurados por pessoas de dentro da empresa ou administradores de domínio desonestos.
    • Realize uma verificação de perímetro usando declarações de autenticação e autorização.

  2. Criptografar as partes a seguir usando um algoritmo de criptografia autenticado:

    • Chave de criptografia de dados (DEK)
    • Os valores resource_name e perimeter_id do token de autorização
    • Quaisquer outros dados sensíveis

  3. Registre a operação, incluindo o usuário que a originou, o resource_name e o motivo transmitido na solicitação.

  4. Retorne um objeto binário opaco para ser armazenado pelo Google Workspace junto com o objeto criptografado e enviado como está em qualquer operação subsequente de desembrulho de chaves. Ou, disponibilize uma resposta de erro estruturada.

    • O objeto binário precisa conter apenas a cópia da DEK criptografada. Dados específicos da implementação podem ser armazenados nele.

Descriptografar dados

Quando um usuário do Google Workspace solicita abrir dados criptografados do lado do cliente (CSE), o Google Workspace envia uma unwrap solicitação para o URL do endpoint do KACLS para descriptografia. Além de verificações de segurança opcionais, como verificações de perímetro e baseadas em declarações JWT, seu KACLS precisa realizar as seguintes etapas:

  1. Validar o usuário solicitante.

    • Validar o token de autenticação e o token de autorização.
    • Verificar se os tokens de autorização e autenticação são do mesmo usuário fazendo uma correspondência sem distinção entre 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 distinção entre 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 precisa ser comparada com a declaração de e-mail no token de autorização, usando um método sem distinção entre 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 convidado, fornecendo informações valiosas para que o KACLS aplique medidas de segurança adicionais a usuários externos.
      • Alguns exemplos de como um KACLS pode usar essas informações incluem:
      • Para impor requisitos de registro adicionais.
      • Para restringir o emissor do token de autenticação a um IdP de 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 precisam continuar sendo 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 sem distinção entre 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 do KACLS atual. Isso permite a detecção de possíveis servidores man-in-the-middle configurados por pessoas de dentro da empresa ou administradores de domínio desonestos.

  2. Descriptografar as partes a seguir usando um algoritmo de criptografia autenticado:

    • Chave de criptografia de dados (DEK)
    • Os valores resource_name e perimeter_id do token de autorização
    • Quaisquer outros dados sensíveis

  3. Verifique se o resource_name no token de autorização e o blob descriptografado correspondem.

  4. Realize uma verificação de perímetro usando declarações de autenticação e autorização.

  5. Registre a operação, incluindo o usuário que a originou, o resource_name e o motivo transmitido na solicitação.

  6. Retorne a DEK desembrulhada ou uma resposta de erro estruturada.