This topic shows you how to do the following symmetric key operations:
- Encrypt text or binary content (plaintext) by using a Cloud Key Management Service key.
- Decrypt ciphertext that was encrypted with a Cloud KMS key.
If instead 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
Create a key ring and a key as described in Creating key rings and keys.
Ensure the user that is calling the encrypt and decrypt methods has the
cloudkms.cryptoKeyVersions.useToEncrypt
andcloudkms.cryptoKeyVersions.useToDecrypt
permissions on the key used to encrypt or decrypt.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. Please note that 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 \ --keyring key-ring \ --location location \ --plaintext-file file-with-data-to-encrypt \ --ciphertext-file file-to-store-encrypted-data
Replace key with the name of the key to use for encryption. Replace key-ring with the name of the key ring where the key is located. Replace location with the Cloud KMS location for the key ring. Replace file-with-data-to-encrypt and file-to-store-encrypted-data with the local file paths for reading the plaintext data and saving 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 base-64 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-name/cryptoKeys/key-name:encrypt" \ --request "POST" \ --header "authorization: Bearer token" \ --header "content-type: application/json" \ --data "{\"plaintext\": \"base64-encoded-input\"}"
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 \ --keyring key-ring \ --location location \ --ciphertext-file file-path-with-encrypted-data \ --plaintext-file file-path-to-store-plaintext
Replace key with the name of the key to use for decryption. Replace key-ring with the name of the key ring where the key will be located. Replace location with the Cloud KMS location for the key ring. Replace file-path-with-encrypted-data and file-path-to-store-plaintext with the local file paths for reading the encrypted data and saving 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 (cipher) text 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-name/cryptoKeys/key-name:decrypt" \ --request "POST" \ --header "authorization: Bearer token" \ --header "content-type: application/json" \ --data "{\"ciphertext\": \"encrypted-content\"}"
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.