Data integrity assurance

This topic describes how to use checksums to maintain and verify the integrity of your secret's data when adding and accessing secret versions.

When you add a secret version, you have the option to pass a CRC32C checksum with the data, which is then verified by Secret Manager to ensure data integrity.

The checksum should be encoded in decimal format, to match its int64 encoding in SecretPayload. The returned SecretVersion indicates whether the checksum has been received by the server.

API

These examples use curl to demonstrate using the API. You can generate access tokens with gcloud auth print-access-token. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

With secret data stored in a data file, calculate the checksum, using gsutil hash. Checksum must be converted to decimal format; it is encoded as int64 in SecretPayload proto. 

$ gsutil hash -c -h "/path/to/file.txt"

With secret data passed on the command line, calculate the checksum as follows: 

$ gsutil hash -c -h cat <(echo ${SECRET_DATA})

Base64-encode the secret data and save it as a shell variable.

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

Invoke the API using 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}}"

When the secret version is accessed, the returned SecretPayload contains the data along with its checksum. Sample response:

{
  "name": "projects/123/secrets/my_secret/versions/2",
  "payload": {
    "data": "YQo=",
    "dataCrc32c": "163439259"
  }
}

In the console , when you add a secret version, the checksum is automatically calculated when you enter a value for the secret.

Secret versions encrypted with customer-managed encryption keys (CMEK) and created prior to July 16, 2021 do not have checksums stored, so a checksum is not returned when they are accessed.

What's next