Using customer-supplied encryption keys

Go to concepts

This page describes how to use your own encryption key, referred to as a customer-supplied encryption key, with Cloud Storage. For other encryption options in Cloud Storage, see Data Encryption Options.

Generating your own encryption key

There are many ways to generate a Base64-encoded AES-256 encryption key. Here are several examples:

C++

For more information, see the Cloud Storage C++ API reference documentation. 

// Create a pseudo-random number generator (PRNG), this is included for
// demonstration purposes only. You should consult your security team about
// best practices to initialize PRNG. In particular, you should verify that
// the C++ library and operating system provide enough entropy to meet the
// security policies in your organization.

// Use the Mersenne-Twister Engine in this example:
//   https://en.cppreference.com/w/cpp/numeric/random/mersenne_twister_engine
// Any C++ PRNG can be used below, the choice is arbitrary.
using GeneratorType = std::mt19937_64;

// Create the default random device to fetch entropy.
std::random_device rd;

// Compute how much entropy we need to initialize the GeneratorType:
constexpr auto kRequiredEntropyWords =
    GeneratorType::state_size *
    (GeneratorType::word_size / std::numeric_limits<unsigned int>::digits);

// Capture the entropy bits into a vector.
std::vector<std::uint64_t> entropy(kRequiredEntropyWords);
std::generate(entropy.begin(), entropy.end(), [&rd] { return rd(); });

// Create the PRNG with the fetched entropy.
std::seed_seq seed(entropy.begin(), entropy.end());

// initialized with enough entropy such that the encryption keys are not
// predictable. Note that the default constructor for all the generators in
// the C++ standard library produce predictable keys.
std::mt19937_64 gen(seed);

namespace gcs = google::cloud::storage;
gcs::EncryptionKeyData data = gcs::CreateKeyFromGenerator(gen);

std::cout << "Base64 encoded key = " << data.key << "\n"
          << "Base64 encoded SHA256 of key = " << data.sha256 << "\n";

C#

For more information, see the Cloud Storage C# API reference documentation. 


using Google.Cloud.Storage.V1;
using System;

public class GenerateEncryptionKeySample
{
    public string GenerateEncryptionKey()
    {
        var encryptionKey = EncryptionKey.Generate().Base64Key;
        Console.WriteLine($"Generated Base64-encoded AES-256 encryption key: {encryptionKey}");
        return encryptionKey;
    }
}

Go

For more information, see the Cloud Storage Go API reference documentation. 

import (
	"crypto/rand"
	"encoding/base64"
	"fmt"
	"io"
)

// generateEncryptionKey generates a 256 bit (32 byte) AES encryption key and
// prints the base64 representation.
func generateEncryptionKey(w io.Writer) error {
	// This is included for demonstration purposes. You should generate your own
	// key. Please remember that encryption keys should be handled with a
	// comprehensive security policy.
	key := make([]byte, 32)
	if _, err := rand.Read(key); err != nil {
		return fmt.Errorf("rand.Read: %v", err)
	}
	encryptionKey := base64.StdEncoding.EncodeToString(key)
	fmt.Fprintf(w, "Generated base64-encoded encryption key: %v\n", encryptionKey)
	return nil
}

Java

For more information, see the Cloud Storage Java API reference documentation. 

import com.google.common.io.BaseEncoding;
import java.util.Random;

public class GenerateEncryptionKey {
  /**
   * Generates a 256 bit (32 byte) AES encryption key and prints the base64 representation. This is
   * included for demonstration purposes only. You should generate your own key, and consult your
   * security team about best practices. Please remember that encryption keys should be handled with
   * a comprehensive security policy.
   */
  public static void generateEncryptionKey() {
    byte[] key = new byte[32];
    new Random().nextBytes(key);
    String encryptionKey = BaseEncoding.base64().encode(key);

    System.out.println("Generated Base64-encoded AES-256 encryption key: " + encryptionKey);
  }
}

Node.js

For more information, see the Cloud Storage Node.js API reference documentation. 


const crypto = require('crypto');
function generateEncryptionKey() {
  /**
   * Generates a 256 bit (32 byte) AES encryption key and prints the base64
   * representation.
   *
   * This is included for demonstration purposes. You should generate your own
   * key. Please remember that encryption keys should be handled with a
   * comprehensive security policy.
   *
   */
  try {
    const buffer = crypto.randomBytes(32);
    const encodedKey = buffer.toString('base64');
    console.log(`Base 64 encoded encryption key: ${encodedKey}`);

    return encodedKey;
  } catch (err) {
    console.error(err);
  }
}
generateEncryptionKey();

PHP

For more information, see the Cloud Storage PHP API reference documentation. 


/**
 * Generate a base64 encoded encryption key for Google Cloud Storage.
 *
 * @return void
 */
function generate_encryption_key()
{
    $key = random_bytes(32);
    $encodedKey = base64_encode($key);
    printf('Your encryption key: %s' . PHP_EOL, $encodedKey);
}

Python

For more information, see the Cloud Storage Python API reference documentation. 

import base64
import os


def generate_encryption_key():
    """Generates a 256 bit (32 byte) AES encryption key and prints the
    base64 representation.

    This is included for demonstration purposes. You should generate your own
    key. Please remember that encryption keys should be handled with a
    comprehensive security policy.
    """
    key = os.urandom(32)
    encoded_key = base64.b64encode(key).decode("utf-8")

    print("Base 64 encoded encryption key: {}".format(encoded_key))

Ruby

For more information, see the Cloud Storage Ruby API reference documentation. 

def generate_encryption_key
  # Generates a 256 bit (32 byte) AES encryption key and prints the base64 representation.
  #
  # This is included for demonstration purposes. You should generate your own key.
  # Please remember that encryption keys should be handled with a comprehensive security policy.
  require "base64"
  require "openssl"

  encryption_key  = OpenSSL::Cipher.new("aes-256-cfb").encrypt.random_key
  encoded_enc_key = Base64.encode64 encryption_key

  puts "Sample encryption key: #{encoded_enc_key}"
end

Uploading with your encryption key

To use customer-supplied encryption keys to upload an object:

gsutil

  1. Add the following option to the [GSUtil] section of your boto configuration file:

    encryption_key = YOUR_ENCRYPTION_KEY

    where YOUR_ENCRYPTION_KEY is the AES-256 encryption key used to encrypt your object.

  2. Use the gsutil cp command:

    gsutil cp LOCAL_OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME

    Where:

    • LOCAL_OBJECT_LOCATION is the path to the object you are uploading. For example, Desktop/dogs.png.
    • DESTINATION_BUCKET_NAME is the name of the bucket to which you are uploading the object. For example, my-bucket.

Code samples

C++

For more information, see the Cloud Storage C++ API reference documentation. 

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, std::string const& base64_aes256_key) {
  StatusOr<gcs::ObjectMetadata> object_metadata = client.InsertObject(
      bucket_name, object_name, "top secret",
      gcs::EncryptionKey::FromBase64Key(base64_aes256_key));

  if (!object_metadata) {
    throw std::runtime_error(object_metadata.status().message());
  }

  std::cout << "The object " << object_metadata->name()
            << " was created in bucket " << object_metadata->bucket()
            << "\nFull metadata: " << *object_metadata << "\n";
}

C#

For more information, see the Cloud Storage C# API reference documentation. 

private void UploadEncryptedFile(string key, string bucketName,
    string localPath, string objectName = null)
{
    var storage = StorageClient.Create();
    using (var f = File.OpenRead(localPath))
    {
        objectName = objectName ?? Path.GetFileName(localPath);
        storage.UploadObject(bucketName, objectName, null, f,
            new UploadObjectOptions()
            {
                EncryptionKey = EncryptionKey.Create(
                Convert.FromBase64String(key))
            });
        Console.WriteLine($"Uploaded {objectName}.");
    }
}

Go

For more information, see the Cloud Storage Go API reference documentation. 

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// uploadEncryptedFile writes an object using AES-256 encryption key.
func uploadEncryptedFile(w io.Writer, bucket, object string, secretKey []byte) error {
	// bucket := "bucket-name"
	// object := "object-name"
	// secretKey := []byte("secret-key")
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	obj := client.Bucket(bucket).Object(object)

	ctx, cancel := context.WithTimeout(ctx, time.Second*50)
	defer cancel()

	// Encrypt the object's contents.
	wc := obj.Key(secretKey).NewWriter(ctx)
	if _, err := wc.Write([]byte("top secret")); err != nil {
		return fmt.Errorf("Writer.Write: %v", err)
	}
	if err := wc.Close(); err != nil {
		return fmt.Errorf("Writer.Close: %v", err)
	}
	fmt.Fprintf(w, "Uploaded encrypted object %v.\n", object)
	return nil
}

Java

For more information, see the Cloud Storage Java API reference documentation. 

import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;

public class UploadEncryptedObject {
  public static void uploadEncryptedObject(
      String projectId, String bucketName, String objectName, String filePath, String encryptionKey)
      throws IOException {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    // The path to your file to upload
    // String filePath = "path/to/your/file"

    // The key to encrypt the object with
    // String encryptionKey = "TIbv/fjexq+VmtXzAlc63J4z5kFmWJ6NdAPQulQBT7g=";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    BlobId blobId = BlobId.of(bucketName, objectName);
    BlobInfo blobInfo = BlobInfo.newBuilder(blobId).build();
    storage.create(
        blobInfo,
        Files.readAllBytes(Paths.get(filePath)),
        Storage.BlobTargetOption.encryptionKey(encryptionKey));

    System.out.println(
        "File "
            + filePath
            + " uploaded to bucket "
            + bucketName
            + " as "
            + objectName
            + " with supplied encryption key");
  }
}

Node.js

For more information, see the Cloud Storage Node.js API reference documentation. 

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const srcFilename = 'Local file to upload, e.g. ./local/path/to/file.txt';
// const destFilename = 'Remote destination for file, e.g. file_encrypted.txt';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function uploadEncryptedFile() {
  const options = {
    // The path to which the file should be uploaded, e.g. "file_encrypted.txt"
    destination: destFilename,
    // Encrypt the file with a customer-supplied key.
    // See the "Generating your own encryption key" section above.
    encryptionKey: Buffer.from(key, 'base64'),
  };

  // Encrypts and uploads a local file, e.g. "./local/path/to/file.txt".
  // The file will only be retrievable using the key used to upload it.
  await storage.bucket(bucketName).upload(srcFilename, options);

  console.log(
    `File ${srcFilename} uploaded to gs://${bucketName}/${destFilename}.`
  );
}

uploadEncryptedFile().catch(console.error);

PHP

For more information, see the Cloud Storage PHP API reference documentation. 

use Google\Cloud\Storage\StorageClient;

/**
 * Upload an encrypted file.
 *
 * @param string $bucketName the name of your Google Cloud bucket.
 * @param string $objectName the name of your Google Cloud object.
 * @param resource $source the path to the file to upload.
 * @param string $base64EncryptionKey the base64 encoded encryption key.
 *
 * @return void
 */
function upload_encrypted_object($bucketName, $objectName, $source, $base64EncryptionKey)
{
    $storage = new StorageClient();
    $file = fopen($source, 'r');
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->upload($file, [
        'name' => $objectName,
        'encryptionKey' => $base64EncryptionKey,
    ]);
    printf('Uploaded encrypted %s to gs://%s/%s' . PHP_EOL,
        basename($source), $bucketName, $objectName);
}

Python

For more information, see the Cloud Storage Python API reference documentation. 

import base64

from google.cloud import storage


def upload_encrypted_blob(
    bucket_name,
    source_file_name,
    destination_blob_name,
    base64_encryption_key,
):
    """Uploads a file to a Google Cloud Storage bucket using a custom
    encryption key.

    The file will be encrypted by Google Cloud Storage and only
    retrievable using the provided encryption key.
    """

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)

    # Encryption key must be an AES256 key represented as a bytestring with
    # 32 bytes. Since it's passed in as a base64 encoded string, it needs
    # to be decoded.
    encryption_key = base64.b64decode(base64_encryption_key)
    blob = bucket.blob(
        destination_blob_name, encryption_key=encryption_key
    )

    blob.upload_from_filename(source_file_name)

    print(
        "File {} uploaded to {}.".format(
            source_file_name, destination_blob_name
        )
    )

Ruby

For more information, see the Cloud Storage Ruby API reference documentation. 

def upload_encrypted_file bucket_name:, local_file_path:, file_name: nil, encryption_key:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The path to your file to upload
  # local_file_path = "/local/path/to/file.txt"

  # The ID of your GCS object
  # file_name = "your-file-name"

  # The key to encrypt the object with
  # encryption_key = "TIbv/fjexq+VmtXzAlc63J4z5kFmWJ6NdAPQulQBT7g="

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new

  bucket = storage.bucket bucket_name

  file = bucket.create_file local_file_path, file_name, encryption_key: encryption_key

  puts "Uploaded #{file.name} with encryption key"
end

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

  2. Use cURL to call the JSON API with a POST Object request:

    curl -X POST --data-binary @OBJECT \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  -H "Content-Type: OBJECT_CONTENT_TYPE" \
  -H "x-goog-encryption-algorithm: AES256" \
  -H "x-goog-encryption-key: YOUR_ENCRYPTION_KEY" \
  -H "x-goog-encryption-key-sha256: HASH_OF_YOUR_KEY" \
  "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=media&name=OBJECT_NAME"

    Where:

    • OBJECT is the path to the object you are uploading. For example, Desktop/dogs.png.
    • OAUTH2_TOKEN is the access token you generated in Step 1.
    • OBJECT_CONTENT_TYPE is the content type of the object. For example, image/png.
    • YOUR_ENCRYPTION_KEY is the AES-256 key used for encrypting the uploaded object.
    • HASH_OF_YOUR_KEY is the SHA-256 hash for your AES-256 key.
    • BUCKET_NAME is the name of the bucket to which you are uploading the object. For example, my-bucket.
    • OBJECT_NAME is the name of the object you are uploading. For example, pets/dogs.png.

See Encryption request headers for more information on encryption-specific headers.

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

  2. Use cURL to call the XML API with a PUT OBJECT request:

    curl -X -i PUT --data-binary @OBJECT \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  -H "Content-Type: OBJECT_CONTENT_TYPE" \
  -H "x-goog-encryption-algorithm: AES256" \
  -H "x-goog-encryption-key: YOUR_ENCRYPTION_KEY" \
  -H "x-goog-encryption-key-sha256: HASH_OF_YOUR_KEY" \
  "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

    Where:

    • OBJECT is the path to the object you are uploading. For example, Desktop/dogs.png.
    • OAUTH2_TOKEN is the access token you generated in Step 1.
    • OBJECT_CONTENT_TYPE is the content type of the object. For example, image/png.
    • YOUR_ENCRYPTION_KEY is the AES-256 key used for encrypting the uploaded object.
    • HASH_OF_YOUR_KEY is the SHA-256 hash for your AES-256 key.
    • BUCKET_NAME is the name of the bucket to which you are uploading the object. For example, my-bucket.
    • OBJECT_NAME is the name of the object you are uploading. For example, pets/dogs.png.

See Encryption request headers for more information on encryption-specific headers.

Downloading objects you've encrypted

To download an object stored in Cloud Storage that is encrypted with a customer-supplied encryption key:

gsutil

  1. Add the following option to the [GSUtil] section of your boto configuration file:

    decryption_key1 = YOUR_ENCRYPTION_KEY

    where YOUR_ENCRYPTION_KEY is the key used to encrypt the object when it was uploaded.

  2. Use the gsutil cp command:

    gsutil cp gs://BUCKET_NAME/OBJECT_NAME OBJECT_DESTINATION

    Where:

    • BUCKET_NAME is the name of the bucket containing the object you are downloading. For example, my-bucket.
    • OBJECT_NAME is the name of the object you are downloading. For example, pets/dog.png.
    • OBJECT_DESTINATION is the location where you want to save your object. For example, Desktop.

Code samples

C++

For more information, see the Cloud Storage C++ API reference documentation. 

namespace gcs = google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, std::string const& base64_aes256_key) {
  gcs::ObjectReadStream stream =
      client.ReadObject(bucket_name, object_name,
                        gcs::EncryptionKey::FromBase64Key(base64_aes256_key));

  std::string data(std::istreambuf_iterator<char>{stream}, {});
  std::cout << "The object contents are: " << data << "\n";
}

C#

For more information, see the Cloud Storage C# API reference documentation. 


using Google.Cloud.Storage.V1;
using System;
using System.IO;

public class DownloadEncryptedFileSample
{
    public void DownloadEncryptedFile(
        string key = "3eFsTXPvqi3BpT2ipFCGirslh1Jgc6ikjoAu2oQ5JcI=",
        string bucketName = "your-unique-bucket-name",
        string objectName = "my-file-name",
        string localPath = "my-local-path/my-file-name")
    {
        var storage = StorageClient.Create();
        using var outputFile = File.OpenWrite(localPath);
        storage.DownloadObject(bucketName, objectName, outputFile, new DownloadObjectOptions
        {
            EncryptionKey = EncryptionKey.Create(Convert.FromBase64String(key))
        });
        Console.WriteLine($"Downloaded {objectName} to {localPath}.");
    }
}

Go

For more information, see the Cloud Storage Go API reference documentation. 

import (
	"context"
	"fmt"
	"io"
	"io/ioutil"
	"time"

	"cloud.google.com/go/storage"
)

// downloadEncryptedFile reads an encrypted object.
func downloadEncryptedFile(w io.Writer, bucket, object string, secretKey []byte) ([]byte, error) {
	// bucket := "bucket-name"
	// object := "object-name"
	// key := []byte("secret-encryption-key")
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	obj := client.Bucket(bucket).Object(object)

	ctx, cancel := context.WithTimeout(ctx, time.Second*50)
	defer cancel()

	rc, err := obj.Key(secretKey).NewReader(ctx)
	if err != nil {
		return nil, fmt.Errorf("Object(%q).Key(%q).NewReader: %v", object, secretKey, err)
	}
	defer rc.Close()

	data, err := ioutil.ReadAll(rc)
	if err != nil {
		return nil, fmt.Errorf("ioutil.ReadAll: %v", err)
	}
	fmt.Fprintf(w, "File %v downloaded with encryption key.\n", object)
	return data, nil
}

Java

For more information, see the Cloud Storage Java API reference documentation. 

import com.google.cloud.storage.Blob;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.io.IOException;
import java.nio.file.Path;

public class DownloadEncryptedObject {
  public static void downloadEncryptedObject(
      String projectId,
      String bucketName,
      String objectName,
      Path destFilePath,
      String decryptionKey)
      throws IOException {

    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    // The path to which the file should be downloaded
    // Path destFilePath = Paths.get("/local/path/to/file.txt");

    // The Base64 encoded decryption key, which should be the same key originally used to encrypt
    // the object
    // String decryptionKey = "TIbv/fjexq+VmtXzAlc63J4z5kFmWJ6NdAPQulQBT7g=";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();

    Blob blob = storage.get(bucketName, objectName);
    blob.downloadTo(destFilePath, Blob.BlobSourceOption.decryptionKey(decryptionKey));

    System.out.println(
        "Downloaded object "
            + objectName
            + " from bucket name "
            + bucketName
            + " to "
            + destFilePath
            + " using customer-supplied encryption key");
  }
}

Node.js

For more information, see the Cloud Storage Node.js API reference documentation. 

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const srcFilename = 'File to download, e.g. file_encrypted.txt';
// const destFilename = 'Local destination for file, e.g. ./file.txt';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function downloadEncryptedFile() {
  const options = {
    // The path to which the file should be downloaded, e.g. "./file.txt"
    destination: destFilename,
  };

  // Descrypts and downloads the file. This can only be done with the key used
  // to encrypt and upload the file.
  await storage
    .bucket(bucketName)
    .file(srcFilename)
    .setEncryptionKey(Buffer.from(key, 'base64'))
    .download(options);

  console.log(`File ${srcFilename} downloaded to ${destFilename}.`);
}

downloadEncryptedFile().catch(console.error);

PHP

For more information, see the Cloud Storage PHP API reference documentation. 

use Google\Cloud\Storage\StorageClient;

/**
 * Download an encrypted file
 *
 * @param string $bucketName the name of your Google Cloud bucket.
 * @param string $objectName the name of your Google Cloud object.
 * @param string $destination the local destination to save the encrypted file.
 * @param string $base64EncryptionKey the base64 encoded encryption key.
 *
 * @return void
 */
function download_encrypted_object($bucketName, $objectName, $destination, $base64EncryptionKey)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $object->downloadToFile($destination, [
        'encryptionKey' => $base64EncryptionKey,
    ]);
    printf('Encrypted object gs://%s/%s downloaded to %s' . PHP_EOL,
        $bucketName, $objectName, basename($destination));
}

Python

For more information, see the Cloud Storage Python API reference documentation. 

import base64

from google.cloud import storage


def download_encrypted_blob(
    bucket_name,
    source_blob_name,
    destination_file_name,
    base64_encryption_key,
):
    """Downloads a previously-encrypted blob from Google Cloud Storage.

    The encryption key provided must be the same key provided when uploading
    the blob.
    """
    # bucket_name = "your-bucket-name"
    # source_blob_name = "storage-object-name"
    # destination_file_name = "local/path/to/file"
    # base64_encryption_key = "base64-encoded-encryption-key"

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)

    # Encryption key must be an AES256 key represented as a bytestring with
    # 32 bytes. Since it's passed in as a base64 encoded string, it needs
    # to be decoded.
    encryption_key = base64.b64decode(base64_encryption_key)
    blob = bucket.blob(source_blob_name, encryption_key=encryption_key)

    blob.download_to_filename(destination_file_name)

    print(
        "Blob {} downloaded to {}.".format(
            source_blob_name, destination_file_name
        )
    )

Ruby

For more information, see the Cloud Storage Ruby API reference documentation. 

def download_encrypted_file bucket_name:, file_name:, local_file_path:, encryption_key:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The ID of your GCS object
  # file_name = "your-file-name"

  # The path to which the file should be downloaded
  # local_file_path = "/local/path/to/file.txt"

  # The Base64 encoded decryption key, which should be the same key originally used to encrypt the object
  # encryption_key = "TIbv/fjexq+VmtXzAlc63J4z5kFmWJ6NdAPQulQBT7g="

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new

  bucket = storage.bucket bucket_name

  file = bucket.file file_name, encryption_key: encryption_key
  file.download local_file_path, encryption_key: encryption_key

  puts "Downloaded encrypted #{file.name} to #{local_file_path}"
end

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

  2. Use cURL to call the JSON API with a GET Object request:

    curl -X GET \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  -H "x-goog-encryption-algorithm: AES256" \
  -H "x-goog-encryption-key: YOUR_ENCRYPTION_KEY" \
  -H "x-goog-encryption-key-sha256: HASH_OF_YOUR_KEY" \
  -o "SAVE_TO_LOCATION" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media"

    Where:

    • OAUTH2_TOKEN is the access token you generated in Step 1.
    • YOUR_ENCRYPTION_KEY is the AES-256 key you used to encrypt the object.
    • HASH_OF_YOUR_KEY is the SHA-256 hash for your AES-256 key.
    • SAVE_TO_LOCATION is the location where you want to save your object. For example, Desktop/dog.png.
    • BUCKET_NAME is the name of the bucket from which you are downloading the object. For example, my-bucket.
    • OBJECT_NAME is the name of the object you are downloading. For example, pets/dogs.png.

See Encryption request headers for more information on encryption-specific headers.

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

  2. Use cURL to call the XML API with a GET OBJECT request:

    curl -X GET \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  -H "x-goog-encryption-algorithm: AES256" \
  -H "x-goog-encryption-key: YOUR_ENCRYPTION_KEY" \
  -H "x-goog-encryption-key-sha256: HASH_OF_YOUR_KEY" \
  -o "SAVE_TO_LOCATION" \
  "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

    Where:

    • OAUTH2_TOKEN is the access token you generated in Step 1.
    • YOUR_ENCRYPTION_KEY is the AES-256 key you used to encrypt the object.
    • HASH_OF_YOUR_KEY is the SHA-256 hash for your AES-256 key.
    • SAVE_TO_LOCATION is the location where you want to save your object. For example, Desktop/dog.png.
    • BUCKET_NAME is the name of the bucket from which you are downloading the object. For example, my-bucket.
    • OBJECT_NAME is the name of the object you are downloading. For example, pets/dogs.png.

See Encryption request headers for more information on encryption-specific headers.

Rotating your encryption keys

To rotate a customer-supplied encryption key:

gsutil

  1. Add the following options to the [GSUtil] section of your boto configuration file:

    encryption_key = NEW_ENCRYPTION_KEY
decryption_key1 = OLD_ENCRYPTION_KEY

    Where:

    • NEW_ENCRYPTION_KEY is the new encryption key for your object.
    • OLD_ENCRYPTION_KEY is the current encryption key for your object.

  2. Use the gsutil rewrite command with the -k flag:

    gsutil rewrite -k gs://BUCKET_NAME/OBJECT_NAME

    Where:

    • BUCKET_NAME is the name of the bucket containing the relevant object. For example, my-bucket.
    • OBJECT_NAME is the name of the relevant object. For example, pets/dog.png.

Code samples

C++

For more information, see the Cloud Storage C++ API reference documentation. 

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, std::string const& old_key_base64,
   std::string const& new_key_base64) {
  StatusOr<gcs::ObjectMetadata> object_metadata =
      client.RewriteObjectBlocking(
          bucket_name, object_name, bucket_name, object_name,
          gcs::SourceEncryptionKey::FromBase64Key(old_key_base64),
          gcs::EncryptionKey::FromBase64Key(new_key_base64));

  if (!object_metadata) {
    throw std::runtime_error(object_metadata.status().message());
  }

  std::cout << "Rotated key on object " << object_metadata->name()
            << " in bucket " << object_metadata->bucket()
            << "\nFull Metadata: " << *object_metadata << "\n";
}

Go

For more information, see the Cloud Storage Go API reference documentation. 

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// rotateEncryptionKey encrypts an object with the newKey.
func rotateEncryptionKey(w io.Writer, bucket, object string, key, newKey []byte) error {
	// bucket := "bucket-name"
	// object := "object-name"
	// key := []byte("encryption-key")
	// newKey := []byte("new-encryption-key")
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	obj := client.Bucket(bucket).Object(object)

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	// obj is encrypted with key, we are encrypting it with the newKey.
	_, err = obj.Key(newKey).CopierFrom(obj.Key(key)).Run(ctx)
	if err != nil {
		return fmt.Errorf("Key(%q).CopierFrom(%q).Run: %v", newKey, key, err)
	}
	fmt.Fprintf(w, "Key rotation complete for blob %v.\n", object)
	return nil
}

Java

For more information, see the Cloud Storage Java API reference documentation. 

import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class RotateObjectEncryptionKey {
  public static void rotateObjectEncryptionKey(
      String projectId,
      String bucketName,
      String objectName,
      String oldEncryptionKey,
      String newEncryptionKey) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    // The Base64 encoded AES-256 encryption key originally used to encrypt the object. See the
    // documentation
    // on Customer-Supplied Encryption keys for more info:
    // https://cloud.google.com/storage/docs/encryption/using-customer-supplied-keys
    // String oldEncryptionKey = "TIbv/fjexq+VmtXzAlc63J4z5kFmWJ6NdAPQulQBT7g="

    // The new encryption key to use
    // String newEncryptionKey = "0mMWhFvQOdS4AmxRpo8SJxXn5MjFhbz7DkKBUdUIef8="

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    BlobId blobId = BlobId.of(bucketName, objectName);
    // You can't change an object's encryption key directly, the only way is to overwrite the object
    Storage.CopyRequest request =
        Storage.CopyRequest.newBuilder()
            .setSource(blobId)
            .setSourceOptions(Storage.BlobSourceOption.decryptionKey(oldEncryptionKey))
            .setTarget(blobId, Storage.BlobTargetOption.encryptionKey(newEncryptionKey))
            .build();
    storage.copy(request);

    System.out.println(
        "Rotated encryption key for object " + objectName + "in bucket " + bucketName);
  }
}

Node.js

For more information, see the Cloud Storage Node.js API reference documentation. 

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const fileName = 'Nome of a file in the bucket, e.g. my-file';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function rotateEncryptionKey() {
  // See the "Generating your own encryption key" section above.
  // const oldKey = 'The current base64 encoded customer-supplied encryption key';
  // const newKey = 'A new base64 encoded customer-supplied encryption key';
  await storage
    .bucket(bucketName)
    .file(fileName, {
      encryptionKey: Buffer.from(oldKey, 'base64'),
    })
    .rotateEncryptionKey({
      encryptionKey: Buffer.from(newKey, 'base64'),
    });

  console.log('Encryption key rotated successfully.');
}

rotateEncryptionKey().catch(console.error);

PHP

For more information, see the Cloud Storage PHP API reference documentation. 

use Google\Cloud\Storage\StorageClient;

/**
 * Change the encryption key used to store an existing object.
 *
 * @param string $bucketName the name of your Google Cloud bucket.
 * @param string $objectName the name of your Google Cloud object.
 * @param string $base64EncryptionKey the base64 encoded encryption key.
 * @param string $newBase64EncryptionKey the new base64 encoded encryption key.
 *
 * @return void
 */
function rotate_encryption_key(
    $bucketName,
    $objectName,
    $base64EncryptionKey,
    $newBase64EncryptionKey
) {
    $storage = new StorageClient();
    $object = $storage->bucket($bucketName)->object($objectName);

    $rewrittenObject = $object->rewrite($bucketName, [
        'encryptionKey' => $base64EncryptionKey,
        'destinationEncryptionKey' => $newBase64EncryptionKey,
    ]);

    printf('Rotated encryption key for object gs://%s/%s' . PHP_EOL,
        $bucketName, $objectName);
}

Python

For more information, see the Cloud Storage Python API reference documentation. 

import base64

from google.cloud import storage


def rotate_encryption_key(
    bucket_name, blob_name, base64_encryption_key, base64_new_encryption_key
):
    """Performs a key rotation by re-writing an encrypted blob with a new
    encryption key."""
    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    current_encryption_key = base64.b64decode(base64_encryption_key)
    new_encryption_key = base64.b64decode(base64_new_encryption_key)

    # Both source_blob and destination_blob refer to the same storage object,
    # but destination_blob has the new encryption key.
    source_blob = bucket.blob(
        blob_name, encryption_key=current_encryption_key
    )
    destination_blob = bucket.blob(
        blob_name, encryption_key=new_encryption_key
    )

    token = None

    while True:
        token, bytes_rewritten, total_bytes = destination_blob.rewrite(
            source_blob, token=token
        )
        if token is None:
            break

    print("Key rotation complete for Blob {}".format(blob_name))

Ruby

For more information, see the Cloud Storage Ruby API reference documentation. 

def rotate_encryption_key bucket_name:, file_name:, current_encryption_key:, new_encryption_key:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The ID of your GCS object
  # file_name = "your-file-name"

  # The Base64 encoded AES-256 encryption key originally used to encrypt the object.
  # See the documentation on Customer-Supplied Encryption keys for more info:
  # https://cloud.google.com/storage/docs/encryption/using-customer-supplied-keys
  # current_encryption_key = "TIbv/fjexq+VmtXzAlc63J4z5kFmWJ6NdAPQulQBT7g="

  # The new encryption key to use
  # new_encryption_key = "0mMWhFvQOdS4AmxRpo8SJxXn5MjFhbz7DkKBUdUIef8="

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.bucket bucket_name
  file    = bucket.file file_name, encryption_key: current_encryption_key

  file.rotate encryption_key:     current_encryption_key,
              new_encryption_key: new_encryption_key

  puts "The encryption key for #{file.name} in #{bucket.name} was rotated."
end

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

  2. Use cURL to call the JSON API with a POST Object request:

    curl -X POST \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  -H "Content-Length: 0" \
  -H "x-goog-encryption-algorithm: AES256" \
  -H "x-goog-encryption-key: NEW_ENCRYPTION_KEY" \
  -H "x-goog-encryption-key-sha256: HASH_OF_NEW_KEY" \
  -H "x-goog-copy-source-encryption-algorithm: AES256" \
  -H "x-goog-copy-source-encryption-key: OLD_ENCRYPTION_KEY" \
  -H "x-goog-copy-source-encryption-key-sha256: HASH_OF_OLD_KEY" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/rewriteTo/b/BUCKET_NAME/o/OBJECT_NAME"

    Where:

    • OAUTH2_TOKEN is the access token you generated in Step 1.
    • NEW_ENCRYPTION_KEY is the new AES-256 key used for encrypting your object.
    • HASH_OF_NEW_KEY is the SHA-256 hash for your new AES-256 key.
    • OLD_ENCRYPTION_KEY is the current AES-256 key used to encrypt your object.
    • HASH_OF_OLD_KEY is the current SHA-256 hash for your AES-256 key.
    • BUCKET_NAME is the name of the bucket containing the relevant object. For example, my-bucket.
    • OBJECT_NAME is the name of the object whose keys you are rotating. For example, Desktop/dogs.png.

See Encryption request headers for more information on encryption-specific headers.

XML API

The XML API does not support rotating a customer-supplied encryption key through rewriting object. To apply a new customer-supplied key to an object using the XML API, you should:

  1. Download the existing object.
  2. Re-upload the object using a new key.

What's next