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

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 o MD5 podem usar esse hash, mas os hashes MD5 não são compatíveis com objetos compostos.

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 aceita uma hash MD5 para objetos não compostos. Essa hash só se aplica a um objeto completo, portanto, não pode ser usada para verificar parcialmente os downloads causados ​​pela execução de um intervalo GET.

ETags

Para objetos não compostos, a API XML usa o MD5 do objeto para o valor do cabeçalho da ETag. 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 é compatível com a validação do lado do servidor para uploads, mas a validação do lado do cliente também é uma abordagem comum. Se seu aplicativo já tiver computado a MD5 ou a CRC32C do objeto antes de iniciar o upload, será possível fornecê-la com a solicitação de upload, e o Cloud Storage só criará o objeto se a hash fornecida corresponder ao valor que calculamos.

Como alternativa, é possível optar por realizar a validação no lado do cliente emitindo uma solicitação para os metadados do novo objeto, comparando o valor de hash informado e excluindo o objeto em caso de incompatibilidade. Para evitar disputas em que processos independentes excluam ou substituam 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.