Gerenciar arquivos criptografados do lado do cliente com a API Drive

Com a criptografia do lado do cliente (CSE), seus dados são criptografados antes de chegarem aos servidores do Drive, a você controle sobre eles. Este guia mostra o processo de criptografia e upload programáticos, além de download e descriptografia de arquivos da CSE usando a API Drive. Ele também aborda as abordagens recomendadas para testar e validar sua implementação.

Antes de começar

Antes de gerenciar arquivos criptografados, configure seu domínio do Google Workspace usando a seguinte lista de verificação:

• Configure a criptografia do lado do cliente (CSE) para seu domínio.

• Configure seu provedor de identidade (IdP).

• Verifique se o Serviço de lista de controle de acesso de chaves (KACLS) é compatível com os endpoints /wrap, /unwrap, /privilegedwrap, /privilegedunwrap e /digest.

• Crie um projeto no Console do Google Cloud e ative a API Drive.

Autenticação e autorização

Para interagir com a API Drive e suas KACLS, escolha um método de autenticação. Essa escolha afeta a maneira como você interage com os dois serviços:

• Individual:para se autenticar como um indivíduo, use o fluxo do OAuth para agir em nome desse usuário. Use os endpoints padrão /wrap e /unwrap e forneça o token de autorização do Google para esse usuário.
• Administrador:para representar outros usuários no domínio, use uma conta de serviço com delegação em todo o domínio (DWD, na sigla em inglês). Use os endpoints /privilegedwrap e /privilegedunwrap sem um token de autorização do Google.

Atenção: se uma conta de serviço for usada sem delegação em todo o domínio, os arquivos criados serão adicionados ao drive da conta de serviço e não ao drive de um usuário específico, o que torna os arquivos inacessíveis aos usuários.

Para mais detalhes sobre como criar credenciais, consulte o guia Criar credenciais de acesso.

Autenticação do IdP de domínio

Para autenticar com seu IdP, configure um ID do cliente OAuth e faça o download do arquivo de chave secreta do cliente. O aplicativo precisa receber um token de autenticação do IdP para autenticar solicitações ao KACLS. Esse token é necessário para permitir que seu aplicativo acesse a chave de criptografia de dados.

Processar credenciais com segurança

Seu aplicativo processa credenciais sensíveis para autenticação na API Drive e no seu IdP. São eles:

• Material secreto do IdP, como um arquivo de chave secreta do cliente
• Material secreto do Google, como um arquivo de chave privada de conta de serviço
• Material secreto armazenado pelo app, como credenciais salvas.

É preciso garantir que todas essas credenciais sejam armazenadas com segurança.

Limites e cotas

Os arquivos criptografados do lado do cliente estão sujeitos aos limites e cotas padrão do Drive. Conheça os limites dos drives compartilhados, os limites gerais de arquivos e pastas e saiba como gerenciar sua cota. Além disso, a ferramenta de importação precisa processar os limites de taxa do serviço de lista de controle de acesso a chaves (KACLS) e do provedor de identidade (IdP).

Estrutura de arquivo criptografado

O Drive espera o seguinte formato de arquivo criptografado do lado do cliente para uploads e downloads.

+-------------------+
| Magic header      |
+-------------------+
| Encrypted Chunk 1 |
+-------------------+
| Encrypted Chunk 2 |
+-------------------+
| ...               |
+-------------------+
| Encrypted Chunk N |
+-------------------+

Cabeçalho mágico

Um cabeçalho mágico (também conhecido como assinatura de arquivo ou número mágico) é uma sequência constante de bytes colocada no início de um arquivo para identificar exclusivamente o formato dele. O arquivo precisa começar com os bytes 0x99 0x5E 0xCC 0x5E.

Blocos criptografados

O arquivo precisa ser dividido em partes de 2 MiB. Cada parte é criptografada usando a primitiva de criptografia autenticada com dados associados (AEAD) da biblioteca Google Tink com um tipo de chave AES-GCM, usando o índice da parte e uma flag de parte final como os dados associados. Para um exemplo de código que usa a API Drive e está em conformidade com essa especificação, consulte a demonstração de código aberto.

Aviso: o Drive não vai conseguir descriptografar do lado do cliente arquivos estruturados incorretamente. Consulte as técnicas de validação para conhecer os métodos de teste recomendados.

Criptografar e fazer upload de um arquivo

Para fazer upload de um arquivo CSE, seu aplicativo precisa autenticar, solicitar um token CSE, criptografar o conteúdo do arquivo localmente, encapsular a chave de criptografia e, por fim, fazer upload do conteúdo criptografado e dos metadados para o Google Drive.

Receber um token da CSE

Solicite um token da CSE do Google Drive chamando o método Files:generateCseToken da API Drive. Não inclua o parâmetro de consulta fileId na solicitação. Para criar o arquivo em uma pasta específica, inclua o parâmetro de consulta parent com o ID da pasta. Se parent for omitido, o arquivo será criado na pasta raiz do Meu Drive do usuário. A resposta inclui um ID de arquivo exclusivo para o upload e um token de autorização JWT, que é necessário para a etapa de encapsulamento de chaves.

Criptografar dados localmente

1. Use o Google Tink para gerar uma chave de criptografia de dados (DEK) exclusiva para o arquivo.
2. Criptografe o conteúdo do arquivo de acordo com a estrutura de arquivo criptografado.

Calcular hash da chave de recurso de computação

Para calcular o hash da chave de recurso:

1. Extraia o resource_name e o perimeter_id do token de autorização jwt recebido de generateCseToken. Se perimeter_id estiver ausente, use uma string vazia.
2. Calcule o HMAC-SHA256 usando a DEK de texto simples como chave e a string ResourceKeyDigest:my_resource_name:my_perimeter_id como os dados a serem assinados.
3. Codifique o hash resultante em Base64.

Para mais detalhes, consulte Hash da chave de recurso.

Encapsular a chave de criptografia

Para proteger a DEK, criptografe (encapsule) usando o KACLS externo.

1. Chame o endpoint apropriado:
   • Individual:/wrap
   • Administrador:/privilegedwrap
2. Transmita a DEK de texto simples, o token de autenticação do IdP, o token de autorização do Google (se necessário), o resource_name do JWT e um reason.
3. Receba a DEK encapsulada (WDEK) do KACLS.

Fazer upload para o Drive

Use o endpoint files.create da API Drive para fazer um upload de arquivo padrão do blob de arquivo criptografado. Defina os seguintes campos nos metadados do arquivo:

• id: o ID exclusivo do arquivo recebido da resposta generateCseToken.
• mimeType: application/vnd.google-gsuite.encrypted; content="application/octet-stream".
  • O parâmetro content pode ser definido como o tipo MIME do arquivo original.
• clientEncryptionDetails:
  • encryptionState: "encrypted".
  • decryptionMetadata:
    • wrappedKey: a DEK encapsulada (WDEK) recebida do KACLS.
    • kaclsId: o ID do KACLS recebido da resposta generateCseToken.
    • keyFormat: "tinkAesGcmKey".
    • aes256GcmChunkSize: "default".
    • encryptionResourceKeyHash: o hash calculado em Calcular hash da chave do recurso.

Observação: alguns campos exigem codificação base64. Consulte a documentação da API Drive para mais detalhes

Exemplo de código aberto

Para uma demonstração prática do processo de criptografia e upload, consulte a demonstração de código aberto. Isso fornece uma solução funcional e pode servir como uma referência valiosa.

Baixar e descriptografar um arquivo

Para baixar um arquivo CSE, é necessário recuperar o conteúdo e os metadados criptografados do Google Drive, solicitar a DEK de texto simples do KACLS e descriptografar o arquivo localmente.

Recuperar metadados de arquivos e conteúdo criptografado

Chame o método Files:get da API Drive para recuperar os metadados e o conteúdo do arquivo. O clientEncryptionDetails contém o DecryptionMetadata, que inclui a DEK encapsulada (WDEK) e o JWT com as informações do KACLS.

Remover o invólucro da chave de criptografia

1. Chame o endpoint apropriado:
   • Individual:/unwrap
   • Administrador:/privilegedunwrap
2. Transmita a WDEK, o token de autenticação do IdP, o token de autorização do Google (se necessário), o resource_name e um reason.
3. Receba a DEK em texto simples do KACLS.

Descriptografar dados localmente

1. Inicialize a criptografia usando a DEK de texto simples recebida do KACLS.
2. Pule os bytes mágicos iniciais e descriptografe o conteúdo restante de acordo com a estrutura do arquivo criptografado.

Exemplo de código aberto

Para uma demonstração prática do processo de download e descriptografia, consulte a demonstração de código aberto. Isso fornece uma solução funcional e pode servir como uma referência valiosa.

Validar arquivos importados

Como o Google não tem acesso às chaves de criptografia, não é possível descriptografar e validar seus arquivos do lado do servidor. Erros de implementação durante as fases de criptografia local ou encapsulamento de chaves resultam em erros ao descriptografar arquivos do lado do cliente. É fundamental fazer uma validação completa antes de usar sua própria implementação.

Para que o conteúdo enviado da CSE do Google Drive funcione corretamente, ele precisa estar criptografado e ter os metadados corretos. Você é responsável por garantir que o conteúdo seja válido e possa ser descriptografado.

Realizar testes de criptografia e descriptografia de ida e volta

Para validar sua implementação, é fundamental testar o fluxo de ponta a ponta. Isso envolve pegar um conjunto de arquivos de teste, criptografá-los usando sua lógica local, fazer upload deles para o Drive usando a API e depois baixar e descriptografar. Depois da descriptografia, compare o conteúdo resultante com os arquivos originais para garantir que eles sejam idênticos. Esse processo ajuda a detectar problemas na criptografia, no encapsulamento de chaves ou no processamento de metadados. A demonstração de código aberto mostra como implementar esse processo de validação no seu próprio aplicativo.

Verificação pontual com o Google Drive

Verifique se os arquivos enviados incluem um ícone de bloqueio no cliente da Web do Drive. Baixe manualmente um pequeno número de arquivos enviados para verificar se eles funcionam conforme o esperado. Essa verificação usa a implementação da CSE do Google para tentar a descriptografia, ajudando a isolar problemas na sua criptografia ou lógica de encapsulamento de chaves. Inclua arquivos do Meu Drive e dos drives compartilhados.

Aviso: não exclua os arquivos de origem originais até validar completamente que as versões importadas da CSE podem ser descriptografadas.

Demonstração de código aberto

O pacote de código aberto Upload da CSE do Drive (link em inglês) oferece uma biblioteca Python completa e funcional e um exemplo de linha de comando que implementa os fluxos de upload e download da CSE descritos neste guia. É altamente recomendável revisar o código de demonstração antes de criar sua própria integração da CSE.