Google Cloud Key Management Encryption

Protect Secrets Manager connection details with Google Cloud Key Management

Keeper Secrets Manager integrates with Google Cloud Key Management in order to provide encryption for Keeper Secrets Manager configuration files. With this integration, you can protect connection details on your machine while taking advantage of Keeper's zero-knowledge encryption of all your secret credentials.

Features

• Encrypt and Decrypt your Keeper Secrets Manager configuration files with Google Cloud Key Management.
• Protect against unauthorized access to your Secrets Manager connections.
• Requires only minor changes to code for immediate protection. Works with all Keeper Secrets Manager SDK functionality.

Prerequisites

To configure Google Cloud Key Management with Keeper Security, you need a service account key file (.json). Key structure that is supported by this integration is projects/<project_name>/locations/<location_name>/keyRings/<key_ring_name>/cryptoKeys/<key_name>/cryptoKeyVersions/<key_version>

Java

• Support the Java/Kotlin Secrets Manager SDK.
• Required GCP package google-cloud-kms
• GCP KMS key needs ENCRYPT and DECRYPT permissions.

JavaScript

Note: v1.1.0+ requires Node.js 22 or later. Earlier Node.js versions are no longer supported.

• Supports the JavaScript Secrets Manager SDK
• @google-cloud/kms is bundled — no separate install required.
• GCP KMS key needs the following IAM permissions on the service account:

  • Cloud KMS CryptoKey Encrypter
  • Cloud KMS CryptoKey Decrypter
  • Cloud KMS CryptoKey Public Key Viewer (required for asymmetric keys)
  • Cloud KMS Viewer (provides cloudkms.cryptoKeys.get, required for key introspection on initialization)

Python

Note: v1.1.0+ requires Python 3.9+. Users on Python 3.6–3.8 should pin to keeper-secrets-manager-storage-gcp-kms<1.1.0.

• Supports the Python Secrets Manager SDK
• Requires google-cloud-kms package and these permissions

  • Cloud KMS CryptoKey Encrypter
  • Cloud KMS CryptoKey Decrypter
  • Cloud KMS CryptoKey Public Key Viewer
  • Cloud KMS Viewer (provides cloudkms.cryptoKeys.get, required for key introspection on initialization)

.Net

• Supports the .Net Secrets Manager SDK
• Requires Google.Apis.CloudKMS.v1
• GCP KMS key needs ENCRYPT and DECRYPT permissions.

Setup

1. Install Module

Java

Setting up project using Gradle or Maven

Gradle

repositories {
  mavenCentral()
}

dependencies {
	implementation("com.keepersecurity.secrets-manager:core:17.0.0")
	implementation("com.keepersecurity.secrets-manager:gcp:1.0.0")
	implementation ("com.google.cloud:google-cloud-kms:2.62.0")
	implementation ("com.google.auth:google-auth-library-oauth2-http:1.33.1") 
	implementation("com.fasterxml.jackson.core:jackson-databind:2.18.2")
	implementation("com.fasterxml.jackson.core:jackson-core:2.18.2")
	implementation("com.google.code.gson:gson:2.12.1")
    implementation("org.slf4j:slf4j-api:1.7.32"){
        exclude("org.slf4j:slf4j-log4j12")
    }
	implementation("ch.qos.logback:logback-classic:1.2.6")
	implementation("ch.qos.logback:logback-core:1.2.6")
	implementation("org.bouncycastle:bc-fips:1.0.2.4")
}

Maven

<!-- KMS-core -->
<dependency>
	<groupId>com.keepersecurity.secrets-manager</groupId>
	<artifactId>core</artifactId>
	<version>[17.0.0,)</version>
</dependency>
<dependency>
	<groupId>com.keepersecurity.secrets-manager</groupId>
	<artifactId>gcp</artifactId>
	<version>1.0.0</version>
</dependency>
<!-- gcp-kms -->
<dependency>
	<groupId>com.google.cloud</groupId>
	<artifactId>google-cloud-kms</artifactId>
	<version>2.62.0</version>
</dependency>
<!-- gcp auth -->
<dependency>
	<groupId>com.google.auth</groupId>
	<artifactId>google-auth-library-oauth2-http</artifactId>
	<version>1.33.1</version>
</dependency>
<!--gson -->
<dependency>
	<groupId>com.google.code.gson</groupId>
	<artifactId>gson</artifactId>
	<version>2.12.1</version>
</dependency>
<!--jackson-core -->
<dependency>
	<groupId>com.fasterxml.jackson.core</groupId>
	<artifactId>jackson-core</artifactId>
	<version>2.18.2</version>
</dependency>
<!--jackson-databind -->
<dependency>
	<groupId>com.fasterxml.jackson.core</groupId>
	<artifactId>jackson-databind</artifactId>
	<version>2.18.2</version>
</dependency>
<!-- slf4j-api -->
<dependency>
	<groupId>org.slf4j</groupId>
	<artifactId>slf4j-api</artifactId>
	<version>1.7.32</version>
	<scope>runtime</scope>
</dependency>
<!-- logback-classic -->
<dependency>
	<groupId>ch.qos.logback</groupId>
	<artifactId>logback-classic</artifactId>
	<version>1.2.6</version>
	<scope>compile</scope>
</dependency>
<!-- logback-core -->
<dependency>
	<groupId>ch.qos.logback</groupId>
	<artifactId>logback-core</artifactId>
	<version>1.2.6</version>
	<scope>compile</scope>
</dependency>
<!-- bc-fips -->
<dependency>
	<groupId>org.bouncycastle</groupId>
	<artifactId>bc-fips</artifactId>
	<version>1.0.2.4</version>
</dependency>

JavaScript

The Secrets Manager Google Cloud Key Management module can be installed using npm

npm install @keeper-security/secrets-manager-gcp

Python

The Secrets Manager Google Cloud Key Management module can be installed using pip

pip3 install keeper-secrets-manager-storage-gcp-kms

.Net

The Secrets Manager Google Cloud Key Management module can be installed using dotnet nuget package manager.

dotnet add package Keeper.SecretsManager.GCPKeyManagement

2. Configure GCP KMS Connection

To enable secure authentication with Google Cloud Platform (GCP), generate a Service Account key in JSON format. This credential file will serve as the authentication mechanism for interacting with GCP services programmatically.

Python v1.1.0+: The service account must have the Cloud KMS Viewer IAM role (cloudkms.cryptoKeys.get) in addition to the Encrypter/Decrypter roles. Without it, GCPKeyValueStorage raises a permission error on initialization. See the Python Prerequisites tab for the full required role list.

See the Google documentation for more information on generating keys:

https://cloud.google.com/iam/docs/keys-create-delete

3. Add GCP KMS Storage to Your Code

Once GCP connection has been configured, you can use the GCP KMS integration to encrypt and decrypt the KSM configuration. Tell the Secrets Manager SDK to use GCP KMS as storage.

Using GCP KMS Integration

Once set up, the Secrets Manager GCP KMS integration supports all Secrets Manager SDK functionality. Your code will need to be able to access the GCP KMS keys in order to manage the encryption and decryption of the KSM configuration file. Using Specified Connection credentials

Java

To do this, create GcpKeyValueStorage instance and use this in SecretManagerOptions constructor.

The GcpKeyValueStorage will require the name of the Secrets Manager configuration file , gcp credential file and key details of Cloud Key Management.

import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;
import static com.keepersecurity.secretsManager.core.SecretsManager.initializeStorage;
import com.keepersecurity.secretsmanager.gcp.GcpKeyValueStorage;
import com.keepersecurity.secretsmanager.gcp.GcpSessionConfig;
import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
public class Test {
	public static void main(String args[]){
	    String oneTimeToken = "One_Time_Token";
	    String projectId = "projectId";
	    String location = "cloud_region";
	    String keyRing = "key_ring_name";
	    String keyId = "key_id";
	    String keyVersion = "key_version";
	    String configFileLocation = "client_config_test.json";
	    String credentialFileLocation = "<path_with_name_of_gcp_cred_file.json>";
	    Security.addProvider(new BouncyCastleFipsProvider());
		try{
				GcpSessionConfig sessionConfig = new GcpSessionConfig(projectId, location, keyRing, keyId, keyVersion, credentialFileLocation);
				GcpKeyValueStorage storage = new GcpKeyValueStorage(configFileLocation, sessionConfig);
				initializeStorage(storage, oneTimeToken);
				SecretsManagerOptions options = new SecretsManagerOptions(storage);	
		}catch (Exception e) {
				  System.out.println(e.getMessage());
		}
	}
}

JavaScript

To do this, use GCPKeyValueStorage as your Secrets Manager storage in the SecretsManager constructor.

The storage will require an keyConfig , gcpsessionConfig(generated by GCPKSMClient) , and the name of the Secrets Manager configuration file which will be encrypted by GCP Cloud Key Management.

v1.1.0 behavior: A config path that is a symbolic link is now refused on both read and write. A config path with a hard-linked peer is replaced rather than written through on save. Point configPath or KSM_CONFIG_FILE at the real file, not a link. A zero-length config file is also now a hard error on init()/decryptConfig() instead of being treated as an empty config, so an interrupted or truncated write can no longer be silently re-encrypted over.

The config file path is the first non-blank value of these three: the config path argument you pass to GCPKeyValueStorage, the KSM_CONFIG_FILE environment variable, and client-config.json in the current working directory. A blank or whitespace-only value counts as unset.

The config file's directory must be writable, not only the file itself — writes create a temporary file alongside the config file and rename it into place. Config file writes land at file mode 0600 and a newly created config directory at 0700. On Linux and macOS, init() and decryptConfig() also refuse to read a config file that is owned by a user other than the account that runs your application (a root-owned file is accepted), or whose mode allows group or world write access, such as 0664 or 0666. A config file that version 1.0.0 created under a umask of 002 has mode 0664 and now fails, while 0644 passes. The error names the path. Set the file to 0600 and make sure the application account owns it. On Windows, Node.js does not apply POSIX file modes, so these modes have no effect and the config read does not check file ownership or mode. Restrict access to the config directory with Windows ACLs instead. A symbolic link at the config path is still refused on Windows, but the check runs just before the file is opened, so a link swapped in between the two steps is not caught. Anyone who can replace the config file can win that race, so limit who can write to the config directory. A save on Windows fails with an EPERM, EACCES, or EBUSY error if another process holds the config file open at that moment. The existing config file is left intact and the error reaches your code, so retry the save.

Call and await init() once before any other method. Every other public method, including decryptConfig(), rejects with an error that names init() until init() has finished, and an instance whose init() failed stays unusable. init() also rejects, and leaves the file untouched, when the config file holds JSON that is not an object of string values, such as null, an array, a number, or an object with a non-string value. Restore the file from a backup, or delete it to create a new configuration.

import { getSecrets, initializeStorage } from "@keeper-security/secrets-manager-core";
import { GCPKeyValueStorage, GCPKeyConfig, GCPKSMClient, LoggerLogLevelOptions } from "@keeper-security/secrets-manager-gcp";

const getKeeperRecordsGCP = async () => {
    const gcpCredFile = "<path_to_gcp_credentials.json>";
    const keyConfig = new GCPKeyConfig("<key_version_resource_url>");
    const gcpSessionConfig = new GCPKSMClient().createClientFromCredentialsFile(gcpCredFile);
    const configPath = "<path_to_client-config.json>";
    const logLevel = LoggerLogLevelOptions.info;

    // oneTimeToken is used only once to initialize the storage
    // after the first run, subsequent calls will use the encrypted config file
    const oneTimeToken = "<one_time_token>";

    const storage = await new GCPKeyValueStorage(configPath, keyConfig, gcpSessionConfig, logLevel).init();
    await initializeStorage(storage, oneTimeToken);

    const { records } = await getSecrets({ storage: storage });
    const firstRecord = records[0];
    const password = firstRecord.data.fields.find((x) => x.type === "password");
    console.log(password.value[0]);
};
getKeeperRecordsGCP();

Python

To do this, use GCPKeyValueStorage as your Secrets Manager storage in the SecretsManager constructor.

The storage will require gcp_key_config (generated by GCPKeyConfig ), gcp_session_config object (generated by GCPKMSClientConfig ) and the name of the Secrets Manager configuration file which will be encrypted by GCP Cloud Key Management.

from keeper_secrets_manager_storage_gcp_kms import GCPKeyConfig, GCPKeyValueStorage, GCPKMSClientConfig
from keeper_secrets_manager_core import SecretsManager

# Example key: projects/<project>/locations/<location>/keyRings/<keyring>/cryptoKeys/<key_name>/cryptoKeyVersions/<version>
gcp_key_config = GCPKeyConfig("<key_resource_uri>")

gcp_cred_file_location_with_name = "<path_with_name_of_gcp_cred_file.json>"
gcp_session_config = GCPKMSClientConfig().create_client_from_credentials_file(gcp_cred_file_location_with_name)

config_path = "ksm_config.json"
one_time_token = "<one_time_token>"

storage = GCPKeyValueStorage(config_path, gcp_key_config, gcp_session_config)
secrets_manager = SecretsManager(token=one_time_token, config=storage)
all_records = secrets_manager.get_secrets()

first_record = all_records[0]
print(first_record)

.Net

To do this, use GCPKeyValueStorage as your Secrets Manager storage in the SecretsManager constructor.

The storage will require an keyConfig (generated by GCPKeyConfig ), gcpSessionConfig object (generated by GCPKMSClient ), and the name of the Secrets Manager configuration file which will be encrypted by GCP Cloud Key Management.

using System;
using System.Linq;
using System.Threading.Tasks;
using SecretsManager;
using GCPKeyManagement;
using Microsoft.Extensions.Logging;

public class Program {
    private static async Task Main() {
        string keyResourceName = "<key_version_resource_url>";
        string gcpConfigFilePath = "<path_to_gcp_credentials.json>";
        var keyConfig = new GCPKeyConfig(keyResourceName);
        var gcpSessionConfig = new GCPKMSClient().CreateClientFromCredentialsFile(gcpConfigFilePath);
        var ksmConfigPath = "ksm_config.json";
        var oneTimeToken = "<one_time_token>";
        var loggerFactory = LoggerFactory.Create(builder => {
            builder.SetMinimumLevel(LogLevel.Debug);
            builder.AddConsole();
        });
        var logger = loggerFactory.CreateLogger<GCPKeyValueStorage>();
        var gcp_storage = new GCPKeyValueStorage(keyConfig, gcpSessionConfig, ksmConfigPath, logger);
        SecretsManagerClient.InitializeStorage(gcp_storage, oneTimeToken);
    }
}

Using Application Default Credentials

JavaScript

If you have configured credentials via gcloud auth application-default login, the GOOGLE_APPLICATION_CREDENTIALS environment variable, or are running on a GCP compute instance with a service account attached, you can omit the credentials file entirely.

import { getSecrets, initializeStorage } from "@keeper-security/secrets-manager-core";
import { GCPKeyValueStorage, GCPKeyConfig, GCPKSMClient, LoggerLogLevelOptions } from "@keeper-security/secrets-manager-gcp";

const getKeeperRecordsGCP = async () => {
    // No credentials file needed — uses Application Default Credentials automatically
    const gcpSessionConfig = new GCPKSMClient();
    const keyConfig = new GCPKeyConfig("<key_version_resource_url>");
    const configPath = "<path_to_client-config.json>";
    const logLevel = LoggerLogLevelOptions.info;

    const oneTimeToken = "<one_time_token>";

    const storage = await new GCPKeyValueStorage(configPath, keyConfig, gcpSessionConfig, logLevel).init();
    await initializeStorage(storage, oneTimeToken);

    const { records } = await getSecrets({ storage: storage });
    const firstRecord = records[0];
    const password = firstRecord.data.fields.find((x) => x.type === "password");
    console.log(password.value[0]);
};
getKeeperRecordsGCP();

Alternatively, you can pass the service account email and private key directly without a file:

const gcpSessionConfig = new GCPKSMClient().createClientUsingCredentials(
    "<service_account_email>",
    "<private_key>"
);

Python

If you have configured credentials via gcloud auth application-default login, the GOOGLE_APPLICATION_CREDENTIALS environment variable, or are running on a GCP compute instance with a service account attached, you can omit the credentials file entirely.

from keeper_secrets_manager_storage_gcp_kms import GCPKeyConfig, GCPKeyValueStorage, GCPKMSClientConfig
from keeper_secrets_manager_core import SecretsManager

gcp_key_config = GCPKeyConfig("<key_resource_uri>")

# Uses Application Default Credentials (gcloud auth application-default login,
# GOOGLE_APPLICATION_CREDENTIALS env var, or attached service account)
gcp_session_config = GCPKMSClientConfig().get_default_crypto_client()

config_path = "ksm_config.json"
one_time_token = "<one_time_token>"

storage = GCPKeyValueStorage(config_path, gcp_key_config, gcp_session_config)
secrets_manager = SecretsManager(token=one_time_token, config=storage)
all_records = secrets_manager.get_secrets()

first_record = all_records[0]
print(first_record)

ADC + RAW_ENCRYPT_DECRYPT limitation: ADC cannot be used with RAW_ENCRYPT_DECRYPT key types. The raw KMS API path requires an OAuth token that the default client does not expose. Use create_client_from_credentials_file() or create_client_using_credentials() for raw symmetric keys.

Alternatively, you can pass the service account email and private key directly without a file:

gcp_session_config = GCPKMSClientConfig().create_client_using_credentials(
    "<service_account_email>",
    "<private_key>"  # PEM-formatted private key string (the private_key field from the service account JSON), not a file path
)

Additional Options

Change Key

We can change key that is used for encrypting the KSM configuration, examples below show the code needed to use it

Java

GcpKeyValueStorage storage = new GcpKeyValueStorage(configFileLocation, sessionConfig);
String newKeyID = "<new_key_id>";
boolean isChanged = storage.changeKey(newKeyID);
System.out.println("Key Changed: " + isChanged);

JavaScript

// To change the GCP KMS key used for encryption, call the changeKey method on the GCPKeyValueStorage instance.
const newKeyConfig = new GCPKeyConfig("<new_key_version_resource_url>");
const storage = await new GCPKeyValueStorage(configPath, keyConfig, gcpSessionConfig).init();
await storage.changeKey(newKeyConfig);

Python

new_key_config = GCPKeyConfig("<new_key_resource_uri>")
storage = GCPKeyValueStorage(config_path, gcp_key_config, gcp_session_config)
is_changed = storage.change_key(new_key_config)
print("Key is changed:", is_changed)

.Net

// To change the GCP KMS key used for encryption, call ChangeKeyAsync on the GCPKeyValueStorage instance.
var gcp_storage = new GCPKeyValueStorage(keyConfig, gcpSessionConfig, path, logger);
bool isChanged = await gcp_storage.ChangeKeyAsync(newKeyConfig);
Console.WriteLine(isChanged);

Decrypt Config

You can decrypt the configuration file to migrate to a different cloud provider or to retrieve your raw credentials. Pass true to save the decrypted configuration back to the file, or false to return the plaintext without modifying the file.

Java

GcpKeyValueStorage storage = new GcpKeyValueStorage(configFileLocation, sessionConfig);
storage.decryptConfig(false); // Set false as a parameter to extract only plaintext.
//OR 
storage.decryptConfig(true); // Set true as a parameter to extract plaintext and save config as a plaintext.

JavaScript

Warning: decryptConfig(true) writes the client ID, app key, and device private key to disk in plaintext at the config file's path, replacing the encrypted file. Anything that can read that file, including backups, snapshots, and container image layers, can read those credentials until you re-encrypt it. The write does land at file mode 0600 (owner read/write only), which limits exposure to other local users on the same machine, but the data itself is plaintext on disk.

const storage = await new GCPKeyValueStorage(configPath,keyConfig,gcpSessionConfig).init();
await storage.decryptConfig(true); // Set true as a parameter to extract plaintext and save config as a plaintext.
 // OR 
await storage.decryptConfig(false);  // Set false as a parameter to extract only plaintext.

To return to an encrypted config, construct a new GCPKeyValueStorage against the same path and call .init() on it. loadConfig() detects the plaintext config file and re-encrypts it in place before init() returns. Do not call init() again on the instance that called decryptConfig(true) — that instance does not re-encrypt the file, and the file stays in plaintext.

Python

v1.1.0 change: decrypt_config() called without arguments now defaults to autosave=False (returns plaintext only, does not write to disk). In v1.0.x the default was True, which would overwrite the encrypted config file with plaintext credentials. Always pass the argument explicitly.

storage = GCPKeyValueStorage(config_path, gcp_key_config, gcp_session_config)

# Extract only plaintext
plaintext = storage.decrypt_config(autosave=False)
print(plaintext)

# OR extract plaintext and save config as plaintext
plaintext = storage.decrypt_config(autosave=True)
print(plaintext)

.Net

// To decrypt the config file and revert to plaintext, call DecryptConfigAsync on the GCPKeyValueStorage instance.
var gcp_storage = new GCPKeyValueStorage(keyConfig, gcpSessionConfig, path, logger);
var conf = await gcp_storage.DecryptConfigAsync(false); // Returns plaintext only
Console.WriteLine(conf);
// OR
var conf = await gcp_storage.DecryptConfigAsync(true); // Returns plaintext and saves config as plaintext
Console.WriteLine(conf);

You're ready to use the KSM integration 👍

Check out the KSM SDKs documentation for more examples and functionality