Criptografar e descriptografar dados

Neste guia, descrevemos como a criptografia e a descriptografia funcionam usando a API de criptografia do lado do cliente Google Workspace.

Você precisa colocar na lista de permissões todos os serviços de provedor de identidade (IdP) usados pelos usuários que compartilham arquivos criptografados. Geralmente, é possível encontrar os detalhes necessários do IdP 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 pede para salvar ou armazenar dados criptografados do lado do cliente (CSE), o Google Workspace envia uma solicitação wrap para o URL do endpoint KACLS para criptografia. Além das verificações de segurança opcionais, como verificações baseadas em declaração de perímetro e JWT, o KACLS precisa 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 indiferente a maiúsculas nas declaraçõ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 usando uma abordagem que não diferencia maiúsculas de minúsculas. Não use a declaração de e-mail no token de autenticação para essa comparação.
   • Nos cenários em que o token de autenticação não tem a declaração google_email opcional, a declaração de e-mail no token de autenticação deve ser comparada com a declaração no token de autorização usando um método que não diferencia maiúsculas de minúsculas.
   • Nos 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 é uma parte crucial do recurso Acesso para convidados, fornecendo informações valiosas para que KACLS aplique outras medidas de segurança a usuários externos.
     • Alguns exemplos de como um KACLS pode usar essas informações incluem:
     • Para impor outros requisitos de geração de registros.
     • Para restringir o emissor do token de autenticação a um IdP convidado dedicado.
     • 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.
   • 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 KACLS atual. Essa verificação permite a detecção de possíveis servidores "man-in-the-middle" configurados por pessoas com informações privilegiadas ou administradores de domínio não autorizados.
   • Fazer uma verificação do perímetro usando declarações de autenticação e autorização.

2. Criptografe 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
   • 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 a ser armazenado pelo Google Workspace com o objeto criptografado e enviado no estado em que se encontra em qualquer operação subsequente de desencapsulamento de chaves. Se preferir, exiba uma resposta de erro estruturado.

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

Observação: não armazene a DEK no seu sistema KACLS. Em vez disso, criptografe-o e retorne no objeto wrapped_key para evitar discrepâncias durante a vida útil do arquivo. O Google não envia solicitações de exclusão para o KACLS quando os objetos são excluídos.

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 ao URL do endpoint KACLS para descriptografia. Além das verificações de segurança opcionais, como verificações baseadas em declaração de perímetro e JWT, o KACLS precisa executar 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 indiferente a maiúsculas nas declaraçõ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 usando uma abordagem que não diferencia maiúsculas de minúsculas. Não use a declaração de e-mail no token de autenticação para essa comparação.
   • Nos cenários em que o token de autenticação não tem a declaração google_email opcional, a declaração de e-mail no token de autenticação deve ser comparada com a declaração no token de autorização usando um método que não diferencia maiúsculas de minúsculas.
   • Nos 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 é uma parte crucial do recurso Acesso para convidados, fornecendo informações valiosas para que KACLS aplique outras medidas de segurança a usuários externos.
     • Alguns exemplos de como um KACLS pode usar essas informações incluem:
     • Para impor outros requisitos de geração de registros.
     • Para restringir o emissor do token de autenticação a um IdP convidado dedicado.
     • 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.
   • Verifique se a declaração role no token de autorização é "leitor" ou "gravador".
   • Verifique se a declaração kacls_url no token de autorização corresponde ao URL KACLS atual. Isso permite a detecção de possíveis servidores "man-in-the-middle" configurados por pessoas com informações privilegiadas ou administradores de domínio não autorizados.

2. Descriptografe 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
   • Outros dados sensíveis

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

4. Realizar uma verificação do 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.

Observação: para descriptografar solicitações do Google Takeout, consulte takeout_unwrap.