Method: cryptoKeyVersions.macVerify

Full name: projects.locations.keyRings.cryptoKeys.cryptoKeyVersions.macVerify

Verifies MAC tag using a CryptoKeyVersion with CryptoKey.purpose MAC, and returns a response that indicates whether or not the verification was successful.

HTTP request

POST https://cloudkms.googleapis.com/v1/{name=projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*}:macVerify

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The resource name of the CryptoKeyVersion to use for verification.

Authorization requires the following IAM permission on the specified resource name:

  • cloudkms.cryptoKeyVersions.useToVerify

Request body

The request body contains data with the following structure:

JSON representation
{
  "data": string,
  "dataCrc32c": string,
  "mac": string,
  "macCrc32c": string
}
Fields
data

string (bytes format)

Required. The data used previously as a MacSignRequest.data to generate the MAC tag.

A base64-encoded string.

dataCrc32c

string (Int64Value format)

Optional. An optional CRC32C checksum of the MacVerifyRequest.data. If specified, KeyManagementService will verify the integrity of the received MacVerifyRequest.data using this checksum. KeyManagementService will report an error if the checksum verification fails. If you receive a checksum error, your client should verify that CRC32C(MacVerifyRequest.data) is equal to MacVerifyRequest.data_crc32c, and if so, perform a limited number of retries. A persistent mismatch may indicate an issue in your computation of the CRC32C checksum. Note: This field is defined as int64 for reasons of compatibility across different languages. However, it is a non-negative integer, which will never exceed 2^32-1, and can be safely downconverted to uint32 in languages that support this type.

mac

string (bytes format)

Required. The signature to verify.

A base64-encoded string.

macCrc32c

string (Int64Value format)

Optional. An optional CRC32C checksum of the MacVerifyRequest.mac. If specified, KeyManagementService will verify the integrity of the received MacVerifyRequest.mac using this checksum. KeyManagementService will report an error if the checksum verification fails. If you receive a checksum error, your client should verify that CRC32C([MacVerifyRequest.tag][]) is equal to MacVerifyRequest.mac_crc32c, and if so, perform a limited number of retries. A persistent mismatch may indicate an issue in your computation of the CRC32C checksum. Note: This field is defined as int64 for reasons of compatibility across different languages. However, it is a non-negative integer, which will never exceed 2^32-1, and can be safely downconverted to uint32 in languages that support this type.

Response body

If successful, the response body contains data with the following structure:

Response message for KeyManagementService.MacVerify.

JSON representation
{
  "name": string,
  "success": boolean,
  "verifiedDataCrc32c": boolean,
  "verifiedMacCrc32c": boolean,
  "verifiedSuccessIntegrity": boolean,
  "protectionLevel": enum (ProtectionLevel)
}
Fields
name

string

The resource name of the CryptoKeyVersion used for verification. Check this field to verify that the intended resource was used for verification.

success

boolean

This field indicates whether or not the verification operation for MacVerifyRequest.mac over MacVerifyRequest.data was successful.

verifiedDataCrc32c

boolean

Integrity verification field. A flag indicating whether MacVerifyRequest.data_crc32c was received by KeyManagementService and used for the integrity verification of the data. A false value of this field indicates either that MacVerifyRequest.data_crc32c was left unset or that it was not delivered to KeyManagementService. If you've set MacVerifyRequest.data_crc32c but this field is still false, discard the response and perform a limited number of retries.

verifiedMacCrc32c

boolean

Integrity verification field. A flag indicating whether MacVerifyRequest.mac_crc32c was received by KeyManagementService and used for the integrity verification of the data. A false value of this field indicates either that MacVerifyRequest.mac_crc32c was left unset or that it was not delivered to KeyManagementService. If you've set MacVerifyRequest.mac_crc32c but this field is still false, discard the response and perform a limited number of retries.

verifiedSuccessIntegrity

boolean

Integrity verification field. This value is used for the integrity verification of [MacVerifyResponse.success]. If the value of this field contradicts the value of [MacVerifyResponse.success], discard the response and perform a limited number of retries.

protectionLevel

enum (ProtectionLevel)

The ProtectionLevel of the CryptoKeyVersion used for verification.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloudkms
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.