Gerenciar arquivos criptografados do lado do cliente com a API Drive

A criptografia do lado do cliente (CSE, na sigla em inglês) garante que os dados sejam criptografados antes de chegar aos servidores do Drive, controle sobre eles. Este guia orienta sobre o processo de criptografia e upload programáticos, bem como o download e a descriptografia de arquivos CSE usando a API Drive. Ele também aborda 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 a chaves (KACLS, na sigla em inglês) oferece suporte aos /wrap, /unwrap, /privilegedwrap, /privilegedunwrap e /digest endpoints.

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

Autenticação e autorização

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

• Individual: para autenticar como um indivíduo, use o OAuth fluxo 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 se passar por 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 de um usuário específico, tornando 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. Seu 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.

Gerenciar credenciais com segurança

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

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

É necessário 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. Esteja ciente dos limites de drives compartilhados, dos limites gerais de arquivos e pastas, e de como gerenciar sua cota. Além disso, sua ferramenta de importação precisa processar 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 de bytes constante 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 blocos de 2 MiB. Cada bloco é criptografado usando a biblioteca Tink do Google com a primitiva de criptografia autenticada com dados associados (AEAD, na sigla em inglês) com um tipo de chave AES-GCM, usando o índice de bloco e um flag de bloco 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 poderá descriptografar arquivos do lado do cliente que estiverem estruturados incorretamente. Consulte as técnicas de validação para 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 e dos metadados criptografados para o Google Drive.

Receber um token CSE

Solicite um token CSE do Google Drive chamando o método da API Drive Files:generateCseToken. 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 "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 chave.

Criptografar dados localmente

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

Calcular o hash da chave de recurso

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 a 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, na sigla em inglês) do KACLS.

Fazer upload para o Drive

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

• id: o ID de arquivo exclusivo 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 o hash da chave de 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.

Fazer o download e descriptografar um arquivo

Para fazer o download de 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 da API Drive Files:get 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 que contém as informações do KACLS.

Desencapsular a 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 de texto simples do KACLS.

Descriptografar dados localmente

1. Inicialize a cifra 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 no servidor. Erros de implementação durante as fases de criptografia local ou encapsulamento de chave resultarão em erros ao descriptografar arquivos do lado do cliente. A validação completa é fundamental antes de usar sua própria implementação.

Para que o conteúdo CSE do Google Drive enviado funcione corretamente, ele precisa ser criptografado corretamente e conter 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 a criação de um conjunto de arquivos de teste, a criptografia deles usando sua lógica local, o upload para o Drive usando a API e, em seguida, o download e a descriptografia. Após a 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 demonstra 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 cadeado no cliente da Web do Drive. Faça o download manual de um pequeno número de arquivos enviados para verificar se eles funcionam conforme o esperado. Essa verificação usa a implementação CSE do Google para tentar a descriptografia, ajudando a isolar problemas na criptografia ou na lógica de encapsulamento de chaves. Inclua arquivos de Meu Drive e Drives compartilhados.

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

Demonstração de código aberto

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