Method: cryptoKeyVersions.decapsulate

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

Decapsulates data that was encapsulated with a public key retrieved from cryptoKeyVersions.getPublicKey corresponding to a CryptoKeyVersion with CryptoKey.purpose KEY_ENCAPSULATION.

HTTP request


The URLs use gRPC Transcoding syntax.

Path parameters

Parameters
name

string

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

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

  • cloudkms.cryptoKeyVersions.useToDecapsulate

Request body

The request body contains data with the following structure:

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

string (bytes format)

Required. The ciphertext produced from encapsulation with the named CryptoKeyVersion public key(s).

A base64-encoded string.
ciphertextCrc32c

string (Int64Value format)

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

Response body

Response message for KeyManagementService.Decapsulate.

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

JSON representation 
{
  "name": string,
  "sharedSecret": string,
  "verifiedCiphertextCrc32c": boolean,
  "protectionLevel": enum (ProtectionLevel),
  "sharedSecretCrc32c": string
}
Fields
name

string

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

string (bytes format)

The decapsulated sharedSecret originally encapsulated with the matching public key.

A base64-encoded string.
verifiedCiphertextCrc32c

boolean

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

enum (ProtectionLevel)

The ProtectionLevel of the CryptoKeyVersion used in decapsulation.
sharedSecretCrc32c

string (int64 format)

Integrity verification field. A CRC32C checksum of the returned DecapsulateResponse.shared_secret. An integrity check of DecapsulateResponse.shared_secret can be performed by computing the CRC32C checksum of DecapsulateResponse.shared_secret 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.

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.