Criptografar e descriptografar dados

Este guia descreve como a criptografia e a descriptografia funcionam usando a API Criptografia do lado do cliente do Google Workspace.

É necessário incluir na lista de permissões todos os serviços de provedor de identidade (IdP) usados pelos usuários que compartilham arquivos criptografados. Geralmente, os detalhes do IdP necessários estão 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 (CSE) do lado do cliente, o Google Workspace envia uma solicitação wrap para o URL do endpoint do KACLS para criptografia. Além das verificações de segurança opcionais, como as verificações baseadas em declarações de JWT e de perímetro, as KACLS precisam realizar as seguintes etapas:

  1. Valide o usuário solicitante.

    • Valide o token de autenticação e o token de autorização.
    • Verifique se os tokens de autorização e autenticação são para o mesmo usuário fazendo uma correspondência sem distinção entre maiúsculas e minúsculas nas reivindicações de e-mail.
    • Quando o token de autenticação contém a declaração google_email opcional, ele precisa ser comparado com a declaração de e-mail no token de autorização 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 alegação opcional google_email, a alegação de e-mail no token de autenticação precisa ser comparada com a alegaçã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 reivindicação email_type precisa estar presente. Isso é uma parte crucial do recurso de acesso de convidados, fornecendo informações valiosas para que o KACLS aplique outras medidas de segurança a usuários externos.
      • Confira alguns exemplos de como uma KACLS pode usar essas informações:
      • Para impor requisitos de registro adicionais.
      • Para restringir o emissor do token de autenticação a um IdP dedicado para convidados.
      • Para exigir declarações adicionais no token de autenticação.
      • Se um cliente não tiver configurado o acesso de convidados, 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 vão continuar sendo aceitas.
    • 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 a detecção de possíveis serviços man-in-the-middle configurados por pessoas com acesso privilegiado ou administradores de domínio fraudulentos.
    • Faça uma verificação de perímetro usando as reivindicações de autenticação e autorização.

  2. Criptografar as partes a seguir 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

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

  4. Retorna um objeto binário opaco para ser armazenado pelo Google Workspace com o objeto criptografado e enviado como está em qualquer operação de desempacotamento de chave subsequente. Ou envie uma resposta estruturada de erro.

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

Descriptografar dados

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

  1. Valide o usuário solicitante.

    • Valide o token de autenticação e o token de autorização.
    • Verifique se os tokens de autorização e autenticação são para o mesmo usuário fazendo uma correspondência sem distinção entre maiúsculas e minúsculas nas reivindicações de e-mail.
    • Quando o token de autenticação contém a declaração google_email opcional, ele precisa ser comparado com a declaração de e-mail no token de autorização 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 alegação opcional google_email, a alegação de e-mail no token de autenticação precisa ser comparada com a alegaçã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 reivindicação email_type precisa estar presente. Isso é uma parte crucial do recurso de acesso de convidados, fornecendo informações valiosas para que o KACLS aplique outras medidas de segurança a usuários externos.
      • Confira alguns exemplos de como uma KACLS pode usar essas informações:
      • Para impor requisitos de registro adicionais.
      • Para restringir o emissor do token de autenticação a um IdP dedicado para convidados.
      • Para exigir declarações adicionais no token de autenticação.
      • Se um cliente não tiver configurado o acesso de convidados, 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 vão continuar sendo aceitas.
    • 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ínios maliciosos.

  2. Descriptografar as partes a seguir 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

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

  4. Faça 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 desencapsulada ou uma resposta de erro estruturada.