Java/Kotlin SDK

Detailed Java and Kotlin SDK docs for Keeper Secrets Manager

Download and Installation

Install With Maven or Gradle

Gradle

build.gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.keepersecurity.secrets-manager:core:17.1.2+'
    implementation("org.bouncycastle:bc-fips:1.0.2.4")
}

Maven

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:

fun main() {
    Security.addProvider(BouncyCastleFipsProvider())
...

See the file CryptoUtilsTest.kt as shown in this example on how to use a custom security provider.

Source Code

Find the Java/Kotlin source code in the GitHub repository

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.

initializeStorage(storage: KeyValueStorage, clientKey: String? = null, hostName: String? = null)

Parameter	Type	Required	Default	Description
storage	KeyValueStorage	Yes
clientKey	String	Optional	null
hostName	String	Optional	null

Example Usage

import static com.keepersecurity.secretsManager.core.SecretsManager.initializeStorage;
import com.keepersecurity.secretsManager.core.LocalConfigStorage;
import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

// oneTimeToken is used only once to initialize the storage
// after the first run, subsequent calls will use "ksm-config.txt" file
String oneTimeToken = "[One Time Access Token]";
LocalConfigStorage storage = new LocalConfigStorage("ksm-config.txt");

Security.addProvider(new BouncyCastleFipsProvider());

try {
    initializeStorage(storage, oneTimeToken);
    SecretsManagerOptions options = new SecretsManagerOptions(storage);
    // Using token only to generate a config (for later usage)
    // requires at least one access operation to bind the token
    //getSecrets(options)
 } catch (Exception e) {
    System.out.println(e.getMessage());
 }

Retrieve Secrets

getSecrets(options: SecretsManagerOptions, recordsFilter: List<String> = emptyList()): KeeperSecrets

Parameter	Type	Required	Default	Description
options	SecretsManagerOptions	Yes		Storage and query configuration
recordsFilter	List<String>	Optional	Empty List	Record search filters

Response

Type: KeeperSecrets

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

Example Usage

Retrieve all Secrets

import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperSecrets;
import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

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

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

//get records from secrets
List<KeeperRecord> records = secrets.getRecords();

Retrieve one secret by UID

import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperSecrets;
import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

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

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

// identify one or more record UID to fetch secrets by
List<String> uidFilter = List.of("[XXX]");

// fetch secrets with the filter
KeeperSecrets secrets = SecretsManager.getSecrets(options, uidFilter);

//get records from secrets
List<KeeperRecord> records = secrets.getRecords();

Retrieve Secrets by Title

// get all matching records
getSecretsByTitle(recordTitle: String): List<KeeperRecord>

// get only the first matching record
getSecretByTitle(recordTitle: String): KeeperRecord

Parameter	Type	Required	Description
recordTitle	String	Yes	Record title to search for

Example Usage

import com.keepersecurity.secretsManager.core.*;
import java.util.List;

public class KSMSample {
    public static void main(String[] args){
        
        // Ensure security provider is loaded
        Security.addProvider(new BouncyCastleFipsProvider());

        // get pre-initialized storage
        KeyValueStorage storage = new LocalConfigStorage("ksm-config.json");
        try {
            SecretsManagerOptions options = new SecretsManagerOptions(storage);

            // title of the record to fetch
            String recordTitle = "My Credentials";
            
            // search for record by title
            KeeperRecord myCredentials = secrets.getRecords().getSecretByTitle(recordTitle);

            // print out record details
            System.out.println("Record UID: " + myCredentials.getRecordUid());
            System.out.println("Title: " + myCredentials.getData().getTitle());
        } catch (Exception e) {
            System.out.println(e.getMessage());
        }
    }
}

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.

Get Password

secret.getPassword()

Example Usage

Retrieve Fields

Get Field

secret.getData().getField(<FIELD_TYPE>)

Example Usage

To get a field value, you will need to cast the return to the class of the corresponding field type. For a list of field types see the Record Types page.

Keeper Notation

Get Value

Notation.getValue(secret, "<query>");
// Query example "<RECORD UID>/field/login"

Example Usage

See Keeper Notation documentation to learn about Keeper Notation format and capabilities

Parameter	Type	Required	Default	Description
secret	KeeperRecord	Yes		Record to get field value from
query	String	Yes		Dot notation query of desired field

Get TOTP Code

Get TOTP Code

TotpCode.uriToTotpCode(url)

Example Usage

Parameter	Type	Required	Default	Description
url	String	Yes		TOTP Url

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

Update Secret

updateSecret(options: SecretsManagerOptions, recordToUpdate: KeeperRecord);

Example Usage

Transactional updates

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

Update Password

recordToUpdate.updatePassword(password: String);

SecretsManager.updateSecret(options, recordToUpdate);

Example Usage

Parameter	Type	Required	Default	Description
password	String	Yes		New password to set

Update other fields

Set Value

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

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

Example Usage

Each record field type is represented by a class. Cast the field to the corresponding class in order to correctly access the field's value. Check the Record Types documentation for a list of field types.

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

Generate Password

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

Example Usage

Parameter	Type	Required	Default
length	int	Optional	64
lowercase	int	Optional	0
uppercase	int	Optional	0
digits	int	Optional	0
specialCharacters	int	Optional	0

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

Download File

SecretsManager.downloadFile(file): ByteArray

Example Usage

Parameter	Type	Required	Default	Description
file	KeeperFile	Yes		File to download

Response

Type: ByteArray

ByteArray of file for download

Download a Thumbnail

Download Thumbnail

SecretsManager.downloadThumbnail(file): ByteArray

Example Usage

Parameter	Type	Required	Default	Description
file	KeeperFile	Yes		File with thumbnail to download

Response

Type: ByteArray

ByteArray of thumbnail for download

Upload a File

Upload File:

uploadFile(options: SecretsManagerOptions, ownerRecord: KeeperRecord, file: KeeperFileUpload): String

Parameter	Type	Required	Description
options	SecretsManagerOptions	Yes	Storage and query configuration
ownerRecord	KeeperRecord	Yes	The record to attach the uploaded file to
file	KeeperFileUpload	Yes	The File to upload

Creating the Keeper File Upload Object:

KeeperFileUpload(
    val name: String,
    val title: String,
    val type: String?,
    val data: ByteArray
)

Parameter	Type	Required	Description
name	string	Yes	What the name of the file will be in Keeper once uploaded
title	string	Yes	What the title of the file will be in Keeper once uploaded
type	string	Optional	The mime type of data in the file. 'application/octet-stream' will be used if nothing is given
data	ByteArray	Yes	File data as bytes

Example Usage

import com.keepersecurity.secretsManager.core.*;

import java.io.File;
import java.io.FileInputStream;
import java.util.Arrays;

public class KSMSample {
    public static void main(String[] args){
    
        // Ensure security provider is loaded
        Security.addProvider(new BouncyCastleFipsProvider());

        // get pre-initialized storage
        KeyValueStorage storage = new LocalConfigStorage("ksm-config.json");
        try {
            SecretsManagerOptions options = new SecretsManagerOptions(storage);

            // create a filter with the UID of the record we want
            List<String> uidFilter = List.of("XXX");

            // fetch secrets with the filter
            KeeperSecrets secrets = SecretsManager.getSecrets(options, uidFilter);

            // get the desired secret to upload a file to
            KeeperRecord ownerRecord = secrets.getRecords().get(0);
        
            // get bytes from file to upload
            File file = new File("./myFile.json");
            FileInputStream fl = new FileInputStream(file);
            byte[] fileBytes = new byte[(int)file.length()];
            fl.read(fileBytes);
            fl.close();
            
            // create a Keeper File to upload
            KeeperFileUpload myFile = new KeeperFileUpload(
                "myFile.json",
                "My File", 
                "application/json", 
                fileBytes
            )

            // upload the file to the selected record
            SecretsManager.uploadFile(options, ownerRecord, myFile);
            
        } catch (Exception e) {
            System.out.println("KSM ran into an problem: " + e.getMessage());
        }
    }
}

Remove Files from a Record

SDK Version Required: 17.1.1 or higher

This feature add the ability to remove file attachments from records using the UpdateOptions class with the linksToRemove parameter.

Prerequisites:

• Record UID or KeeperRecord object containing files

• File UIDs of the files to be removed

• Files must exist on the record to be removed

Remove Files

Parameter	Type	Required	Default	Description
options	SecretsManagerOptions	Yes		Preconfigured options
record	KeeperRecord	Yes		The record to update
updateOptions	UpdateOptions	Yes		Options containing files to remove

UpdateOptions

Example (Java)

Example (Kotlin)

Full Example Usage:

import com.keepersecurity.secretsManager.core.*;
import java.util.*;

// Get record with files
QueryOptions queryOptions = new QueryOptions(
    Arrays.asList(recordUid),
    Collections.emptyList(),
    true  // request files
);

KeeperSecrets secrets = SecretsManager.getSecrets2(options, queryOptions);
KeeperRecord record = secrets.getRecords().get(0);

// Remove specific files
List<String> fileUidsToRemove = Arrays.asList("fileUid1", "fileUid2");

UpdateOptions updateOptions = new UpdateOptions(
    null,              // transactionType
    fileUidsToRemove  // linksToRemove
);

SecretsManager.updateSecretWithOptions(options, record, updateOptions);

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

  • See the documentation for expected field formats for each record type

• TOTP fields accept only URL generated outside of the KSM SDK

• After record creation, you can upload file attachments using uploadFile

Create a Record

SecretsManager.createSecret(options, folderUid, newRecordData, secrets);

Parameter	Type	Required	Default
options	SecretsManagerOptions	Yes
folderUid	String	Yes
newRecordData	KeeperRecordData	Yes
secrets	KeeperSecrets	Optional	Freshly fetched list of all secrets from the Keeper servers

Create Record in Sub-folder

Login Record Example

Custom Type Example

Delete a Secret

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

Delete Secret

deleteSecret(smOptions, recordUids);

Parameter	Type	Required
smOptions	SecretsManagerOptions	Yes
recordUids	List<Sting>	Yes

Example

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.

//create options with caching
SecretsManagerOptions options = new SecretsManagerOptions(storage, SecretsManager::cachingPostFunction);

//example get all secrets
SecretsManager.getSecrets(options)

Folders

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

Read Folders

Downloads full folder hierarchy.

getFolders(options: SecretsManagerOptions): List<KeeperFolder>

Response

Type: List<KeeperFolder>

Example Usage

import com.keepersecurity.secretsManager.core.*;
SecretsManagerOptions options = new SecretsManagerOptions(new LocalConfigStorage("ksm-config.json"));
List<KeeperFolder> folders = SecretsManager.getFolders(options);

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.

createFolder(options: SecretsManagerOptions, createOptions: CreateOptions, folderName: String, folders: List<KeeperFolder> = getFolders(options)): String

Parameter	Type	Required	Default	Description
options	SecretsManagerOptions	Yes		Preconfigured options
createOptions	CreateOptions	Yes		The parent and sub-folder UIDs
folderName	String	Yes		The Folder name
folders	List<KeeperFolder>	No	List<KeeperFolder>	List of folders to use in the search for parent and sub-folder from CreateOptions

data class CreateOptions  constructor(
    val folderUid: String,
    val subFolderUid: String? = null,
)

data class KeeperFolder(
    val folderKey: ByteArray,
    val folderUid: String,
    val parentUid: String? = null,
    val name: String
)

Example Usage

import com.keepersecurity.secretsManager.core.*;
SecretsManagerOptions options = new SecretsManagerOptions(new LocalConfigStorage("ksm-config.json"));
CreateOptions co := new CreateOptions("[PARENT_SHARED_FOLDER_UID]");
String folderUid = SecretsManager.createFolder(options, co, "new_folder");

Update a Folder

Updates the folder metadata - currently folder name only.

updateFolder(options: SecretsManagerOptions, folderUid: String, folderName: String, folders: List<KeeperFolder> = getFolders(options))

Parameter	Type	Required	Default	Description
options	SecretsManagerOptions	Yes		Preconfigured options
folderUid	String	Yes		The folder UID
folderName	String	Yes		The new folder name
folders	List<KeeperFolder>	No	List<KeeperFolder>	List of folders to use in the search for parent folder

Example Usage

import com.keepersecurity.secretsManager.core.*;
SecretsManagerOptions options = new SecretsManagerOptions(new LocalConfigStorage("ksm-config.json"));
SecretsManager.updateFolder(options, "[FOLDER_UID]", "new_folder_name");

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.

deleteFolder(options: SecretsManagerOptions, folderUids: List<String>, forceDeletion: Boolean = false): SecretsManagerDeleteResponse

Parameter	Type	Required	Default	Description
options	SecretsManagerOptions	Yes		Preconfigured options
folderUids	List<String>	Yes		The folder UID list
forceDeletion	Boolean	No	false	Force deletion of non-empty folders

Example Usage

import com.keepersecurity.secretsManager.core.*;
SecretsManagerOptions options = new SecretsManagerOptions(new LocalConfigStorage("ksm-config.json"));
SecretsManager.deleteFolder(options, Arrays.asList("[FOLDER_UID1]", "[FOLDER_UID2]"), true);

PAM Records Types - Accessing Linked Credentials

SDK Version Required: 17.1.1 or higher

On PAM Resource Records Types (PAM Machine, PAM Directory, PAM Database), the following credentials can be linked:

• Administrative Credentials - the credentials used to perform administrative operations on the resource

• Launch Credentials - the credentials used to authenticate a launched session to the resource

Prerequisites:

• Use getSecrets2() method instead of getSecrets()

• Set requestLinks = true in QueryOptions to enable GraphSync™

• Links will be null if requestLinks is false, empty list if true but no links exist

Parameter	Type	Required	Default	Description
options	SecretsManagerOptions	Yes		Preconfigured options
queryOptions	QueryOptions	Yes		Must set requestLinks=true

QueryOptions Parameters

Parameter	Type	Required	Default	Description
recordsFilter	List<String>	No	Empty	Filter by record UIDs
foldersFilter	List<String>	No	Empty	Filter by folder UIDs
requestLinks	boolean	Yes	false	Must be true for GraphSync

Link Methods

Method	Returns	Description
getRecordUid()	String	Target record UID
isAdminUser()	boolean	Admin privileges
allowsRotation()	boolean	Rotation allowed
allowsConnections()	boolean	Connections allowed

Basic Usage - Retrieve Records with Links

import com.keepersecurity.secretsManager.core.*;
import java.util.*;

// Enable GraphSync™
QueryOptions queryOptions = new QueryOptions(
    Collections.emptyList(),  // recordsFilter
    Collections.emptyList(),  // foldersFilter
    true                      // requestLinks - REQUIRED
);

SecretsManagerOptions options = new SecretsManagerOptions(storage);
KeeperSecrets secrets = SecretsManager.getSecrets2(options, queryOptions);

// Access links
for (KeeperRecord record : secrets.getRecords()) {
    List<KeeperRecordLink> links = record.getLinks();
    if (links != null && !links.isEmpty()) {
        for (KeeperRecordLink link : links) {
            System.out.println("Links to: " + link.getRecordUid());
        }
    }
}

Check Link Properties

for (KeeperRecordLink link : record.getLinks()) {
    // Check user privileges
    if (link.isAdminUser()) {
        System.out.println("Admin user");
    }
    
    // Check permissions
    if (link.allowsRotation()) {
        System.out.println("Password rotation allowed");
    }
}

Common Example - Find PAM Users

// Find users associated with a PAM machine
for (KeeperRecord machine : secrets.getRecords()) {
    if ("pamMachine".equals(machine.getType())) {
        System.out.println("PAM Machine: " + machine.getTitle());
        
        List<KeeperRecordLink> links = machine.getLinks();
        if (links != null) {
            for (KeeperRecordLink link : links) {
                // Check if user is admin
                if (link.isAdminUser()) {
                    System.out.println("  Admin user: " + link.getRecordUid());
                }
            }
        }
    }
}

Additional Details

For detailed information on the retrievable fields on the PAM record types, see the Record Field Classes page.

For examples on handling Linked Credentials for advanced PAM use cases, see the Linked Credentials on PAM records page.