Oracle Cloud Infrastructure (OCI) Vault Encryption

Protect Secrets Manager connection details with OCI Vault

Keeper Secrets Manager integrates with Oracle Cloud Infrastructure (OCI) Vault in order to provide protection 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 OCI Vault
• 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

Java

• Support the Java/Kotlin Secrets Manager SDK.
• Required Oracle packages: oci-java-sdk-keymanagement, oci-java-sdk-common and oci-java-sdk-common-httpclient-jersey.
• OCI Key needs ENCRYPT and DECRYPT permissions.

JavaScript

• Supports the JavaScript Secrets Manager SDK
• oci-keymanagement is bundled — no separate install required.
• OCI KMS Key needs ENCRYPT and DECRYPT permissions.

Python

• Supports the Python Secrets Manager SDK
• Requires oci package
• User credentials to be used will need to have OCI vault permissions

.Net

• Supports the .Net Secrets Manager SDK.
• Requires OCI.DotNetSDK.Keymanagement.
• Requires 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:oracle:1.0.0")
  implementation("com.keepersecurity.secrets-manager:core:17.0.0")
  implementation("com.oracle.oci.sdk:oci-java-sdk-keymanagement:3.60.0")
  implementation("com.oracle.oci.sdk:oci-java-sdk-common-httpclient-jersey:3.60.0") // or the latest version
  implementation("com.oracle.oci.sdk:oci-java-sdk-common:3.60.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-simple:2.0.16")
  implementation("org.bouncycastle:bc-fips:1.0.2.4")
}

Maven

<!-- KMS-core -->
    <dependency>
     <groupId>com.keepersecurity.secrets-manager</groupId>
     <artifactId>oracle</artifactId>
     <version>1.0.0</version>
    </dependency>
    <dependency>
     <groupId>com.keepersecurity.secrets-manager</groupId>
     <artifactId>core</artifactId>
     <version>17.0.0</version>
    </dependency>

<!-- oci-kv -->
   <dependency>
       <groupId>com.oracle.oci.sdk</groupId>
       <artifactId>oci-java-sdk-keymanagement</artifactId>
       <version>3.60.0</version>
   </dependency>
   <dependency>
       <groupId>com.oracle.oci.sdk</groupId>
       <artifactId>oci-java-sdk-common-httpclient-jersey</artifactId>
       <version>3.60.0</version>
   </dependency>
   <dependency>
       <groupId>com.oracle.oci.sdk</groupId>
       <artifactId>oci-java-sdk-common</artifactId>
       <version>3.60.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>

   <dependency>
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-simple</artifactId>
       <version>2.0.16</version>
   </dependency>   	
   <!-- bc-fips -->
   <dependency>
   	<groupId>org.bouncycastle</groupId>
   	<artifactId>bc-fips</artifactId>
   	<version>1.0.2.4</version>
   </dependency>
   	

JavaScript

The Secrets Manager OCI Vault module can be installed using npm

npm install @keeper-security/secrets-manager-oracle-kv

Python

The Secrets Manager OCI KSM module can be installed using pip

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

oci is a prerequisite for the OCI Vault integration. Install it to your machine using pip.

pip3 install oci

.Net

The Secrets Manager OCI Vault module can be installed using dotnet nuget package manager.

dotnet add package Keeper.SecretsManager.OracleKeyManagement

2. Configure OCI Vault Connection

Ensure that you have an OCI Vault instance available, and you know its OCID (Oracle Cloud Identifier). By default, the `oci key management` library will use the default OCI configuration file (~/.oci/config)

See the Oracle documentation for more information on setting up OCI Keys:

https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdkconfig.htm

Alternatively, You will need to add the correct configuration for your OCI environment, including the details for accessing OCI Vault.

The configuration file should look like this (replace with your actual details):

[DEFAULT] user=ocid1.user.oc1..example_unique_id fingerprint=xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx key_file=/path/to/your/private/api/key.pem tenancy=ocid1.tenancy.oc1..example_unique_id region=us-phoenix-1

3. Add OCI Vault Storage to Your Code

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

Using OCI Vault Integration

Once setup, the Secrets Manager OCI Vault integration supports all Secrets Manager SDK functionality. Your code will need to be able to access the OCI Keys in order to manage the encryption and decryption of the KSM configuration file. Using Specified Connection credentials

Java

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

The OracleKeyValueStorage will require the name of the Secrets Manager configuration file with profile and configuration.

import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;
import static com.keepersecurity.secretsManager.core.SecretsManager.initializeStorage;
import com.keepersecurity.secretmanager.oracle.kv.OracleKeyValueStorage;
import com.keepersecurity.secretmanager.oracle.kv.OracleSessionConfig;
import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import com.oracle.bmc.Region;


class Test {
	public static void main(String args[]){
		String configPath = "<~/.oci/config>";
		String cryptoEndpoint = "https://<>-crypto.kms.<oracle_cloud_region>.oraclecloud.com";
		String vaultId = "<OCI VAULT ID>";
		String keyId = "<OCI KEY ID>";
		String keyVersionId = "<OCI KEY VERSION>";
		String configFileLocation = "<KSM CONFIG FILE LOCATION>";
		String profile = "<OCI CONFIG PROFILE EX: DEFAULT>"; // name of your profile
		String oneTimeToken = "<Keeper One Time Token>";
		String managementEndpoint =  "https://<>-management.kms.<oracle_cloud_region>.oraclecloud.com";
		Region region = Region.<cloud_region>;
		Security.addProvider(new BouncyCastleFipsProvider());
		try{
			//set OCI Vault configuration, 
			OracleSessionConfig oracleSessionConfig = new OracleSessionConfig(configPath, cryptoEndpoint, managementEndpoint, vaultId, keyId, keyVersionId, region);
			//Get Storage 
			OracleKeyValueStorage oracleKeyValueStorage = new OracleKeyValueStorage(configFileLocation, profile, oracleSessionConfig);
			initializeStorage(oracleKeyValueStorage, oneTimeToken);
			SecretsManagerOptions options = new SecretsManagerOptions(oracleKeyValueStorage);
			//getSecrets(options)
		}catch (Exception e) {
			System.out.println(e.getMessage());
		}
	}
}

JavaScript

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

The storage will require an OCI config file location, OCI configuration profile (if there are multiple profile configurations) and the OCI KMS Crypto endpoint , OCI KMS Management endpoint as well as the name of the Secrets Manager configuration file which will be encrypted by OCI Vault.

import { getSecrets, initializeStorage } from "@keeper-security/secrets-manager-core";
import { OCISessionConfig, OciKeyValueStorage, LoggerLogLevelOptions } from "@keeper-security/secrets-manager-oracle-kv";

const getKeeperRecordsOCI = async () => {
    const oracleConfigFileLocation = "/home/<user>/.oci/config";
    const oracleProfile = "DEFAULT";
    const kmsCryptoEndpoint = "https://<id>-crypto.kms.<region>.oraclecloud.com";
    const kmsManagementEndpoint = "https://<id>-management.kms.<region>.oraclecloud.com";
    const ociSessionConfig = new OCISessionConfig(oracleConfigFileLocation, oracleProfile, kmsCryptoEndpoint, kmsManagementEndpoint);
    const logLevel = LoggerLogLevelOptions.info;
    const configPath = "<path_to_client-config.json>";

    // 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 keyId = "ocid1.key.oc1.iad.<unique_id>";
    const keyVersionId = "ocid1.keyversion.oc1.iad.<unique_id>";

    const storage = await new OciKeyValueStorage(keyId, keyVersionId, configPath, ociSessionConfig, 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]);
};
getKeeperRecordsOCI();

Python

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

The storage will require a OCI Key ID, key version Id, KMS Crypto endpoint, KMS management endpoint, OCI config file location, configuration profile as well as the name of the Secrets Manager configuration file which will be encrypted by OCI Vault and OCI session configuration shown below.

from keeper_secrets_manager_storage_oracle_kms import OracleKeyValueStorage, OCISessionConfig
from keeper_secrets_manager_core import SecretsManager
config_file_location = "/home/<user>/.oci/config"
profile = "DEFAULT"
kms_crypto_endpoint = "https://<id>-crypto.kms.<region>.oraclecloud.com"
kms_management_endpoint = "https://<id>-management.kms.<region>.oraclecloud.com"
key_id = '<key_id>'
key_version_id = "<key_version_id>"
config_path = "<path to config json>"
one_time_token = "<Keeper One Time Token>"
oci_session_config = OCISessionConfig(config_file_location, profile, kms_crypto_endpoint, kms_management_endpoint)
storage = OracleKeyValueStorage(key_id=key_id, key_version=key_version_id, config_file_location=config_path, oci_session_config=oci_session_config,logger=None)
secrets_manager = SecretsManager(one_time_token,config=storage)
all_records = secrets_manager.get_secrets()
first_record = all_records[0]
print(first_record)

.Net

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

The storage will require a OCI Key ID, key version Id, KMS Crypto endpoint, KMS management endpoint, OCI config file location, configuration profile as well as the name of the Secrets Manager configuration file which will be encrypted by OCI Vault and OCI session configuration shown below.

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

public class Program
{
    private static async Task Main()
    {
        var ociConfigFileLocation = "<path_to_oci_config>";
        var profile = "DEFAULT";
        var kmsCryptoEndpoint = "https://<id>-crypto.kms.<region>.oraclecloud.com";
        var kmsManagementEndpoint = "https://<id>-management.kms.<region>.oraclecloud.com";
        var ociSessionConfig = new OciSessionConfig(ociConfigFileLocation, profile, kmsCryptoEndpoint, kmsManagementEndpoint);

        var path = "ksm_config.json";
        string keyId = "<oci_key_id>";
        string keyVersionId = "<oci_key_version_id>";

        var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder.SetMinimumLevel(LogLevel.Debug);
            builder.AddConsole();
        });
        var logger = loggerFactory.CreateLogger<OracleKeyValueStorage>();
        var storage = new OracleKeyValueStorage(keyId, keyVersionId, path, ociSessionConfig, logger);

        var oneTimeToken = "<one_time_token>";
        SecretsManagerClient.InitializeStorage(storage, oneTimeToken);

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

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

//The method changeKey(keyID, keyVersion) will be used to encrypt the KSM config file with new Key and version. 

String newKeyID = "<new Key ID>";
String newKeyVersion = "<New Key Version>";
OracleKeyValueStorage oracleKeyValueStorage = new OracleKeyValueStorage(configFileLocation, profile, oracleSessionConfig);
oracleKeyValueStorage.changeKey(newKeyID, newKeyVersion); // Change the key for encryption/decryption

JavaScript

// To change the OCI Vault key used for encryption, call the changeKey method on the OciKeyValueStorage instance.
const newKeyId = "ocid1.key.oc1.iad.<new_unique_id>";
const newKeyVersionId = "ocid1.keyversion.oc1.iad.<new_unique_id>";
const storage = await new OciKeyValueStorage(keyId, keyVersionId, configPath, ociSessionConfig).init();
await storage.changeKey(newKeyId, newKeyVersionId);

Python

   storage = OracleKeyValueStorage(key_id=key_id, key_version=key_version_id, config_file_location=config_path, oci_session_config=oci_session_config,logger=None)
    
    new_key_id = "<new key id>"
    new_key_version_id = "<new key version>"
    isChanged = storage.change_key(new_key_id, new_key_version_id)
    print(f"Key is changed: {isChanged}")

.Net

// To change the OCI Vault key used for encryption, call ChangeKeyAsync on the OracleKeyValueStorage instance.
var storage = new OracleKeyValueStorage(keyId, keyVersionId, path, ociSessionConfig, logger);
string newKeyId = "<new_oci_key_id>";
string newKeyVersionId = "<new_oci_key_version_id>";
await storage.ChangeKeyAsync(newKeyId, newKeyVersionId, null);

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

OracleKeyValueStorage oracleKeyValueStorage = new OracleKeyValueStorage(configFileLocation, profile, oracleSessionConfig);
oracleKeyValueStorage.decryptConfig(false); // Set false as a parameter to extract only plaintext.
//OR 
oracleKeyValueStorage.decryptConfig(true); // Set true as a parameter to extract plaintext and save config as a plaintext.

JavaScript

const storage = await new OciKeyValueStorage(keyId, keyVersionId, configPath, ociSessionConfig).init();

// Returns plaintext only (file stays encrypted)
const plaintext = await storage.decryptConfig(false);

// OR: returns plaintext and saves config as plaintext
const saved = await storage.decryptConfig(true);

Python

storage = OracleKeyValueStorage(key_id=key_id, key_version=key_version_id, config_file_location=config_path, oci_session_config=oci_session_config, logger=None)

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

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

.Net

// To decrypt the config file and revert to plaintext, call DecryptConfigAsync on the OracleKeyValueStorage instance.
var conf = await storage.DecryptConfigAsync(false); // Returns plaintext only
Console.WriteLine(conf);
// OR
var conf = await 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