Method: cryptoKeys.decrypt

Full name: projects.locations.keyRings.cryptoKeys.decrypt

Decrypts data that was protected by cryptoKeys.encrypt. The CryptoKey.purpose must be ENCRYPT_DECRYPT.

HTTP request

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

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The resource name of the CryptoKey to use for decryption. The server will choose the appropriate version.

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

  • cloudkms.cryptoKeyVersions.useToDecrypt

Request body

The request body contains data with the following structure:

JSON representation
{
  "ciphertext": string,
  "additionalAuthenticatedData": string,
  "ciphertextCrc32c": string,
  "additionalAuthenticatedDataCrc32c": string
}
Fields
ciphertext

string (bytes format)

Required. The encrypted data originally returned in EncryptResponse.ciphertext.

A base64-encoded string.

additionalAuthenticatedData

string (bytes format)

Optional. Optional data that must match the data originally supplied in EncryptRequest.additional_authenticated_data.

A base64-encoded string.

ciphertextCrc32c

string (Int64Value format)

Optional. An optional CRC32C checksum of the DecryptRequest.ciphertext. If specified, KeyManagementService will verify the integrity of the received DecryptRequest.ciphertext 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(DecryptRequest.ciphertext) is equal to DecryptRequest.ciphertext_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.

additionalAuthenticatedDataCrc32c

string (Int64Value format)

Optional. An optional CRC32C checksum of the DecryptRequest.additional_authenticated_data. If specified, KeyManagementService will verify the integrity of the received DecryptRequest.additional_authenticated_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(DecryptRequest.additional_authenticated_data) is equal to DecryptRequest.additional_authenticated_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.

Response body

Response message for KeyManagementService.Decrypt.

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

JSON representation
{
  "plaintext": string,
  "plaintextCrc32c": string,
  "usedPrimary": boolean,
  "protectionLevel": enum (ProtectionLevel)
}
Fields
plaintext

string (bytes format)

The decrypted data originally supplied in EncryptRequest.plaintext.

A base64-encoded string.

plaintextCrc32c

string (Int64Value format)

Integrity verification field. A CRC32C checksum of the returned DecryptResponse.plaintext. An integrity check of DecryptResponse.plaintext can be performed by computing the CRC32C checksum of DecryptResponse.plaintext and comparing your results to this field. Discard the response in case of non-matching checksum values, and perform a limited number of retries. A persistent mismatch may indicate an issue in your computation of the CRC32C checksum. Note: receiving this response message indicates that KeyManagementService is able to successfully decrypt the ciphertext. 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.

usedPrimary

boolean

Whether the Decryption was performed using the primary key version.

protectionLevel

enum (ProtectionLevel)

The ProtectionLevel of the CryptoKeyVersion used in decryption.

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.