Hashes e eTags: práticas recomendadas

O Cloud Storage incentiva os usuários a validar os dados transferidos de/para seus buckets usando as somas de verificação CRC32c ou MD5. Nesta seção, você verá as práticas recomendadas para executar essas validações.

Como usar hashes para verificação de integridade

Há várias maneiras de corromper os dados durante o upload ou o download do Cloud:

  • Links de rede com ruído.
  • Erros de memória em computadores clientes ou servidores, ou roteadores ao longo do caminho.
  • Erros de software (por exemplo, em uma biblioteca que os clientes usam).
  • Alterações no arquivo de origem quando ocorre um upload durante um período prolongado.

Para proteger contra esse problema, o Cloud Storage aceita dois tipos de hashes: CRC32C e MD5. O CRC32C é o método de validação recomendado. Os clientes que preferem a MD5 podem usar esse hash, mas hashes MD5 não são compatíveis com objetos compostos ou objetos criados a partir de um upload de várias partes da API XML.

CRC32C

Todos os objetos do Cloud Storage têm uma hash CRC32C. As bibliotecas para computação do CRC32c incluem:

A CRC32c codificada em Base64 está na ordem de bytes big-endian.

MD5

O Cloud Storage é compatível um hash MD5 para objetos que atendem aos seguintes critérios:

Esse hash só se aplica a um objeto completo, portanto, não pode ser usado para verificar parcialmente os downloads causados pela execução de um intervalo GET.

ETags

O cabeçalho ETag de um objeto retorna o valor MD5 do objeto se todas as condições a seguir forem verdadeiras:

Em todos os outros casos, os usuários não precisam pressupor o valor usado em uma ETag, exceto que ele é alterado sempre que os dados subjacentes são alterados, de acordo com a especificação.

O mesmo objeto pode ter um valor de ETag diferente quando solicitado da API XML em comparação com a API JSON.

Validação

Uma verificação de integridade de download pode ser executada ao fazer a hash dos dados de download no período de veiculação e comparar seus resultados às hashes fornecidas pelo servidor. Descarte dados de download com valores de hash incorretos e use a lógica de repetição para evitar loops infinitos e potencialmente caros.

O Cloud Storage realiza a validação do servidor nos seguintes casos:

  • Quando você faz uma solicitação de cópia ou regravação no Cloud Storage.

  • Ao fornecer o hash MD5 ou CRC32C esperado de um objeto em uma solicitação de upload. O Cloud Storage criará o objeto somente se o hash fornecido corresponder ao valor calculado pelo Cloud Storage.

Como alternativa, é possível optar por realizar a validação dos uploads no lado do cliente emitindo uma solicitação para os metadados do objeto enviado, comparando o valor de hash informado e excluindo o objeto em caso de incompatibilidade. Esse método é útil se o hash MD5 ou CRC32C do objeto não for conhecido no início do upload. Para evitar disputas em que processos independentes excluem ou substituem os dados uns dos outros, também recomendamos o uso de gerações de objetos e condições prévias.

No caso de uploads compostos paralelos, os usuários precisam executar uma verificação de integridade para cada upload de componente e, em seguida, usam as condições prévias do componente com as solicitações de composição para proteção contra disputas. A composição de objetos não oferece validação MD5 do lado do servidor. Portanto, usuários que quiserem executar uma verificação de integridade completa precisam aplicar a validação do lado do cliente ao novo objeto composto.

Ao final de cada operação de cópia, os comandos cp e rsync do gsutil validam se a soma de verificação do arquivo local corresponde à soma de verificação do objeto armazenado no Cloud Storage. Caso contrário, o gsutil exclui a cópia inválida e imprime uma mensagem de aviso. Isso raramente acontece. Em caso afirmativo, você poderá repetir a operação.

API XML

Na API XML, as hashes MD5 e CRC32C codificadas em base64 são expostas e aceitas por meio do cabeçalho x-goog-hash. Antes, as MD5s eram usadas como ETags de objeto, mas os usuários precisam evitar essa pressuposição, já que alguns objetos usam valores de ETag opacos que não garantem nada além da mudança quando o objeto muda.

É possível realizar a validação de upload do lado do servidor fornecendo hashes calculadas localmente por meio do cabeçalho de solicitação x-goog-hash. Além disso, é possível fornecer a MD5 usando o cabeçalho Content-MD5 HTTP padrão (consulte a especificação).

API JSON

Na API JSON, as properties md5Hash e crc32c do recurso de objetos contêm hashes MD5 e CRC32C codificadas em base64, respectivamente. Fornecer a property de metadados é opcional. Fornecer uma das propriedades como parte de um upload retomável ou do upload da API JSON aciona a validação do lado do servidor para o novo objeto. Se o Cloud Storage calcular um valor para qualquer property que não corresponda a um valor fornecido, o objeto não será criado. Se as propriedades não forem fornecidas em uma inserção de objeto, o Cloud Storage calculará os valores e os gravará nos metadados do objeto.