1 of 2

Java/Kotlin SDK

Detailed Java and Kotlin SDK docs for Keeper Secrets Manager

Download and Installation

Install With Maven or Gradle

Cryptographic Provider

The Keeper Secrets Manager SDK expects the developer to use their required cryptographic provider. As documented above, Keeper will use the default cryptographic module of the Java runtime unless a specific provider is added. In the examples here in this documentation, we are using the BouncyCastle FIPS provider.

In the source code, ensure that the provider is loaded in the security context:

Source Code

Initialize Storage

Using token only to generate a new config (for later usage) requires at least one read operation to bind the token and fully populate config.json

In order to retrieve secrets, you must first initialize the local storage on your machine.

Example Usage

Retrieve Secrets

Response

Type: KeeperSecrets

Object containing all Keeper records, or records that match the given filter criteria

Example Usage

Retrieve all Secrets

Retrieve one secret by UID

Retrieve Secrets by Title

Example Usage

Retrieve Values From a Secret

Retrieve a Password

This shortcut gets the password of a secret once that secret has been retrieved from Keeper Secrets Manager.

Retrieve Fields

Keeper Notation

Get TOTP Code

Update Values in a Secret

Record update commands don't update local record data on success (esp. updated record revision) so any consecutive updates to an already updated record will fail due to revision mismatch. Make sure to reload all updated records after each update batch.

Update Secret

updateSecret(options: SecretsManagerOptions, recordToUpdate: KeeperRecord);

import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperSecrets;
import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import static com.keepersecurity.secretsManager.core.SecretsManager.*;

// Ensure security provider is loaded
Security.addProvider(new BouncyCastleFipsProvider());

// get secrets
SecretsManagerOptions options = SecretsManagerOptions(storage);
KeeperSecrets secrets = getSecrets(options);

// we'll update the first record
KeeperRecord recordToUpdate = secrets.getRecords().get(0);

// update password
recordToUpdate.updatePassword("aP1$t367QOCvL$eM$bG#");

// update title and notes
recordToUpdate.data.title = "New Title"
recordToUpdate.data.notes = "My Notes"

// save changes
updateSecret(options, recordToUpdate);

import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperSecrets;
import com.keepersecurity.secretsManager.core.SecretsManagerOptions;

import static com.keepersecurity.secretsManager.core.SecretsManager.*;

...

// get secrets
SecretsManagerOptions options = SecretsManagerOptions(storage);
KeeperSecrets secrets = getSecrets(options);

// we'll update the first record
KeeperRecord record = secrets.getRecords().get(0);

// rotate password on the record
record.updatePassword("aP1$t367QOCvL$eM$bG#");

// start a transaction
updateSecret(options, record, transactionType = UpdateTransactionType.GENERAL);
// rotate password on remote host
boolean success = rotateRemoteSshPassword("aP1$t367QOCvL$eM$bG#");
// complete the transaction - commit or rollback
completeTransaction(options, record.recordUid, rollback = !success);

Update Secret is used to save changes made to a secret. Once updateSecret is performed successfully, the changes are reflected in the Keeper Vault.

Parameter

Type

Required

Default

Description

options

SecretsManagerOptions

Yes

Storage and query configuration

recordToUpdate

KeeperRecord

Yes

Record to update

Update Password

recordToUpdate.updatePassword(password: String);

SecretsManager.updateSecret(options, recordToUpdate);

import static com.keepersecurity.secretsManager.core.SecretsManager;

import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperSecrets;

// get secrets
SecretsManagerOptions options = SecretsManagerOptions(storage);
KeeperSecrets secrets = getSecrets(options);

// we'll update the first record
KeeperRecord recordToUpdate = secrets.getRecords().get(0);

// update password
recordToUpdate.updatePassword("aP1$t367QOCvL$eM$bG#");

// save changes
SecretsManager.updateSecret(options, recordToUpdate);

Parameter

Type

Required

Default

Description

password

String

Yes

New password to set

Update other fields

//format
RecordField.getValue().set(index, value)

//example - Login field
recordLogin.getValue().set(0, "New Login");

// get field to edit
Login recordLogin = (Login) recordToUpdate.getData().getField(Login.class);

// update field value
recordLogin.getValue().set(0, "New Login");

// save changes
SecretsManager.updateSecret(options, recordToUpdate);

Fields can have multiple values, which is accessed in a List. In this example we are updating the login field, which only accepts one value, so we update the one value in the values list.

Generate a Random Password

generatePassword(length: int, lowercase: int, uppercase: int, digits: int, specialCharacters: int)

import com.keepersecurity.secretsManager.core.CryptoUtils;

// Ensure security provider is loaded
Security.addProvider(new BouncyCastleFipsProvider());

// get field to edit
Password recordPassword = (Password) recordToUpdate.getData().getField(Password.class);

// generate a random password
String password = CryptoUtils.generatePassword();

// update field value
recordPassword.getValue().set(0, password);

// save changes
SecretsManager.updateSecret(options, recordToUpdate);

Parameter

Type

Required

Default

length

int

Optional

lowercase

int

Optional

uppercase

int

Optional

digits

int

Optional

specialCharacters

int

Optional

Each parameter indicates the min number of a type of character to include. For example, 'uppercase' indicates the minimum number of uppercase letters to include.

Download a File

SecretsManager.downloadFile(file): ByteArray

import static com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperFile;

// Ensure security provider is loaded
Security.addProvider(new BouncyCastleFipsProvider());

// download the first file from the first record
KeeperRecord firstRecord = secrets.getRecords().get(0);
KeeperFile file = firstRecord.getFileByName("acme.cer");
byte[] fileBytes = SecretsManager.downloadFile(file);

// write file to a disk
try (FileOutputStream fos = new FileOutputStream(file.getData().getName())) {
    fos.write(fileBytes);
} catch (IOException ioException){
    ioException.printStackTrace();
}

Parameter

Type

Required

Default

Description

file

KeeperFile

Yes

File to download

Response

Type: ByteArray

ByteArray of file for download

Download a Thumbnail

SecretsManager.downloadThumbnail(file): ByteArray

import static com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperFile;

// Ensure security provider is loaded
Security.addProvider(new BouncyCastleFipsProvider());

// download the first file from the first record
KeeperRecord firstRecord = secrets.getRecords().get(0);
KeeperFile file = firstRecord.getFileByName("acme.cer");
byte[] fileBytes = SecretsManager.downloadThumbnail(file);

// write file to a disk
try (FileOutputStream fos = new FileOutputStream(file.getData().getName())) {
    fos.write(fileBytes);
} catch (IOException ioException){
    ioException.printStackTrace();
}

Response

Type: ByteArray

ByteArray of thumbnail for download

Upload a File

Upload File:

Creating the Keeper File Upload Object:

Example Usage

Create a Secret

Prerequisites:

Shared folder UID
- Shared folder must be accessible by the Secrets Manager Application
- You and the Secrets Manager application must have edit permission
- There must be at least one record in the shared folder
Created records and record fields must be formatted correctly
TOTP fields accept only URL generated outside of the KSM SDK

This example creates a record with a custom record type.

Replace '[FOLDER UID]' in the example with the UID of a shared folder that your Secrets Manager Application has access to.

Delete a Secret

The Java/Kotlin KSM SDK can delete records in the Keeper Vault.

Caching

To protect against losing access to your secrets when network access is lost, the Java SDK allows caching of secrets to the local machine in an encrypted file.

Setup and Configure Cache

In order to setup caching in the Java SDK, include a caching post function as the second argument when instantiating aSecretsManagerOptions object.

The Java SDK includes a default caching function cachingPostFunction which stores cached queries to a file.

Folders

Folders have full CRUD support - create, read, update and delete operations.

Read Folders

Downloads full folder hierarchy.

Response

Type: List<KeeperFolder>

Example Usage

Create a Folder

Requires CreateOptions and folder name to be provided. The folder UID parameter in CreateOptions is required - UID of a shared folder, while sub-folder UID is optional and if missing new regular folder is created directly under the parent (shared folder). There's no requirement for the sub-folder to be a direct descendant of the parent shared folder - it could be many levels deep.

Example Usage

Update a Folder

Updates the folder metadata - currently folder name only.

Example Usage

Delete Folders

Removes a list of folders. Use forceDeletion flag to remove non-empty folders.

When using forceDeletion avoid sending parent with its children folder UIDs. Depending on the delete order you may get an error - ex. if parent force-deleted child first. There's no guarantee that list will always be processed in FIFO order.

Any folders UIDs missing from the vault or not shared to the KSM Application will not result in error.

Example Usage