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.