Hashes e ETags: práticas recomendadas

O Cloud Storage recomenda que você valide os dados transferidos de/para seus buckets. Nesta página, descrevemos as práticas recomendadas para realiza validações usando as somas de verificação CRC32C ou MD5.

Proteger contra corrupção de dados usando hashes

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

  • 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.

O Cloud Storage aceita dois tipos de hashes que podem ser usados para verificar a integridade dos dados: CRC32C e MD5. O CRC32C é o método de validação recomendado para realizar verificações de integridade. 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 por 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 ou metadados 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. Se não corresponder, a solicitação será rejeitada com um erro BadRequestException: 400.

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 excluam ou substituam os dados uns dos outros, use gerações de objetos e pré-condições.

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.

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.

CLI do Google Cloud

Para a CLI do Google Cloud, os dados copiados de ou para um bucket do Cloud Storage são validados. Isso se aplica aos comandos cp, mv e rsync. Quando o checksum dos dados de origem não corresponde ao checksum dos dados de destino, a gcloud CLI exclui a cópia inválida e gera uma mensagem de aviso. Isso raramente acontece. Se isso acontecer, repita a operação.

Essa validação automática ocorre após a finalização do próprio objeto. Portanto, objetos inválidos ficam visíveis por um a três segundos antes de serem identificados e excluídos. Além disso, há uma chance de que a gcloud CLI possa ser interrompida após a conclusão do upload, mas antes de realizar a validação, deixando o objeto inválido no lugar. Esses problemas podem ser evitados ao fazer upload de arquivos individuais para o Cloud Storage com a validação do lado do servidor, que ocorre ao usar a flag--content-md5=MD5.

A seguir