Encrypting and decrypting data with a symmetric key

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

Create a key ring and create a key .
Ensure the user that is calling the encrypt and decrypt methods has the cloudkms.cryptoKeyVersions.useToEncrypt and cloudkms.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 , or roles/cloudkms.cryptoKeyEncrypterDecrypter IAM roles for that key. The roles/cloudkms.admin role does notprovide 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 .

  using 
  
  Google.Cloud.Kms.V1 
 
 ; 
 using 
  
  Google.Protobuf 
 
 ; 
 using 
  
 System.Text 
 ; 
 public 
  
 class 
  
 EncryptSymmetricSample 
 { 
  
 public 
  
 byte 
 [] 
  
 EncryptSymmetric 
 ( 
  
 string 
  
 projectId 
  
 = 
  
 "my-project" 
 , 
  
 string 
  
 locationId 
  
 = 
  
 "us-east1" 
 , 
  
 string 
  
 keyRingId 
  
 = 
  
 "my-key-ring" 
 , 
  
 string 
  
 keyId 
  
 = 
  
 "my-key" 
 , 
  
 string 
  
 message 
  
 = 
  
 "Sample message" 
 ) 
  
 { 
  
 // Create the client. 
  
  KeyManagementServiceClient 
 
  
 client 
  
 = 
  
  KeyManagementServiceClient 
 
 . 
  Create 
 
 (); 
  
 // Build the key name. 
  
  CryptoKeyName 
 
  
 keyName 
  
 = 
  
 new 
  
  CryptoKeyName 
 
 ( 
 projectId 
 , 
  
 locationId 
 , 
  
 keyRingId 
 , 
  
 keyId 
 ); 
  
 // Convert the message into bytes. Cryptographic plaintexts and 
  
 // ciphertexts are always byte arrays. 
  
 byte 
 [] 
  
 plaintext 
  
 = 
  
 Encoding 
 . 
 UTF8 
 . 
 GetBytes 
 ( 
 message 
 ); 
  
 // Call the API. 
  
  EncryptResponse 
 
  
 result 
  
 = 
  
 client 
 . 
  Encrypt 
 
 ( 
 keyName 
 , 
  
  ByteString 
 
 . 
  CopyFrom 
 
 ( 
 plaintext 
 )); 
  
 // Return the ciphertext. 
  
 return 
  
 result 
 . 
  Ciphertext 
 
 . 
 ToByteArray 
 (); 
  
 } 
 }

Go

To run this code, first set up a Go development environment and install the Cloud KMS Go SDK .

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "hash/crc32" 
  
 "io" 
  
 kms 
  
 "cloud.google.com/go/kms/apiv1" 
  
 "cloud.google.com/go/kms/apiv1/kmspb" 
  
 "google.golang.org/protobuf/types/known/wrapperspb" 
 ) 
 // encryptSymmetric encrypts the input plaintext with the specified symmetric 
 // Cloud KMS key. 
 func 
  
 encryptSymmetric 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 name 
  
 string 
 , 
  
 message 
  
 string 
 ) 
  
 error 
  
 { 
  
 // name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key" 
  
 // message := "Sample message" 
  
 // Create the client. 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 kms 
 . 
  NewKeyManagementClient 
 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "failed to create kms client: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 // Convert the message into bytes. Cryptographic plaintexts and 
  
 // ciphertexts are always byte arrays. 
  
 plaintext 
  
 := 
  
 [] 
 byte 
 ( 
 message 
 ) 
  
 // Optional but recommended: Compute plaintext's CRC32C. 
  
 crc32c 
  
 := 
  
 func 
 ( 
 data 
  
 [] 
 byte 
 ) 
  
 uint32 
  
 { 
  
 t 
  
 := 
  
 crc32 
 . 
 MakeTable 
 ( 
 crc32 
 . 
 Castagnoli 
 ) 
  
 return 
  
 crc32 
 . 
 Checksum 
 ( 
 data 
 , 
  
 t 
 ) 
  
 } 
  
 plaintextCRC32C 
  
 := 
  
 crc32c 
 ( 
 plaintext 
 ) 
  
 // Build the request. 
  
 req 
  
 := 
  
& kmspb 
 . 
 EncryptRequest 
 { 
  
 Name 
 : 
  
 name 
 , 
  
 Plaintext 
 : 
  
 plaintext 
 , 
  
 PlaintextCrc32C 
 : 
  
 wrapperspb 
 . 
 Int64 
 ( 
 int64 
 ( 
 plaintextCRC32C 
 )), 
  
 } 
  
 // Call the API. 
  
 result 
 , 
  
 err 
  
 := 
  
 client 
 . 
 Encrypt 
 ( 
 ctx 
 , 
  
 req 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "failed to encrypt: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 // Optional, but recommended: perform integrity verification on result. 
  
 // For more details on ensuring E2E in-transit integrity to and from Cloud KMS visit: 
  
 // https://cloud.google.com/kms/docs/data-integrity-guidelines 
  
 if 
  
 result 
 . 
 VerifiedPlaintextCrc32C 
  
 == 
  
 false 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Encrypt: request corrupted in-transit" 
 ) 
  
 } 
  
 if 
  
 int64 
 ( 
 crc32c 
 ( 
 result 
 . 
 Ciphertext 
 )) 
  
 != 
  
 result 
 . 
 CiphertextCrc32C 
 . 
 Value 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Encrypt: response corrupted in-transit" 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Encrypted ciphertext: %s" 
 , 
  
 result 
 . 
 Ciphertext 
 ) 
  
 return 
  
 nil 
 }

Java

To run this code, first set up a Java development environment and install the Cloud KMS Java SDK .

  import 
  
 com.google.cloud.kms.v1. CryptoKeyName 
 
 ; 
 import 
  
 com.google.cloud.kms.v1. EncryptResponse 
 
 ; 
 import 
  
 com.google.cloud.kms.v1. KeyManagementServiceClient 
 
 ; 
 import 
  
 com.google.protobuf. ByteString 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 public 
  
 class 
 EncryptSymmetric 
  
 { 
  
 public 
  
 void 
  
 encryptSymmetric 
 () 
  
 throws 
  
 IOException 
  
 { 
  
 // TODO(developer): Replace these variables before running the sample. 
  
 String 
  
 projectId 
  
 = 
  
 "your-project-id" 
 ; 
  
 String 
  
 locationId 
  
 = 
  
 "us-east1" 
 ; 
  
 String 
  
 keyRingId 
  
 = 
  
 "my-key-ring" 
 ; 
  
 String 
  
 keyId 
  
 = 
  
 "my-key" 
 ; 
  
 String 
  
 plaintext 
  
 = 
  
 "Plaintext to encrypt" 
 ; 
  
 encryptSymmetric 
 ( 
 projectId 
 , 
  
 locationId 
 , 
  
 keyRingId 
 , 
  
 keyId 
 , 
  
 plaintext 
 ); 
  
 } 
  
 // Encrypt data with a given key. 
  
 public 
  
 void 
  
 encryptSymmetric 
 ( 
  
 String 
  
 projectId 
 , 
  
 String 
  
 locationId 
 , 
  
 String 
  
 keyRingId 
 , 
  
 String 
  
 keyId 
 , 
  
 String 
  
 plaintext 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 // Initialize client that will be used to send requests. This client only 
  
 // needs to be created once, and can be reused for multiple requests. After 
  
 // completing all of your requests, call the "close" method on the client to 
  
 // safely clean up any remaining background resources. 
  
 try 
  
 ( 
  KeyManagementServiceClient 
 
  
 client 
  
 = 
  
  KeyManagementServiceClient 
 
 . 
 create 
 ()) 
  
 { 
  
 // Build the key version name from the project, location, key ring, key, 
  
 // and key version. 
  
  CryptoKeyName 
 
  
 keyVersionName 
  
 = 
  
  CryptoKeyName 
 
 . 
 of 
 ( 
 projectId 
 , 
  
 locationId 
 , 
  
 keyRingId 
 , 
  
 keyId 
 ); 
  
 // Encrypt the plaintext. 
  
  EncryptResponse 
 
  
 response 
  
 = 
  
 client 
 . 
 encrypt 
 ( 
 keyVersionName 
 , 
  
  ByteString 
 
 . 
  copyFromUtf8 
 
 ( 
 plaintext 
 )); 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Ciphertext: %s%n" 
 , 
  
 response 
 . 
  getCiphertext 
 
 (). 
 toStringUtf8 
 ()); 
  
 } 
  
 } 
 }

Node.js

To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK .

  // 
 // TODO(developer): Uncomment these variables before running the sample. 
 // 
 // const projectId = 'my-project'; 
 // const locationId = 'us-east1'; 
 // const keyRingId = 'my-key-ring'; 
 // const keyId = 'my-key'; 
 // const plaintextBuffer = Buffer.from('...'); 
 // Imports the Cloud KMS library 
 const 
  
 { 
 KeyManagementServiceClient 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/kms 
' 
 ); 
 // Instantiates a client 
 const 
  
 client 
  
 = 
  
 new 
  
  KeyManagementServiceClient 
 
 (); 
 // Build the key name 
 const 
  
 keyName 
  
 = 
  
 client 
 . 
 cryptoKeyPath 
 ( 
 projectId 
 , 
  
 locationId 
 , 
  
 keyRingId 
 , 
  
 keyId 
 ); 
 // Optional, but recommended: compute plaintext's CRC32C. 
 const 
  
 crc32c 
  
 = 
  
 require 
 ( 
 'fast-crc32c' 
 ); 
 const 
  
 plaintextCrc32c 
  
 = 
  
 crc32c 
 . 
 calculate 
 ( 
 plaintextBuffer 
 ); 
 async 
  
 function 
  
 encryptSymmetric 
 () 
  
 { 
  
 const 
  
 [ 
 encryptResponse 
 ] 
  
 = 
  
 await 
  
 client 
 . 
 encrypt 
 ({ 
  
 name 
 : 
  
 keyName 
 , 
  
 plaintext 
 : 
  
 plaintextBuffer 
 , 
  
 plaintextCrc32c 
 : 
  
 { 
  
 value 
 : 
  
 plaintextCrc32c 
 , 
  
 }, 
  
 }); 
  
 const 
  
 ciphertext 
  
 = 
  
 encryptResponse 
 . 
 ciphertext 
 ; 
  
 // Optional, but recommended: perform integrity verification on encryptResponse. 
  
 // For more details on ensuring E2E in-transit integrity to and from Cloud KMS visit: 
  
 // https://cloud.google.com/kms/docs/data-integrity-guidelines 
  
 if 
  
 ( 
 ! 
 encryptResponse 
 . 
 verifiedPlaintextCrc32c 
 ) 
  
 { 
  
 throw 
  
 new 
  
 Error 
 ( 
 'Encrypt: request corrupted in-transit' 
 ); 
  
 } 
  
 if 
  
 ( 
  
 crc32c 
 . 
 calculate 
 ( 
 ciphertext 
 ) 
  
 !== 
  
 Number 
 ( 
 encryptResponse 
 . 
 ciphertextCrc32c 
 . 
 value 
 ) 
  
 ) 
  
 { 
  
 throw 
  
 new 
  
 Error 
 ( 
 'Encrypt: response corrupted in-transit' 
 ); 
  
 } 
  
 console 
 . 
 log 
 ( 
 `Ciphertext: 
 ${ 
 ciphertext 
 . 
 toString 
 ( 
 'base64' 
 ) 
 } 
 ` 
 ); 
  
 return 
  
 ciphertext 
 ; 
 } 
 return 
  
 encryptSymmetric 
 ();

PHP

To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP SDK .

  use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient; 
 use Google\Cloud\Kms\V1\EncryptRequest; 
 function encrypt_symmetric( 
 string $projectId = 'my-project', 
 string $locationId = 'us-east1', 
 string $keyRingId = 'my-key-ring', 
 string $keyId = 'my-key', 
 string $plaintext = '...' 
 ) { 
 // Create the Cloud KMS client. 
 $client = new KeyManagementServiceClient(); 
 // Build the key name. 
 $keyName = $client->cryptoKeyName($projectId, $locationId, $keyRingId, $keyId); 
 // Call the API. 
 $encryptRequest = (new EncryptRequest()) 
 ->setName($keyName) 
 ->setPlaintext($plaintext); 
 $encryptResponse = $client->encrypt($encryptRequest); 
 printf('Ciphertext: %s' . PHP_EOL, $encryptResponse->getCiphertext()); 
 return $encryptResponse; 
 }

Python

To run this code, first set up a Python development environment and install the Cloud KMS Python SDK .

  # Import base64 for printing the ciphertext. 
 import 
  
 base64 
 # Import the client library. 
 from 
  
 google.cloud 
  
 import 
 kms 
 def 
  
 encrypt_symmetric 
 ( 
 project_id 
 : 
 str 
 , 
 location_id 
 : 
 str 
 , 
 key_ring_id 
 : 
 str 
 , 
 key_id 
 : 
 str 
 , 
 plaintext 
 : 
 str 
 ) 
 - 
> bytes 
 : 
  
 """ 
 Encrypt plaintext using a symmetric key. 
 Args: 
 project_id (string): Google Cloud project ID (e.g. 'my-project'). 
 location_id (string): Cloud KMS location (e.g. 'us-east1'). 
 key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring'). 
 key_id (string): ID of the key to use (e.g. 'my-key'). 
 plaintext (string): message to encrypt 
 Returns: 
 bytes: Encrypted ciphertext. 
 """ 
 # Convert the plaintext to bytes. 
 plaintext_bytes 
 = 
 plaintext 
 . 
 encode 
 ( 
 "utf-8" 
 ) 
 # Optional, but recommended: compute plaintext's CRC32C. 
 # See crc32c() function defined below. 
 plaintext_crc32c 
 = 
 crc32c 
 ( 
 plaintext_bytes 
 ) 
 # Create the client. 
 client 
 = 
 kms 
 . 
  KeyManagementServiceClient 
 
 () 
 # Build the key name. 
 key_name 
 = 
 client 
 . 
  crypto_key_path 
 
 ( 
 project_id 
 , 
 location_id 
 , 
 key_ring_id 
 , 
 key_id 
 ) 
 # Call the API. 
 encrypt_response 
 = 
 client 
 . 
  encrypt 
 
 ( 
 request 
 = 
 { 
 "name" 
 : 
 key_name 
 , 
 "plaintext" 
 : 
 plaintext_bytes 
 , 
 "plaintext_crc32c" 
 : 
 plaintext_crc32c 
 , 
 } 
 ) 
 # Optional, but recommended: perform integrity verification on encrypt_response. 
 # For more details on ensuring E2E in-transit integrity to and from Cloud KMS visit: 
 # https://cloud.google.com/kms/docs/data-integrity-guidelines 
 if 
 not 
 encrypt_response 
 . 
 verified_plaintext_crc32c 
 : 
 raise 
 Exception 
 ( 
 "The request sent to the server was corrupted in-transit." 
 ) 
 if 
 not 
 encrypt_response 
 . 
 ciphertext_crc32c 
 == 
 crc32c 
 ( 
 encrypt_response 
 . 
 ciphertext 
 ): 
 raise 
 Exception 
 ( 
 "The response received from the server was corrupted in-transit." 
 ) 
 # End integrity verification 
 print 
 ( 
 f 
 "Ciphertext: 
 { 
 base64 
 . 
 b64encode 
 ( 
 encrypt_response 
 . 
 ciphertext 
 ) 
 } 
 " 
 ) 
 return 
 encrypt_response 
 def 
  
 crc32c 
 ( 
 data 
 : 
 bytes 
 ) 
 - 
> int 
 : 
  
 """ 
 Calculates the CRC32C checksum of the provided data. 
 Args: 
 data: the bytes over which the checksum should be calculated. 
 Returns: 
 An int representing the CRC32C checksum of the provided bytes. 
 """ 
 import 
  
 crcmod 
 # type: ignore 
 crc32c_fun 
 = 
 crcmod 
 . 
 predefined 
 . 
 mkPredefinedCrcFun 
 ( 
 "crc-32c" 
 ) 
 return 
 crc32c_fun 
 ( 
 data 
 )

Ruby

To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK .

  # TODO(developer): uncomment these values before running the sample. 
 # project_id  = "my-project" 
 # location_id = "us-east1" 
 # key_ring_id = "my-key-ring" 
 # key_id      = "my-key" 
 # plaintext  = "..." 
 # Require the library. 
 require 
  
 "google/cloud/kms" 
 # Create the client. 
 client 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
  Kms 
 
 . 
  key_management_service 
 
 # Build the parent key name. 
 key_name 
  
 = 
  
 client 
 . 
 crypto_key_path 
  
 project 
 : 
  
 project_id 
 , 
  
 location 
 : 
  
 location_id 
 , 
  
 key_ring 
 : 
  
 key_ring_id 
 , 
  
 crypto_key 
 : 
  
 key_id 
 # Call the API. 
 response 
  
 = 
  
 client 
 . 
 encrypt 
  
 name 
 : 
  
 key_name 
 , 
  
 plaintext 
 : 
  
 plaintext 
 puts 
  
 "Ciphertext: 
 #{ 
 Base64 
 . 
 strict_encode64 
  
 response 
 . 
 ciphertext 
 } 
 "

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.

Tip: You can base64-encode or decode data using the base64 command on Linux or macOS, or the Base64.exe command on Windows. Programming and scripting languages typically include libraries for base64-encoding. For command-line examples, see Base64 Encoding in the Cloud Vision API documentation.

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 the encrypt 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 .

  using 
  
  Google.Cloud.Kms.V1 
 
 ; 
 using 
  
  Google.Protobuf 
 
 ; 
 using 
  
 System.Text 
 ; 
 public 
  
 class 
  
 DecryptSymmetricSample 
 { 
  
 public 
  
 string 
  
 DecryptSymmetric 
 ( 
  
 string 
  
 projectId 
  
 = 
  
 "my-project" 
 , 
  
 string 
  
 locationId 
  
 = 
  
 "us-east1" 
 , 
  
 string 
  
 keyRingId 
  
 = 
  
 "my-key-ring" 
 , 
  
 string 
  
 keyId 
  
 = 
  
 "my-key" 
 , 
  
 byte 
 [] 
  
 ciphertext 
  
 = 
  
 null 
 ) 
  
 { 
  
 // Create the client. 
  
  KeyManagementServiceClient 
 
  
 client 
  
 = 
  
  KeyManagementServiceClient 
 
 . 
  Create 
 
 (); 
  
 // Build the key name. 
  
  CryptoKeyName 
 
  
 keyName 
  
 = 
  
 new 
  
  CryptoKeyName 
 
 ( 
 projectId 
 , 
  
 locationId 
 , 
  
 keyRingId 
 , 
  
 keyId 
 ); 
  
 // Call the API. 
  
  DecryptResponse 
 
  
 result 
  
 = 
  
 client 
 . 
  Decrypt 
 
 ( 
 keyName 
 , 
  
  ByteString 
 
 . 
  CopyFrom 
 
 ( 
 ciphertext 
 )); 
  
 // Get the plaintext. Cryptographic plaintexts and ciphertexts are 
  
 // always byte arrays. 
  
 byte 
 [] 
  
 plaintext 
  
 = 
  
 result 
 . 
  Plaintext 
 
 . 
 ToByteArray 
 (); 
  
 // Return the result. 
  
 return 
  
 Encoding 
 . 
 UTF8 
 . 
 GetString 
 ( 
 plaintext 
 ); 
  
 } 
 }

Go

To run this code, first set up a Go development environment and install the Cloud KMS Go SDK .

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "hash/crc32" 
  
 "io" 
  
 kms 
  
 "cloud.google.com/go/kms/apiv1" 
  
 "cloud.google.com/go/kms/apiv1/kmspb" 
  
 "google.golang.org/protobuf/types/known/wrapperspb" 
 ) 
 // decryptSymmetric will decrypt the input ciphertext bytes using the specified symmetric key. 
 func 
  
 decryptSymmetric 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 name 
  
 string 
 , 
  
 ciphertext 
  
 [] 
 byte 
 ) 
  
 error 
  
 { 
  
 // name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key" 
  
 // ciphertext := []byte("...")  // result of a symmetric encryption call 
  
 // Create the client. 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 kms 
 . 
  NewKeyManagementClient 
 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "failed to create kms client: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 // Optional, but recommended: Compute ciphertext's CRC32C. 
  
 crc32c 
  
 := 
  
 func 
 ( 
 data 
  
 [] 
 byte 
 ) 
  
 uint32 
  
 { 
  
 t 
  
 := 
  
 crc32 
 . 
 MakeTable 
 ( 
 crc32 
 . 
 Castagnoli 
 ) 
  
 return 
  
 crc32 
 . 
 Checksum 
 ( 
 data 
 , 
  
 t 
 ) 
  
 } 
  
 ciphertextCRC32C 
  
 := 
  
 crc32c 
 ( 
 ciphertext 
 ) 
  
 // Build the request. 
  
 req 
  
 := 
  
& kmspb 
 . 
 DecryptRequest 
 { 
  
 Name 
 : 
  
 name 
 , 
  
 Ciphertext 
 : 
  
 ciphertext 
 , 
  
 CiphertextCrc32C 
 : 
  
 wrapperspb 
 . 
 Int64 
 ( 
 int64 
 ( 
 ciphertextCRC32C 
 )), 
  
 } 
  
 // Call the API. 
  
 result 
 , 
  
 err 
  
 := 
  
 client 
 . 
 Decrypt 
 ( 
 ctx 
 , 
  
 req 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "failed to decrypt ciphertext: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 // Optional, but recommended: perform integrity verification on result. 
  
 // For more details on ensuring E2E in-transit integrity to and from Cloud KMS visit: 
  
 // https://cloud.google.com/kms/docs/data-integrity-guidelines 
  
 if 
  
 int64 
 ( 
 crc32c 
 ( 
 result 
 . 
 Plaintext 
 )) 
  
 != 
  
 result 
 . 
 PlaintextCrc32C 
 . 
 Value 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Decrypt: response corrupted in-transit" 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Decrypted plaintext: %s" 
 , 
  
 result 
 . 
 Plaintext 
 ) 
  
 return 
  
 nil 
 }

Java

To run this code, first set up a Java development environment and install the Cloud KMS Java SDK .

  import 
  
 com.google.cloud.kms.v1. CryptoKeyName 
 
 ; 
 import 
  
 com.google.cloud.kms.v1. DecryptResponse 
 
 ; 
 import 
  
 com.google.cloud.kms.v1. KeyManagementServiceClient 
 
 ; 
 import 
  
 com.google.protobuf. ByteString 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 public 
  
 class 
 DecryptSymmetric 
  
 { 
  
 public 
  
 void 
  
 decryptSymmetric 
 () 
  
 throws 
  
 IOException 
  
 { 
  
 // TODO(developer): Replace these variables before running the sample. 
  
 String 
  
 projectId 
  
 = 
  
 "your-project-id" 
 ; 
  
 String 
  
 locationId 
  
 = 
  
 "us-east1" 
 ; 
  
 String 
  
 keyRingId 
  
 = 
  
 "my-key-ring" 
 ; 
  
 String 
  
 keyId 
  
 = 
  
 "my-key" 
 ; 
  
 byte 
 [] 
  
 ciphertext 
  
 = 
  
 null 
 ; 
  
 decryptSymmetric 
 ( 
 projectId 
 , 
  
 locationId 
 , 
  
 keyRingId 
 , 
  
 keyId 
 , 
  
 ciphertext 
 ); 
  
 } 
  
 // Decrypt data that was encrypted using a symmetric key. 
  
 public 
  
 void 
  
 decryptSymmetric 
 ( 
  
 String 
  
 projectId 
 , 
  
 String 
  
 locationId 
 , 
  
 String 
  
 keyRingId 
 , 
  
 String 
  
 keyId 
 , 
  
 byte 
 [] 
  
 ciphertext 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 // Initialize client that will be used to send requests. This client only 
  
 // needs to be created once, and can be reused for multiple requests. After 
  
 // completing all of your requests, call the "close" method on the client to 
  
 // safely clean up any remaining background resources. 
  
 try 
  
 ( 
  KeyManagementServiceClient 
 
  
 client 
  
 = 
  
  KeyManagementServiceClient 
 
 . 
 create 
 ()) 
  
 { 
  
 // Build the key version name from the project, location, key ring, and 
  
 // key. 
  
  CryptoKeyName 
 
  
 keyName 
  
 = 
  
  CryptoKeyName 
 
 . 
 of 
 ( 
 projectId 
 , 
  
 locationId 
 , 
  
 keyRingId 
 , 
  
 keyId 
 ); 
  
 // Decrypt the response. 
  
  DecryptResponse 
 
  
 response 
  
 = 
  
 client 
 . 
 decrypt 
 ( 
 keyName 
 , 
  
  ByteString 
 
 . 
  copyFrom 
 
 ( 
 ciphertext 
 )); 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Plaintext: %s%n" 
 , 
  
 response 
 . 
  getPlaintext 
 
 (). 
 toStringUtf8 
 ()); 
  
 } 
  
 } 
 }

Node.js

To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK .

  // 
 // TODO(developer): Uncomment these variables before running the sample. 
 // 
 // const projectId = 'my-project'; 
 // const locationId = 'us-east1'; 
 // const keyRingId = 'my-key-ring'; 
 // const keyId = 'my-key'; 
 // Ciphertext must be either a Buffer object or a base-64 encoded string 
 // const ciphertext = Buffer.from('...'); 
 // Imports the Cloud KMS library 
 const 
  
 { 
 KeyManagementServiceClient 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/kms 
' 
 ); 
 // Instantiates a client 
 const 
  
 client 
  
 = 
  
 new 
  
  KeyManagementServiceClient 
 
 (); 
 // Build the key name 
 const 
  
 keyName 
  
 = 
  
 client 
 . 
 cryptoKeyPath 
 ( 
 projectId 
 , 
  
 locationId 
 , 
  
 keyRingId 
 , 
  
 keyId 
 ); 
 // Optional, but recommended: compute ciphertext's CRC32C. 
 const 
  
 crc32c 
  
 = 
  
 require 
 ( 
 'fast-crc32c' 
 ); 
 const 
  
 ciphertextCrc32c 
  
 = 
  
 crc32c 
 . 
 calculate 
 ( 
 ciphertext 
 ); 
 async 
  
 function 
  
 decryptSymmetric 
 () 
  
 { 
  
 const 
  
 [ 
 decryptResponse 
 ] 
  
 = 
  
 await 
  
 client 
 . 
 decrypt 
 ({ 
  
 name 
 : 
  
 keyName 
 , 
  
 ciphertext 
 : 
  
 ciphertext 
 , 
  
 ciphertextCrc32c 
 : 
  
 { 
  
 value 
 : 
  
 ciphertextCrc32c 
 , 
  
 }, 
  
 }); 
  
 // Optional, but recommended: perform integrity verification on decryptResponse. 
  
 // For more details on ensuring E2E in-transit integrity to and from Cloud KMS visit: 
  
 // https://cloud.google.com/kms/docs/data-integrity-guidelines 
  
 if 
  
 ( 
  
 crc32c 
 . 
 calculate 
 ( 
 decryptResponse 
 . 
 plaintext 
 ) 
  
 !== 
  
 Number 
 ( 
 decryptResponse 
 . 
 plaintextCrc32c 
 . 
 value 
 ) 
  
 ) 
  
 { 
  
 throw 
  
 new 
  
 Error 
 ( 
 'Decrypt: response corrupted in-transit' 
 ); 
  
 } 
  
 const 
  
 plaintext 
  
 = 
  
 decryptResponse 
 . 
 plaintext 
 . 
 toString 
 (); 
  
 console 
 . 
 log 
 ( 
 `Plaintext: 
 ${ 
 plaintext 
 } 
 ` 
 ); 
  
 return 
  
 plaintext 
 ; 
 } 
 return 
  
 decryptSymmetric 
 ();

PHP

To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP SDK .

  use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient; 
 use Google\Cloud\Kms\V1\DecryptRequest; 
 function decrypt_symmetric( 
 string $projectId = 'my-project', 
 string $locationId = 'us-east1', 
 string $keyRingId = 'my-key-ring', 
 string $keyId = 'my-key', 
 string $ciphertext = '...' 
 ) { 
 // Create the Cloud KMS client. 
 $client = new KeyManagementServiceClient(); 
 // Build the key name. 
 $keyName = $client->cryptoKeyName($projectId, $locationId, $keyRingId, $keyId); 
 // Call the API. 
 $decryptRequest = (new DecryptRequest()) 
 ->setName($keyName) 
 ->setCiphertext($ciphertext); 
 $decryptResponse = $client->decrypt($decryptRequest); 
 printf('Plaintext: %s' . PHP_EOL, $decryptResponse->getPlaintext()); 
 return $decryptResponse; 
 }

Python

To run this code, first set up a Python development environment and install the Cloud KMS Python SDK .

  from 
  
 google.cloud 
  
 import 
 kms 
 def 
  
 decrypt_symmetric 
 ( 
 project_id 
 : 
 str 
 , 
 location_id 
 : 
 str 
 , 
 key_ring_id 
 : 
 str 
 , 
 key_id 
 : 
 str 
 , 
 ciphertext 
 : 
 bytes 
 ) 
 - 
> kms 
 . 
 DecryptResponse 
 : 
  
 """ 
 Decrypt the ciphertext using the symmetric key 
 Args: 
 project_id (string): Google Cloud project ID (e.g. 'my-project'). 
 location_id (string): Cloud KMS location (e.g. 'us-east1'). 
 key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring'). 
 key_id (string): ID of the key to use (e.g. 'my-key'). 
 ciphertext (bytes): Encrypted bytes to decrypt. 
 Returns: 
 DecryptResponse: Response including plaintext. 
 """ 
 # Create the client. 
 client 
 = 
 kms 
 . 
  KeyManagementServiceClient 
 
 () 
 # Build the key name. 
 key_name 
 = 
 client 
 . 
  crypto_key_path 
 
 ( 
 project_id 
 , 
 location_id 
 , 
 key_ring_id 
 , 
 key_id 
 ) 
 # Optional, but recommended: compute ciphertext's CRC32C. 
 # See crc32c() function defined below. 
 ciphertext_crc32c 
 = 
 crc32c 
 ( 
 ciphertext 
 ) 
 # Call the API. 
 decrypt_response 
 = 
 client 
 . 
  decrypt 
 
 ( 
 request 
 = 
 { 
 "name" 
 : 
 key_name 
 , 
 "ciphertext" 
 : 
 ciphertext 
 , 
 "ciphertext_crc32c" 
 : 
 ciphertext_crc32c 
 , 
 } 
 ) 
 # Optional, but recommended: perform integrity verification on decrypt_response. 
 # For more details on ensuring E2E in-transit integrity to and from Cloud KMS visit: 
 # https://cloud.google.com/kms/docs/data-integrity-guidelines 
 if 
 not 
 decrypt_response 
 . 
 plaintext_crc32c 
 == 
 crc32c 
 ( 
 decrypt_response 
 . 
 plaintext 
 ): 
 raise 
 Exception 
 ( 
 "The response received from the server was corrupted in-transit." 
 ) 
 # End integrity verification 
 print 
 ( 
 f 
 "Plaintext: 
 { 
 decrypt_response 
 . 
 plaintext 
 !r} 
 " 
 ) 
 return 
 decrypt_response 
 def 
  
 crc32c 
 ( 
 data 
 : 
 bytes 
 ) 
 - 
> int 
 : 
  
 """ 
 Calculates the CRC32C checksum of the provided data. 
 Args: 
 data: the bytes over which the checksum should be calculated. 
 Returns: 
 An int representing the CRC32C checksum of the provided bytes. 
 """ 
 import 
  
 crcmod 
 # type: ignore 
 crc32c_fun 
 = 
 crcmod 
 . 
 predefined 
 . 
 mkPredefinedCrcFun 
 ( 
 "crc-32c" 
 ) 
 return 
 crc32c_fun 
 ( 
 data 
 )

Ruby

To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK .

  # TODO(developer): uncomment these values before running the sample. 
 # project_id  = "my-project" 
 # location_id = "us-east1" 
 # key_ring_id = "my-key-ring" 
 # key_id      = "my-key" 
 # ciphertext  = "..." 
 # Require the library. 
 require 
  
 "google/cloud/kms" 
 # Create the client. 
 client 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
  Kms 
 
 . 
  key_management_service 
 
 # Build the parent key name. 
 key_name 
  
 = 
  
 client 
 . 
 crypto_key_path 
  
 project 
 : 
  
 project_id 
 , 
  
 location 
 : 
  
 location_id 
 , 
  
 key_ring 
 : 
  
 key_ring_id 
 , 
  
 crypto_key 
 : 
  
 key_id 
 # Call the API. 
 response 
  
 = 
  
 client 
 . 
 decrypt 
  
 name 
 : 
  
 key_name 
 , 
  
 ciphertext 
 : 
  
 ciphertext 
 puts 
  
 "Plaintext: 
 #{ 
 response 
 . 
 plaintext 
 } 
 "

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 .

Encrypting and decrypting data with a symmetric key Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Encrypt

gcloud

C#

Go

Java

Node.js

PHP

Python

Ruby

API

Decrypt

gcloud

C#

Go

Java

Node.js

PHP

Python

Ruby

API

What's next

Encrypting and decrypting data with a symmetric key