This page shows you how to use Cloud Key Management Service (Cloud KMS) to do the following symmetric key operations:
- Encrypt text or binary content (plaintext) by using a Cloud KMS key.
- Decrypt ciphertext that was encrypted with a Cloud KMS key.
If you want to use an asymmetric key for encryption, see Encrypting and decrypting data with an asymmetric key. To learn about raw symmetric encryption, see raw symmetric encryption.
Before you begin
Ensure the user that is calling the encrypt and decrypt methods has the
cloudkms.cryptoKeyVersions.useToEncrypt
andcloudkms.cryptoKeyVersions.useToDecrypt
permissions on the key.One way to permit a user to encrypt or decrypt is to add the user to the
roles/cloudkms.cryptoKeyEncrypter
,roles/cloudkms.cryptoKeyDecrypter
, orroles/cloudkms.cryptoKeyEncrypterDecrypter
IAM roles for that key. Theroles/cloudkms.admin
role does not provide these two permissions. For more information, see Permissions and Roles.
Encrypt
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
gcloud kms encrypt \ --key KEY_NAME \ --keyring KEY_RING \ --location LOCATION \ --plaintext-file FILE_TO_ENCRYPT \ --ciphertext-file ENCRYPTED_OUTPUT
Replace the following:
KEY_NAME
: the name of the key that you want to use for encryption.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location that contains the key ring.FILE_TO_ENCRYPT
: the path to the file that you want to encrypt.ENCRYPTED_OUTPUT
: the path where you want to save the encrypted output.
For information on all flags and possible values, run the command with the
--help
flag.
C#
To run this code, first set up a C# development environment and install the Cloud KMS C# SDK.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
When using JSON and the REST API, content must be base64 encoded before it can be encrypted by Cloud KMS.
To encrypt data, make a POST
request and provide the appropriate project and
key information and specify the base64 encoded text to be encrypted in the
plaintext
field of the request body.
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME:encrypt" \ --request "POST" \ --header "authorization: Bearer TOKEN" \ --header "content-type: application/json" \ --data "{\"plaintext\": \"PLAINTEXT_TO_ENCRYPT\"}"
Replace the following:
PROJECT_ID
: the ID of the project that contains the key ring and key that you want to use for encryption.LOCATION
: the Cloud KMS location that contains the key ring.KEY_RING
: the key ring that contains the key that you want to use for encryption.KEY_NAME
: the name of the key that you want to use for encryption.PLAINTEXT_TO_ENCRYPT
: the plaintext data that you want to encrypt. The plaintext must be base64 encoded before you call theencrypt
method.
Here is an example payload with base64 encoded data:
{ "plaintext": "U3VwZXIgc2VjcmV0IHRleHQgdGhhdCBtdXN0IGJlIGVuY3J5cHRlZAo=", }
Decrypt
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
gcloud kms decrypt \ --key KEY_NAME \ --keyring KEY_RING \ --location LOCATION \ --ciphertext-file FILE_TO_DECRYPT \ --plaintext-file DECRYPTED_OUTPUT
Replace the following:
KEY_NAME
: the name of the key that you want to use for decryption.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location that contains the key ring.FILE_TO_DECRYPT
: the path to the file that you want to decrypt.DECRYPTED_OUTPUT
: the path where you want to save the decrypted output.
For information on all flags and possible values, run the command with the
--help
flag.
C#
To run this code, first set up a C# development environment and install the Cloud KMS C# SDK.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
Decrypted text that is returned in the JSON from Cloud KMS is base64 encoded.
To decrypt encrypted data, make a POST
request and provide the appropriate
project and key information and specify the encrypted text (also known as
ciphertext) to be decrypted in the ciphertext
field of the request body.
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME:decrypt" \ --request "POST" \ --header "authorization: Bearer TOKEN" \ --header "content-type: application/json" \ --data "{\"ciphertext\": \"ENCRYPTED_DATA\"}"
Replace the following:
PROJECT_ID
: the ID of the project that contains the key ring and key that you want to use for decryption.LOCATION
: the Cloud KMS location that contains the key ring.KEY_RING
: the key ring that contains the key that you want to use for decryption.KEY_NAME
: the name of the key that you want to use for decryption.ENCRYPTED_DATA
: the encrypted data that you want to decrypt.
Here is an example payload with base64 encoded data:
{ "ciphertext": "CiQAhMwwBo61cHas7dDgifrUFs5zNzBJ2uZtVFq4ZPEl6fUVT4kSmQ...", }
What's next
- Read more about raw symmetric encryption.
- Read more about envelope encryption.
- Try the Encrypt and decrypt data with Cloud KMS Codelab.