Garantia de integridade dos dados

Esta página descreve como usar checksums para manter e validar a integridade dos dados do seu segredo quando adiciona e acede a versões secretas.

Pense numa soma de verificação como uma impressão digital única para os seus dados. É um código curto gerado a partir dos dados secretos através do algoritmo CRC32C. Se mesmo um único bit nos seus dados secretos mudar, a soma de verificação também muda. Isto permite que o Secret Manager detete modificações ou corrupção acidentais.

O Secret Manager usa somas de verificação das seguintes formas:

  1. Quando adiciona uma versão do Secret:

    • O Secret Manager calcula a soma de verificação CRC32C dos seus dados secretos.

    • Esta soma de verificação é armazenada juntamente com os dados secretos.

  2. Quando acede a uma versão do Secret:

    • O Secret Manager devolve os dados secretos juntamente com a respetiva soma de verificação.

    • Pode usar esta soma de verificação para confirmar que os dados que recebeu são exatamente iguais aos dados armazenados no Secret Manager.

Para garantir que a soma de verificação é compatível com a estrutura SecretPayload, a soma de verificação dos dados secretos tem de ser calculada através do algoritmo CRC32C e codificada como um número inteiro decimal. A resposta SecretVersion inclui um campo que indica se o servidor recebeu e validou com êxito esta soma de verificação.

O exemplo seguinte mostra como funcionam as somas de verificação no Secret Manager:

API

Estes exemplos usam o curl para demonstrar a utilização da API. Pode gerar chaves de acesso com gcloud auth print-access-token. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito cloud-platform.

Com os dados secretos armazenados num ficheiro de dados, calcule a soma de verificação usando gcloud storage hash. A soma de verificação tem de ser convertida para o formato decimal. É codificada como int64 no proto SecretPayload. 

$ gcloud storage hash "/path/to/file.txt" --hex

Com os dados secretos transmitidos na linha de comandos, calcule a soma de verificação da seguinte forma: 

$ gcloud storage hash --hex cat <(echo ${SECRET_DATA})

Codifique os dados secretos em Base64 e guarde-os como uma variável de shell.

$ SECRET_DATA=$(echo "seCr3t" | base64)

Invocar a API através do curl.

$ curl "https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id:addVersion" \
    --request "POST" \
    --header "authorization: Bearer $(gcloud auth print-access-token)" \
    --header "content-type: application/json" \
    --data "{\"payload\": {\"data\": \"${SECRET_DATA}\", \"data_crc32c\": $CHECKSUM}}"

Quando se acede à versão do Secret, o SecretPayload devolvido contém os dados juntamente com a respetiva soma de verificação. Segue-se um exemplo de resposta:

{
  "name": "projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID",
  "payload": {
    "data": "YQo=",
    "dataCrc32c": "163439259"
  }
}

Na consola, quando adiciona uma versão secreta, a soma de verificação é calculada automaticamente quando introduz um valor para o segredo.

As versões secretas encriptadas com chaves de encriptação geridas pelo cliente (CMEK) e criadas antes de 16 de julho de 2021 não têm somas de verificação armazenadas.

O que se segue?