AWS KMS Encryption

Protect Secrets Manager connection details with AWS KMS

Keeper Secrets Manager integrates with AWS KMS 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.

Looking for AWS Secrets Manager-backed storage instead? See AWS Secrets Manager Storage. That integration stores the KSM config inside an AWS Secrets Manager secret, with no local file. The two AWS integrations solve different problems and use different AWS services; pick the one that fits your deployment shape.

Features

Encrypt and Decrypt your Keeper Secrets Manager configuration files with AWS KMS
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

Supports the Java Secrets Manager SDK
Requires AWS-KMS and AWS-Auth packages
Supports Java 11 and above

Setup

1. Install Module

Setting up project using Gradle or Maven

Gradle

repositories {
  mavenCentral()
}

dependencies {
  implementation("com.keepersecurity.secrets-manager:aws:1.0.0")
  implementation("com.keepersecurity.secrets-manager:core:17.1.1")
  implementation ("software.amazon.awssdk:kms:2.34.0")
  implementation ("software.amazon.awssdk:auth:2.34.0")
  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>aws</artifactId>
 <version>1.0.0</version>
</dependency>
<dependency>
 <groupId>com.keepersecurity.secrets-manager</groupId>
 <artifactId>core</artifactId>
 <version>17.1.1</version>
</dependency>

<!-- aws-kms -->
   	<dependency>
   		<groupId>software.amazon.awssdk</groupId>
   		<artifactId>kms</artifactId>
   		<version>2.34.0</version>
   	</dependency>
   		
   	<!-- aws-auth -->
   	<dependency>
   		<groupId>software.amazon.awssdk</groupId>
   		<artifactId>auth</artifactId>
   		<version>2.34.0</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>

The Secrets Manager AWS KMS storage module can be installed using pip

pip3 install keeper-secrets-manager-storage

boto3 is a prerequisite for the AWS KSM integration. Install it to your machine using pip.

pip install boto3

2. Configure AWS Connection

By default, the AWS SDK will utilize the default connection session setup with the AWS CLI using the aws configure command. If you would like to specify the connection details, the two configuration files located at ~/.aws/config and ~/.aws/credentials can be manually edited.

See the AWS documentation for more information on setting up an AWS session: https://docs.aws.amazon.com/cli/latest/reference/configure/

Alternatively, configuration variables can be provided explicitly using the AwsSessionConfig data class and providing aws_access_key_id, aws_secret_access_key, and region_name variables.

You will need an AWS Access Key to use the AWS KMS integration.

For more information on AWS Access Keys see the AWS documentation: https://aws.amazon.com/premiumsupport/knowledge-center/create-access-key/

3. Add AWS KMS Storage to Your Code

Once the AWS connection has been configured, you can use AWS KMS to encrypt and decrypt KSM configurations. Tell the Secrets Manager SDK to utilize KMS as storage. Using Specified Connection credentials

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

The storage will require an AWS Key ID, AwsSessionConfig, as well as the name of the Secrets Manager configuration file which will be encrypted by AWS KMS.

import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;
import com.keepersecurity.secretmanager.aws.kms.AwsKeyValueStorage;
import com.keepersecurity.secretmanager.aws.kms.AwsSessionConfig;
import com.keepersecurity.secretsManager.core.InMemoryStorage;
import com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import static com.keepersecurity.secretsManager.core.SecretsManager.initializeStorage;

import software.amazon.awssdk.regions.Region;

import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

class Test {
	public static void main(String args[]){
		String keyId = "<Key ID>";
		String awsAccessKeyId = "<AWS Access ID>";
		String awsSecretAccessKey = "<AWS Secret>";
		String oneTimeToken = "[One Time Token]";
		Region region = Region.<cloud-region>;
		String profile = null;  // set to "DEFAULT", "UAT", "PROD" etc. if ~/.aws/config profiles are configured
		String configFileLocation = "client_config_test.json";
		try{
			//set AWS configuration, It can be null if profile is set for aws credentials
			AwsSessionConfig sessionConfig = new AwsSessionConfig(awsAccessKeyId, awsSecretAccessKey);
			//Get Storage 
			AwsKeyValueStorage awskvstorage =  new AwsKeyValueStorage(keyId, configFileLocation, profile, sessionConfig, region);
			initializeStorage(awskvstorage, oneTimeToken);
			SecretsManagerOptions options = new SecretsManagerOptions(awskvstorage);
			//getSecrets(OPTIONS);
		}catch (Exception e) {
			System.out.println(e.getMessage());
		}
	}
}

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

The storage will require an AWS Key ID, AWS Session credentials - AWSSessionConfig , as well as the name of the Secrets Manager configuration file which will be encrypted by AWS KMS.

import { AWSKeyValueStorage, AWSSessionConfig, LoggerLogLevelOptions } from "@keeper-security/secrets-manager-aws";
import { initializeStorage, getSecrets } from "@keeper-security/secrets-manager-core";


const getKeeperRecordsAWS = async () => {

	const accessKeyId = "<YOUR AWS ACCESS KEY>";
	const secretAccessKey = "<YOUR AWS SECRET_ACCESS_KEY>";
	const regionName = "<YOUR AWS REGION>";
	const logLevel = LoggerLogLevelOptions.debug;
	const configPath = "client-config-path.json";
	
	const awsSessionConfig = new AWSSessionConfig(accessKeyId, secretAccessKey, regionName);
	const keyId = 'arn:aws:kms:ap-south-1:<accountName>:key/<keyId>';
	const storage = await new AWSKeyValueStorage(keyId, configPath, awsSessionConfig, logLevel).init();
	
	const oneTimeToken = "<one time token>";

	await initializeStorage(storage, oneTimeToken);
	const { records } = await getSecrets({ storage: storage });

	const firstRecord = records[0]
	const firstRecordPassword = firstRecord.data.fields.find(x => x.type === 'password')
	console.log(firstRecordPassword.value[0])
};
getKeeperRecordsAWS();

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

The storage will require an AWS Key ID, AwsSessionConfig, as well as the name of the Secrets Manager configuration file which will be encrypted by AWS KMS.

Upgrading from v1.0.x? v1.1.0 includes these behavioral changes:

decrypt_config() now defaults to autosave=False — call decrypt_config(autosave=True) to preserve the previous behavior.
Encrypt and decrypt failures now raise exceptions instead of silently corrupting storage state.
Corrupt or non-UTF8 config files now raise "is not a valid encrypted config file" instead of leaking JSONDecodeError or logging silently.
Config writes are now atomic (write-then-rename), so a failed write no longer truncates the existing config to zero bytes.
delete_all() now removes the encrypted config file from disk instead of writing an empty encrypted blob.
AwsKmsKeyValueStorage is now thread-safe for concurrent reads and writes.

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_hsm.storage_aws_kms import AwsKmsKeyValueStorage, AwsSessionConfig

aws_session_cfg = AwsSessionConfig(
    aws_access_key_id="AK[...]FIF",
    aws_secret_access_key="/[...]/g3",
    region_name="us-east-2")

config = AwsKmsKeyValueStorage(
   key_id='e9[...]567',
   config_file_location='client-config.json',
   aws_session_config=aws_session_cfg)

secrets_manager = SecretsManager(config=config, verify_ssl_certs=True)
all_records = secrets_manager.get_secrets()

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

The storage will require an AWS Key ID, AwsSessionConfig, as well as the name of the Secrets Manager configuration file which will be encrypted by AWS KMS.

using System;
using System.Linq;
using System.Threading.Tasks;
using SecretsManager;
using AWSKeyManagement;

public class Program
{
	private static async Task getOneIndividualSecret()
	{
		var accessKeyId = "<ACCESS_KEY_ID>";
		var secretAccessKey = "<SECRET_ACCESS_KEY>";
		var regionName = "<AWS_REGION_STRING>";

		var keyId = "<KEY_ID_1>";
		var path = "<KEEPER_CONFIG_FILE_PATH>";
		var dotnet_access_token = "<ONE_TIME_TOKEN>";

		var awsSessionConfig = new AWSSessionConfig(accessKeyId, secretAccessKey, regionName);

		var aws_storage = new AWSKeyValueStorage(keyId, path, awsSessionConfig);

		SecretsManagerClient.InitializeStorage(aws_storage, dotnet_access_token);

		var options = new SecretsManagerOptions(aws_storage);
		var records_1 = await SecretsManagerClient.GetSecrets(options);
		records_1.Records.ToList().ForEach(record => Console.WriteLine(record.RecordUid + " - " + record.Data.title));
	}

	static async Task Main()
	{
		await getOneIndividualSecret();
	}
}

Using Default Connection

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

The storage will require an AWS Key ID, as well as the name of the Secrets Manager configuration file which will be encrypted by AWS KMS.

import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;
import com.keepersecurity.secretmanager.aws.kms.AwsKeyValueStorage;
import com.keepersecurity.secretmanager.aws.kms.AwsSessionConfig;
import com.keepersecurity.secretsManager.core.InMemoryStorage;
import com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import static com.keepersecurity.secretsManager.core.SecretsManager.initializeStorage;

import software.amazon.awssdk.regions.Region;

import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

class Test {
	public static void main(String args[]){
		String keyId = "<Key ID>";
		String oneTimeToken = "[One Time Token]";
		Region region = Region.<cloud-region>;
		String profile = null;  // set to "DEFAULT", "UAT", "PROD" etc. if ~/.aws/config profiles are configured
		String configFileLocation = "client_config_test.json";
		try{
			// Using default AWS credentials from ~/.aws/credentials or environment variables
			AwsKeyValueStorage awskvstorage =  new AwsKeyValueStorage(keyId, configFileLocation, profile, null, region);
			initializeStorage(awskvstorage, oneTimeToken);
			SecretsManagerOptions options = new SecretsManagerOptions(awskvstorage);
			//getSecrets(OPTIONS);
		}catch (Exception e) {
			System.out.println(e.getMessage());
		}
	}
}

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

The storage will require an AWS Key ID , as well as the name of the Secrets Manager configuration file which will be encrypted by AWS KMS.

import { AWSKeyValueStorage } from "@keeper-security/secrets-manager-aws";
import { initializeStorage, getSecrets } from "@keeper-security/secrets-manager-core";


const getKeeperRecordsAWS = async () => {

	const configPath = "client-config-path.json";
	
	const keyId = 'arn:aws:kms:ap-south-1:<accountName>:key/<keyId>';
	const storage = await new AWSKeyValueStorage(keyId, configPath).init();
	
	const oneTimeToken = "<one time token>";

	await initializeStorage(storage, oneTimeToken);
	const { records } = await getSecrets({ storage: storage });

	const firstRecord = records[0]
	const firstRecordPassword = firstRecord.data.fields.find(x => x.type === 'password')
	console.log(firstRecordPassword.value[0])
};
getKeeperRecordsAWS();

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

The storage will require an AWS Key ID, as well as the name of the Secrets Manager configuration file which will be encrypted by AWS KMS.

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_hsm.storage_aws_kms import AwsKmsKeyValueStorage

key_id = 'c5[...]576'
    
config = AwsKmsKeyValueStorage(key_id, 'client-config.json') # default session
 
secrets_manager = SecretsManager(config=config, verify_ssl_certs=True)
all_records = secrets_manager.get_secrets()

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

The storage will require an AWS Key ID, as well as the name of the Secrets Manager configuration file which will be encrypted by AWS KMS.

using System;
using System.Linq;
using System.Threading.Tasks;
using SecretsManager;
using AWSKeyManagement;

public class Program
{
	private static async Task getOneIndividualSecret()
	{
		var keyId = "<KEY_ID_1>";
		var path = "<KEEPER_CONFIG_FILE_PATH>";
		var dotnet_access_token = "<ONE_TIME_TOKEN>";

		var aws_storage = new AWSKeyValueStorage(keyId, path);

		SecretsManagerClient.InitializeStorage(aws_storage, dotnet_access_token);

		var options = new SecretsManagerOptions(aws_storage);
		var records_1 = await SecretsManagerClient.GetSecrets(options);
		records_1.Records.ToList().ForEach(record => Console.WriteLine(record.RecordUid + " - " + record.Data.title));
	}

	static async Task Main()
	{
		await getOneIndividualSecret();
	}
}

Using the AWS KMS Integration

Once setup, the Secrets Manager AWS KMS integration supports all Secrets Manager SDK functionality. Your code will need to be able to access the AWS KMS APIs in order to manage the decryption of the configuration file when run.

Additional Options

Change Key

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

String newkeyId = "<New-Key-ID>";
AwsKeyValueStorage awskvstorage =  new AwsKeyValueStorage(keyId, configFileLocation, profile, sessionConfig, region);
awskvstorage.changeKey(newkeyId)

const storage = await new AWSKeyValueStorage(keyId,config_path).init()
await initializeStorage(storage, oneTimeToken);

// do all process needed if any or change directly
await storage.changeKey(keyId2);

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_hsm.storage_aws_kms import AwsKmsKeyValueStorage, AwsSessionConfig

aws_session_cfg = AwsSessionConfig(
    aws_access_key_id="AK[...]FIF",
    aws_secret_access_key="/[...]/g3",
    region_name="<region>")

new_key_id = "<new_key_id>"
config = AwsKmsKeyValueStorage(
   key_id='e9[...]567',
   config_file_location='client-config.json',
   aws_session_config=aws_session_cfg)

secrets_manager = SecretsManager(config=config, verify_ssl_certs=True)
is_changed = config.change_key(new_key_id)

    using Microsoft.Extensions.Logging;

    var awsSessionConfig2 = new AWSSessionConfig();
    var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder.SetMinimumLevel(LogLevel.Debug);
            builder.AddConsole();
        });

    var logger = loggerFactory.CreateLogger<AWSKeyValueStorage>();

    var aws_storage = new AWSKeyValueStorage(keyId, path, awsSessionConfig2,logger);
    await aws_storage.ChangeKeyAsync("<NEW_KEY_ID>");

Decrypt Config

We can decrypt the config if current implementation is to be migrated onto a different cloud or if you want your raw credentials back. The function accepts a boolean which when set to true will save the decrypted configuration to file and if left false, will just return decrypted configuration.

AwsKeyValueStorage awskvstorage =  new AwsKeyValueStorage(keyId, configFileLocation, profile, sessionConfig, region);
awskvstorage.decryptConfig(true) // Set true as a parameter to extract plaintext and save config as a plaintext.
//OR 
awskvstorage.decryptConfig(false); // Set false as a parameter to extract only plaintext.

v1.1.0: decrypt_config() now defaults to autosave=False. Previously the default was True, which would overwrite the encrypted config file with plaintext. Pass autosave=True explicitly to save to disk.

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_hsm.storage_aws_kms import AwsKmsKeyValueStorage, AwsSessionConfig

aws_session_cfg = AwsSessionConfig(
    aws_access_key_id="AK[...]FIF",
    aws_secret_access_key="/[...]/g3",
    region_name="<region>")

config = AwsKmsKeyValueStorage(
   key_id='e9[...]567',
   config_file_location='client-config.json',
   aws_session_config=aws_session_cfg)

secrets_manager = SecretsManager(config=config, verify_ssl_certs=True)

# Returns plaintext only (file stays encrypted)
plaintext = config.decrypt_config(autosave=False)
print(plaintext)

# OR: returns plaintext and saves config as plaintext
plaintext = config.decrypt_config(autosave=True)
print(plaintext)

You're ready to use the KSM integration 👍

Check out the KSM SDKs documentation for more examples and functionality

PreviousAWS CLI Credential Process NextAWS Secrets Manager Sync

Last updated 13 days ago