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:
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 comogoogle-visitor
oucustomer-idp
poderão ser rejeitadas. As solicitações com umemail_type
degoogle
ou com umemail_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.
Criptografe as partes a seguir usando um algoritmo de criptografia autenticado:
- Chave de criptografia de dados (DEK)
- Os valores
resource_name
eperimeter_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.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.
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:
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 comogoogle-visitor
oucustomer-idp
poderão ser rejeitadas. As solicitações com umemail_type
degoogle
ou com umemail_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.
Descriptografe as partes a seguir usando um algoritmo de criptografia autenticado:
- Chave de criptografia de dados (DEK)
- Os valores
resource_name
eperimeter_id
do token de autorização - Outros dados sensíveis
Verifique se o
resource_name
no token de autorização e o blob descriptografado correspondem.Realizar uma verificação do 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.Retorne a DEK desencapsulada ou uma resposta de erro estruturada.