# AWS KMS Encryption

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2Fs5mJxxwsAgO65JtYFSNV%2Fksm-aws.jpg?alt=media&#x26;token=cf7a9f00-3fd7-4a74-9843-1cf65c6ade60" alt=""><figcaption></figcaption></figure>

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.

## 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

{% tabs %}
{% tab title="Java" %}

* Supports the [Java Secrets Manager SDK](https://docs.keeper.io/en/keeperpam/secrets-manager/developer-sdk-library/java-sdk)
* Requires [AWS-KMS](https://mvnrepository.com/artifact/software.amazon.awssdk/kms) and [AWS-Auth](https://mvnrepository.com/artifact/software.amazon.awssdk/auth) packages
* Supports Java 11 and above
  {% endtab %}

{% tab title="JavaScript" %}

* Supports the [JavaScript Secrets Manager SDK](https://docs.keeper.io/en/keeperpam/secrets-manager/developer-sdk-library/javascript-sdk)
* [`@aws-sdk/client-kms`](https://www.npmjs.com/package/@aws-sdk/client-kms) is bundled — no separate install required
  {% endtab %}

{% tab title="Python" %}

* Supports the [Python Secrets Manager SDK](https://docs.keeper.io/en/keeperpam/secrets-manager/developer-sdk-library/python-sdk)
* Requires boto3 package
  {% endtab %}

{% tab title=".Net" %}

* Supports the [.Net Secrets Manager SDK](https://docs.keeper.io/en/keeperpam/secrets-manager/developer-sdk-library/.net-sdk)
* Requires [AWSSDK.KeyManagementService](https://www.nuget.org/packages/AWSSDK.KeyManagementService)
  {% endtab %}
  {% endtabs %}

## Setup

### 1. Install Module

{% tabs %}
{% tab title="Java" %}
Setting up project using Gradle or Maven

**Gradle**

<pre><code>repositories {
  mavenCentral()
}

dependencies {
<strong>  implementation("com.keepersecurity.secrets-manager:aws:1.0.0")
</strong>  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")
}
</code></pre>

**Maven**

```xml
<!-- 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>
   	
```

{% endtab %}

{% tab title="JavaScript" %}
The Secrets Manager AWS Key Management Service Integration can be installed using npm

```bash
npm install @keeper-security/secrets-manager-aws
```

{% endtab %}

{% tab title="Python" %}
The Secrets Manager AWS KMS storage module can be installed using pip

```bash
pip3 install keeper-secrets-manager-storage
```

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

```bash
pip install boto3
```

{% endtab %}

{% tab title=".Net" %}
The Secrets Manager AWS Key Management Service Integration can be installed using

```bash
dotnet add package Keeper.SecretsManager.AWSKeyManagement
```

{% endtab %}
{% endtabs %}

### 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.

{% hint style="info" %}
See the AWS documentation for more information on setting up an AWS session: <https://docs.aws.amazon.com/cli/latest/reference/configure/>
{% endhint %}

Alternatively, configuration variables can be provided explicitly as an access key using the `AwsSessionConfig` data class and providing  `aws_access_key_id` , `aws_secret_access_key` and  `aws_session_token` variables.

{% hint style="info" %}
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/>
{% endhint %}

### 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**

{% tabs %}
{% tab title="Java" %}
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.

```java
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());
		}
	}
}

```

{% endtab %}

{% tab title="JavaScript" %}
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.

```javascript
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();

```

{% endtab %}

{% tab title="Python" %}
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.

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_hsm.storage_aws_kms import AwsKmsKeyValueStorage
 
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()
```

{% endtab %}

{% tab title=".Net" %}
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.

```csharp
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();
	}
}
```

{% endtab %}
{% endtabs %}

**Using Default Connection**

{% tabs %}
{% tab title="Java" %}
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.

{% code fullWidth="false" %}

```java
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());
		}
	}
}

```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
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.

```javascript
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();

```

{% endtab %}

{% tab title="Python" %}
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.

```python
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()

```

{% endtab %}

{% tab title=".Net" %}
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.

```csharp
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();
	}
}
```

{% endtab %}
{% endtabs %}

## 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.&#x20;

## Additional Options

### Change Key

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

{% tabs %}
{% tab title="Java" %}

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

{% endtab %}

{% tab title="JavaScript" %}

```
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);
```

{% endtab %}

{% tab title="Python" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_hsm.storage_aws_kms import AwsKmsKeyValueStorage
 
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)
```

{% endtab %}

{% tab title=".Net" %}

```csharp
    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>");
```

{% endtab %}
{% endtabs %}

### 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.

{% tabs %}
{% tab title="Java" %}

```java
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.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const storage = await new AWSKeyValueStorage(keyId,config_path).init();
await storage.decryptConfig(); 
```

{% endtab %}

{% tab title="Python" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_hsm.storage_aws_kms import AwsKmsKeyValueStorage
 
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)
is_decrypted = config.decrypt_config(True)
```

{% endtab %}

{% tab title=".Net" %}

```
var conf = await aws_storage.DecryptConfigAsync(false);
Console.WriteLine(conf);   
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
You're ready to use the KSM integration :thumbsup:
{% endhint %}

{% hint style="info" %}
Check out the [KSM SDKs documentation](https://docs.keeper.io/en/keeperpam/secrets-manager/developer-sdk-library) for more examples and functionality
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/en/keeperpam/secrets-manager/integrations/aws-kms.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.