Using gRPC with Cloud KMS

If you are using manually created gRPC libraries to make calls to Cloud Key Management Service, you must specify a x-google-request-params value in the metadata, or header, of the call. The proper use of x-google-request-params will route the call to the appropriate region for your Cloud KMS resources.

Set the x-google-request-params value to a field in the method's request as shown in the following table.

Method Request field
AsymmetricDecrypt AsymmetricDecryptRequest.name
AsymmetricSign AsymmetricSignRequest.name
CreateCryptoKey CreateCryptoKeyRequest.parent
CreateCryptoKeyVersion CreateCryptoKeyVersionRequest.parent
CreateKeyRing CreateKeyRingRequest.parent
Decrypt DecryptRequest.name
DestroyCryptoKeyVersion DestroyCryptoKeyVersionRequest.name
Encrypt EncryptRequest.name
GetCryptoKey GetCryptoKeyRequest.name
GetCryptoKeyVersion GetCryptoKeyVersionRequest.name
GetKeyRing GetKeyRingRequest.name
GetPublicKey GetPublicKeyRequest.name
ListCryptoKeyVersions ListCryptoKeyVersionsRequest.parent
ListCryptoKeys ListCryptoKeysRequest.parent
ListKeyRings ListKeyRingsRequest.parent
RestoreCryptoKeyVersion RestoreCryptoKeyVersionRequest.name
UpdateCryptoKey UpdateCryptoKeyRequest.crypto_key.name
UpdateCryptoKeyPrimaryVersion UpdateCryptoKeyPrimaryVersionRequest.name
UpdateCryptoKeyVersion UpdateCryptoKeyVersionRequest.crypto_key_version.name

Setting the request field

The following examples show where to specify the resource name in various methods. Replace the text styled as place-holder with the actual values used in your Cloud KMS resource IDs.

Decrypt example

If you are making a call to Decrypt, you need to populate the following fields in your request:

name: 'projects/project-id/locations/location/keyRings/key-ring/cryptoKeys/key-name/'
ciphertext: 'iQALWM/r6alAxQm0VQe3...'

The value assigned to the name field is the resource name of your CryptoKey. To properly route the call, you must also include this resource name in the call metadata, in the following form:

x-goog-request-params: 'name=projects/project-id/locations/location/keyRings/key-ring/cryptoKeys/key-name/'

CreateKeyRing example

If you are making a call to CreateKeyRing, you need to populate the following fields in your request:

parent: 'projects/project-id/locations/location/'
key_ring_id: 'myKeyRing'
...

The call metadata also needs to contain the parent resource name:

x-goog-request-params: 'parent=projects/project-id/locations/location/'

UpdateCryptoKey example

If you are making a call to UpdateCryptoKey, you need to populate the following fields in your request:

name: 'projects/project-id/locations/location/keyRings/key-ring/cryptoKeys/key-name/'
field_mask: ...

The metadata also needs to contain the name resource name. Note the format uses crypto_key.name=, not name=:

x-goog-request-params: 'crypto_key.name=projects/project-id/locations/location/keyRings/key-ring/cryptoKeys/key-name/'

Adding metadata using C++

If you are using C++, call ClientContext::AddMetadata before making your RPC call to add the appropriate information to the call metadata.

For example, if you are adding metadata for a call to Decrypt:

context.AddMetadata("x-goog-request-params",
                    "name=projects/project-id/locations/location/keyRings/key-ring-name/cryptoKeys/key-name/");

You can then pass the context to your method call as usual, along with your request and response protocol buffers.