Validação de dados e detecção de mudanças com checksums

Para validar a integridade de dados e detectar alterações, o Cloud Storage recomenda que você use checksums ao transferir dados de e para seus buckets. Nesta página, fornecemos informações sobre como as somas de verificação são usadas no Cloud Storage e como especificá-las ao enviar solicitações.

Evitar a corrupção de dados usando checksums

Às vezes, os dados podem ser corrompidos durante a transferência para ou da nuvem devido a bugs de software ou hardware, erros de memória ou roteador, distúrbios elétricos ou alterações nos dados de origem durante uploads de arquivos de longo período.

Para proteger você contra corrupção de dados, o Cloud Storage é compatível com o uso de checksums CRC32C e MD5 para verificar a integridade dos dados e detectar alterações neles.

O CRC32C é o método de validação recomendado para realizar verificações de integridade. A validação com hashes MD5 é compatível com uploads de arquivo único, mas não é compatível com objetos enviados em partes, como objetos compostos e objetos enviados usando um upload de várias partes da API XML.

Checksums para gravações de dados

Para gravações de objetos, o cliente calcula o checksum do arquivo local e o anexa aos cabeçalhos HTTP da solicitação de upload do objeto. O servidor recebe o payload de dados, calcula o próprio checksum e valida os dados comparando os dois checksums após a conclusão do upload. Se as somas de verificação forem iguais, o objeto será armazenado no Cloud Storage com as somas de verificação. Se as somas de verificação não corresponderem, a solicitação de gravação será rejeitada com um erro BadRequestException: 400.

Validação do lado do servidor para gravações de dados

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

  • Quando você fornece o hash MD5 ou CRC32C de um objeto em uma solicitação de upload de objeto. Para aprender mais sobre os tipos de upload de objetos, consulte Uploads de objetos.

  • Quando você faz uma solicitação de cópia ou regravação no Cloud Storage. Para solicitações de cópia e regravação de objetos, o Cloud Storage realiza automaticamente a validação do lado do servidor com base em uma soma de verificação não editável armazenada com o objeto de origem.

Uploads de solicitação única (mídia) da API JSON

Para uploads de mídia da API JSON, é possível especificar checksums no cabeçalho X-Goog-Hash da solicitação. Exemplo:

curl -X POST --data-binary @Desktop/dog-pic.jpeg \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: image/jpeg" \
    -H "X-Goog-Hash: crc32c=n03x6A==" \
    "https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=media&name=dog-pic.jpeg"

Uploads de várias partes da API JSON

Para uploads de várias partes da API JSON, é possível especificar checksums como parte do contêiner de solicitação, na seção de metadados do objeto ou em uma terceira string de limite. Para detalhes sobre a estrutura JSON e as chaves válidas de um objeto, consulte a representação de recursos de objetos.

O exemplo a seguir especifica um checksum CRC32C na parte de metadados do objeto de um contêiner de solicitação:

--separator_string
Content-Type: application/json; charset=UTF-8

{
"name":"my-document.txt",
"crc32c": "n03x6A=="
}

--separator_string
Content-Type: text/plain

This is a text file.
--separator_string--

O exemplo a seguir especifica um checksum CRC32C na terceira string de limite de um contêiner de solicitação:

--separator_string
Content-Type: application/json; charset=UTF-8

{
"name":"my-document.txt"
}

--separator_string
Content-Type: text/plain

This is a text file.

--separator_string
Content-Type: application/json; charset=UTF-8

{ "crc32c": "n03x6A==" }
--separator_string--

Uploads retomáveis da API JSON

Para uploads retomáveis da API JSON, é possível especificar checksums no cabeçalho X-Goog-Hash da solicitação final que conclui o upload. Exemplo:

curl -i -X PUT --data-binary @Desktop/dog-pic.jpeg \
      -H "Content-Length: 2000000" \
      -H "X-Goog-Hash: crc32c=n03x6A==" \
      "SESSION_URI"

O checksum especificado na solicitação final é calculado com base em todo o objeto, não apenas nos dados do objeto na solicitação final.

Uploads de solicitação única da API XML

Para uploads de solicitação única da API XML, é possível especificar checksums no cabeçalho x-goog-hash da solicitação.

Exemplo:

curl -X PUT --data-binary @Desktop/dog-pic.jpeg \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: image/jpeg" \
    -H "x-goog-hash: crc32c=n03x6A==" \
    "https://storage.googleapis.com/my-bucket/dog-pic.jpeg"

Os uploads de solicitação única da API XML também aceitam o cabeçalho Content-MD5 HTTP padrão. Para mais detalhes, consulte a especificação Content-MD5.

Uploads de várias partes da API XML

Para uploads de várias partes da API XML, é possível especificar um checksum para cada parte do upload. Para especificar um checksum individual para uma parte do upload, inclua o cabeçalho x-goog-hash na solicitação dessa parte específica.

Exemplo:

PUT /dog-pic.jpeg?partNumber=1&uploadId=ABgVH8 HTTP/1.1
Host: my-bucket.storage.googleapis.com
Content-Length: 1000000
x-goog-hash: crc32c=n03x6A==

Somente as somas de verificação CRC32C podem ser usadas para verificar a integridade de uploads de várias partes da API XML. Não há suporte para checksums MD5.

Uploads de gRPC

Ao fazer upload de objetos usando o gRPC, é possível especificar checksums no nível do objeto na primeira ou na última mensagem WriteObject de qualquer solicitação de upload, seja um upload único ou um upload retomável.

Além disso, o gRPC é compatível com checksums por mensagem. Cada mensagem WriteObject contém blocos de dados de até 2 MiB, e cada bloco pode incluir o próprio checksum. É possível especificar checksums por mensagem em vez de ou junto com um checksum no nível do objeto.

Uploads compostos paralelos

No caso de uploads compostos paralelos, execute uma verificação de integridade para cada upload de componente e, em seguida, use as condições prévias com as solicitações de composição para proteção contra disputas. As solicitações de composição não recebem validação do lado do servidor. Portanto, realize a validação do lado do cliente no novo objeto composto se quiser uma verificação de integridade de ponta a ponta.

Cópias e regravações da Google Cloud CLI

Na CLI gcloud, os dados copiados de ou para um bucket do Cloud Storage são validados automaticamente. Para os comandos cp, mv e rsync, a CLI gcloud usa checksums MD5 ou CRC32C para determinar se há uma diferença entre a versão de um objeto encontrado na origem e a versão encontrada no destino. Quando o checksum dos dados de origem não corresponde ao checksum dos dados de destino, a CLI gcloud 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 objeto, e os objetos inválidos ficam visíveis por um a três segundos antes de serem identificados e excluídos. Além disso, a CLI gcloud pode 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 para especificar um hash MD5.

A CLI do Google Cloud ignora a flag --content-md5 para objetos que não têm um hash MD5.

Detecção de mudanças para rsync

O comando gcloud storage rsync compara as somas de verificação nos seguintes cenários para determinar se uma transferência deve ser ignorada:

  • A origem e o destino são buckets do Cloud Storage, e o objeto tem um checksum MD5 ou CRC32C em ambos os buckets.

  • O objeto não tem um horário de modificação do arquivo (mtime) na origem ou destino.

Nos casos em que um objeto tem um valor mtime na origem e no destino, como quando a origem e o destino são sistemas de arquivos, o comando rsync compara o tamanho do objeto e o valor mtime, em vez de usar checksums. Da mesma forma, se a origem for um bucket e o destino for um sistema de arquivos local, o comando rsync usará o horário de criação do objeto de origem como substituto de mtime, e o comando não usa checksums.

Se mtime e as somas de verificação não estiverem disponíveis, o rsync só vai comparar os tamanhos dos arquivos ao determinar se há uma mudança entre a versão de origem de um objeto e a versão de destino. Por exemplo, nem mtime nem as somas de verificação estão disponíveis ao comparar objetos compostos com objetos em um provedor de nuvem que não oferece suporte a CRC32C, porque objetos compostos não têm checksums MD5.

Validação do lado do cliente para gravações de dados

É possível realizar uma validação do lado do cliente de seus envios emitindo uma solicitação para os metadados do objeto enviado, comparando o valor de hash do objeto enviado com o valor esperado 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.

A tabela a seguir contém a versão mínima de cada cliente do Cloud Storage que oferece suporte a checksums de gravação de objetos.

Cliente Versão compatível com checksums de gravação de objetos
Biblioteca de cliente C++ do Cloud Storage 2.46 e mais recentes
Biblioteca de cliente do Cloud Storage para Go 1.60.0 e mais recentes
Biblioteca de cliente do Cloud Storage para Java 2.62 e mais recentes
Biblioteca de cliente do Cloud Storage para Node.js 7.19.0 e versões mais recentes
Biblioteca de cliente do Cloud Storage para PHP 1.51.0 e mais recentes
Biblioteca de cliente do Cloud Storage para Python 3.7.0 e mais recentes
Biblioteca de cliente do Cloud Storage para Ruby 1.60.0
Biblioteca de cliente do Cloud Storage para .NET 2.3.0 e mais recentes. Recomendamos a versão 4.15.0, que oferece validação de checksum no servidor.
Conector do Cloud Storage
  • 3.0.18 e versões mais recentes para o conector do Cloud Storage 3.0.x
  • 3.1.14 e versões mais recentes para o conector do Cloud Storage 3.1.x
  • 4.0.3 e versões mais recentes para o conector do Cloud Storage 4.0.x
Cloud Storage FUSE. 3.8.0 e mais recentes
CLI do Google Cloud

Checksums para leituras e downloads de dados

Para leituras e downloads de objetos, o servidor envia o objeto com o checksum armazenado na resposta. O cliente calcula o próprio checksum do arquivo lido ou baixado com base nos bytes recebidos e compara os dois checksums para verificar a integridade dos dados.

Validação do lado do cliente para leituras e downloads

Por padrão, todos os SDKs da biblioteca de cliente do Cloud Storage são compatíveis com o cálculo de checksums para downloads e leituras de objetos. A tabela a seguir contém informações sobre como desativar o download de objetos ou ler checksums para cada SDK da biblioteca de cliente.

Biblioteca de cliente Instruções sobre como desativar as somas de verificação de leitura ou download de objetos
Biblioteca de cliente C++ do Cloud Storage Na biblioteca de cliente C++, desative a verificação de checksum definindo DownloadChecksumValidationOption como o valor ChecksumAlgorithm::kNone.
Biblioteca de cliente do Cloud Storage para Go Na biblioteca de cliente do Go, desative a verificação de checksum fornecendo opções de leitor na inicialização. Transmita WithDisableReaderChecksum() ao chamar NewReader ou transmita WithDisableMRDReadChecksum() ao chamar NewMultiRangeDownloader.
Biblioteca de cliente do Cloud Storage para Java Para desativar a validação interna de checksum CRC32C em caminhos de leitura na biblioteca de cliente Java, transmita a propriedade do sistema JVM -Dcom.google.cloud.storage.Hasher.read=disabled, que desativa o hasher interno para leituras. Se você quiser desativar a soma de verificação globalmente em leituras e gravações, use -Dcom.google.cloud.storage.Hasher.default=disabled.
Biblioteca de cliente do Cloud Storage para Node.js Na biblioteca de cliente do Node.js, desative a validação de checksum transmitindo { validation: false } no objeto de opção de configuração fornecido para chamadas de método de download.
Biblioteca de cliente do Cloud Storage para PHP Na biblioteca de cliente do PHP, desative a validação de checksum nos caminhos de leitura das APIs JSON e API XML transmitindo 'validate' => false ou 'validate' => 'none' dentro da matriz de opções associativas ($options['validate']) ao chamar métodos de download.
Biblioteca de cliente do Cloud Storage para Python Na biblioteca de cliente do Python, a desativação da verificação de checksum depende do transporte do cliente: para o cliente JSON, transmita checksum=None (compatível com métodos como download_to_file), enquanto para o cliente gRPC, defina enable_checksum=False.
Biblioteca de cliente do Cloud Storage para Ruby Na biblioteca de cliente do Ruby, desative a verificação de checksum transmitindo argumentos de palavra-chave (checksum: ou verify:) diretamente para métodos de download, especificamente definindo verify: none ou verify: false.
Biblioteca de cliente do Cloud Storage para .NET Na biblioteca de cliente .NET, desative a verificação de checksum definindo a propriedade ChecksumValidation como DownloadValidationMode.Never no objeto DownloadObjectOptions transmitido para chamadas de método de download.

Como realizar verificações de integridade de dados em objetos que foram baixados ou lidos

Em alguns casos, o aplicativo pode precisar calcular de forma independente o checksum do arquivo que foi baixado ou lido usando os bytes recebidos e compará-lo com o hash fornecido pelo servidor para verificar a integridade dos dados.

Para realizar uma verificação de integridade dos dados baixados, calcule o checksum conforme os dados são recebidos e compare os resultados com o checksum fornecido pelo servidor.

As somas de verificação do servidor são baseadas no objeto completo, já que são armazenadas no Cloud Storage, ou seja, os seguintes tipos de downloads não podem ser validados usando as somas de verificação fornecidas pelo servidor:

  • Downloads que passam por transcodificação descompressiva: a soma de verificação fornecida pelo servidor representa o objeto em seu estado compactado, enquanto a compactação dos dados veiculados é removida e, consequentemente, tem um valor de soma de verificação diferente.

  • Uma resposta que contém somente uma parte dos dados do objeto: esse tipo de resposta ocorre para solicitações Range.

    As leituras de intervalo do gRPC são uma exceção a esse marcador e oferecem suporte à validação de ponta a ponta. Nas leituras por intervalo do gRPC, o Cloud Storage valida os dados incluindo um checksum CRC32C exclusivo em cada bloco de resposta individual de um stream, o que permite que o cliente verifique instantaneamente se o bloco de dados específico não foi corrompido em trânsito. Para uma validação mais ampla, o stream também fornece o checksum completo do objeto, que os clientes avançados podem usar para calcular um total contínuo e verificar a integridade do arquivo maior.

    Se o aplicativo precisar ler intervalos de objetos em vez de objetos completos de uma só vez, recomendamos usar o gRPC. Caso contrário, recomendamos usar solicitações de intervalo apenas para reiniciar o download de um objeto inteiro após o último deslocamento recebido, em que é possível calcular e validar o checksum após a conclusão do download.

Ao validar o download, uma incompatibilidade entre a soma de verificação calculada e a fornecida pelo servidor indica que os dados foram corrompidos em trânsito. Nesses casos, descarte os dados corrompidos e use a lógica de repetição recomendada para repetir a solicitação.

A seguir