Java/Kotlin SDK

Keeperシークレットマネージャー用JavaとKotlin SDKの詳細

ダウンロードとインストール

MavenまたはGradleを使用したインストール

Gradle

build.gradle

repositories {
    mavenCentral()
}

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

Maven

暗号化プロバイダ

KeeperシークレットマネージャーSDK では、開発者が必要とされる暗号化プロバイダを使用することが想定されています。特定のプロバイダが追加されない限り、Javaランタイムのデフォルトの暗号化モジュールを使用します。本ページの例では、BouncyCastle FIPSプロバイダを使用しています。

ソースコードで、プロバイダがセキュリティコンテキストにロードされていることを確認します。

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

カスタムセキュリティプロバイダーの使用方法については、こちらのページの CryptoUtilsTest.kt ファイルをご参照ください。

ソースコード

Java/Kotlinのソースコードは、GitHubリポジトリで入手できます。

ストレージの初期化

(後で使用するために) トークンのみを使用して新しい構成を生成するには、トークンをバインドしてconfig.jsonに完全に読み込むために、少なくとも1回の読み取り操作が必要となります。

シークレットを取得するには、まずマシンのローカルストレージを初期化する必要があります。

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

パラメータ	型	必須	デフォルト	説明
storage	KeyValueStorage	はい
clientKey	String	オプション	null
hostName	String	オプション	null

使用例

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はストレージの初期化に一度だけ使用
// 初回実行以降の呼び出しでは「ksm-config.txt」ファイルを使用
String oneTimeToken = "[One Time Access Token]";
LocalConfigStorage storage = new LocalConfigStorage("ksm-config.txt");

try {
    initializeStorage(storage, oneTimeToken);
    SecretsManagerOptions options = new SecretsManagerOptions(storage);
    // トークンのみを使用して（後で使用するために）設定を生成するには
    // トークンをバインドするアクセス操作が少なくとも1回必要です
    //getSecrets(options)
 } catch (Exception e) {
    System.out.println(e.getMessage());
 }

シークレットの取得

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

パラメータ	型	必須	デフォルト	説明
options	SecretsManagerOptions	はい		ストレージとクエリの設定
recordsFilter	List<String>	オプション	空のリスト	レコードの検索フィルタ

レスポンス

型: KeeperSecrets

すべてのKeeperレコード、または指定したフィルタ条件に一致するレコードを含むオブジェクト

使用例

すべてのシークレットを取得

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;

// セキュリティプロバイダがロードされていることを確認
Security.addProvider(new BouncyCastleFipsProvider());

// シークレットを取得
SecretsManagerOptions options = new SecretsManagerOptions(storage);
KeeperSecrets secrets = SecretsManager.getSecrets(options);

// シークレットからレコードを取得
List<KeeperRecord> records = secrets.getRecords();

UIDで1つのシークレットを取得

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;

// セキュリティプロバイダがロードされていることを確認
Security.addProvider(new BouncyCastleFipsProvider());

// シークレットを取得
SecretsManagerOptions options = new SecretsManagerOptions(storage);
KeeperSecrets secrets = SecretsManager.getSecrets(options);

// シークレットを取得するための1つまたは複数のUIDレコードを指定
List<String> uidFilter = List.of("[XXX]");

// フィルタを使用してシークレットを取得
KeeperSecrets secrets = SecretsManager.getSecrets(options, uidFilter);

// シークレットからレコードを取得
List<KeeperRecord> records = secrets.getRecords();

タイトルでシークレットを取得

// 一致するレコードをすべて取得
getSecretsByTitle(recordTitle:String):List<KeeperRecord>

// 最初に一致したレコードだけを取得
getSecretByTitle(recordTitle:String):KeeperRecord

パラメータ	型	必須	説明
recordTitle	String	はい	検索するレコードタイトル

使用例

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

public class KSMSample {
    public static void main(String[] args){

        // セキュリティプロバイダがロードされていることを確認
        Security.addProvider(new BouncyCastleFipsProvider());
            
        // 事前に初期化されたストレージを取得
        KeyValueStorage storage = new LocalConfigStorage("ksm-config.json");
        try {
            SecretsManagerOptions options = new SecretsManagerOptions(storage);

            // 取得するレコードのタイトル
            String recordTitle = "My Credentials";
            
            // タイトルでレコードを検索
            KeeperRecord myCredentials = secrets.getRecords().getSecretByTitle(recordTitle);

            // レコードの詳細を出力
            System.out.println("Record UID: " + myCredentials.getRecordUid());
            System.out.println("Title: " + myCredentials.getData().getTitle());
        } catch (Exception e) {
            System.out.println(e.getMessage());
        }
    }
}

シークレットから値を取得

パスワードを取得

シークレットをKeeperシークレットマネージャーから取得すると、このショートカットでそのシークレットのパスワードを取得します。

パスワードを取得

secret.getPassword()

使用例

フィールドを取得

フィールドを取得

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

使用例

フィールド値を取得するには、戻り値を対応するフィールドタイプのクラスにキャストする必要があります。フィールドタイプの一覧については、レコードタイプページをご参照ください。

Keeper表記法

値を取得

Notation.getValue(secret, "<query>");
// クエリの例: <RECORD UID>/field/login

使用例

Keeper表記法の形式と機能については、Keeper表記法をご参照ください

パラメータ	型	必須	デフォルト	説明
secret	KeeperRecord	はい		フィールド値を取得するレコード
query	String	はい		目的のフィールドのドット記法によるクエリ

TOTPコードを取得

TOTPコードを取得

TotpCode.uriToTotpCode(url)

Example Usage

パラメータ	型	必須	デフォルト	説明
url	String	はい		TOTP Url

シークレットの値を更新

レコード更新コマンドが成功しても、ローカルのデータ (特にレコードのリビジョン情報) は更新されません。そのため、同じレコードを続けて更新しようとすると、リビジョンが一致しないため失敗します。これを防ぐには、レコードを更新した後に、必ずそのレコードを再読み込みしてください。

シークレットを更新

シークレットを更新

updateSecret(options:SecretsManagerOptions, recordToUpdate:KeeperRecord);

使用例

トランザクション更新

UpdateSecretを使用して、シークレットに加えた変更を保存します。 UpdateSecretが正常に実行されると、変更がKeeperボルトに反映されます。

パラメータ	型	必須	デフォルト	説明
options	SecretsManagerOptions	はい		ストレージとクエリの設定
recordToUpdate	KeeperRecord	はい		更新するレコード

パスワードを更新

パスワードを更新

recordToUpdate.updatePassword(password:String);

SecretsManager.updateSecret(options, recordToUpdate);

使用例

パラメータ	型	必須	デフォルト	説明
password	String	はい		設定する新しいパスワード

他のフィールドを更新

値を設定

// 形式
RecordField.getValue().set(index, value)
// 例 - ログインフィールド
recordLogin.getValue().set(0, "New Login");

使用例

レコードの各フィールドタイプは、クラスに相当します。 フィールドの値に正しくアクセスするために、フィールドを対応するクラスにキャストします。 フィールドタイプについては、レコードタイプのページご確認ください。

フィールドには複数の値を設定でき、リストでアクセスします。 この例では、1つの値のみを指定するログインフィールドを更新するため、値リスト内の1つの値を更新します。

ランダムなパスワードを生成

パスワード生成

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

使用例

パラメータ	型	必須	デフォルト
length	int	オプション	64
lowercase	int	オプション	0
uppercase	int	オプション	0
digits	int	オプション	0
specialCharacters	int	オプション	0

各パラメータは、使用する文字の種類の最小数を示します。たとえば、「uppercase」は、使用する大文字の最小数を示します。

ファイルのダウンロード

ファイルのダウンロード

SecretsManager.downloadFile(file):ByteArray

使用例

パラメータ	型	必須	デフォルト	説明
file	KeeperFile	はい		ダウンロードするファイル

レスポンス

型: ByteArray

ダウンロード用のファイルのバイト配列

サムネイルのダウンロード

サムネイルのダウンロード

SecretsManager.downloadThumbnail(file):ByteArray

使用例

パラメータ	型	必須	デフォルト	説明
file	KeeperFile	はい		ダウンロードするサムネイル付きファイル

レスポンス

型: ByteArray

ダウンロード用サムネイルのバイト配列

ファイルのアップロード

ファイルのアップロード

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

パラメータ	型	必須	説明
options	SecretsManagerOptions	はい	ストレージとクエリの設定
ownerRecord	KeeperRecord	はい	アップロードされたファイルを添付するレコード
file	KeeperFileUpload	はい	アップロードするファイル

Keeperファイルアップロードオブジェクトを作成

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

パラメータ	型	必須	説明
name	string	はい	アップロード後にKeeperに格納されるファイルの名前
title	string	はい	アップロード後にKeeperに格納されるファイルのタイトル
type	string	オプション	ファイルのデータのMIMEタイプ。何も指定しない場合は、「application/octet-stream」が使用されます
data	ByteArray	はい	バイト型のファイルデータ

使用例

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){
        
        // セキュリティプロバイダがロードされていることを確認
        Security.addProvider(new BouncyCastleFipsProvider());
                
        // 事前に初期化されたストレージを取得
        KeyValueStorage storage = new LocalConfigStorage("ksm-config.json");
        try {
            SecretsManagerOptions options = new SecretsManagerOptions(storage);

            // 必要なレコードのUIDを含むフィルタを作成
            List<String> uidFilter = List.of("XXX");

            // フィルタを使用してシークレットを取得
            KeeperSecrets secrets = SecretsManager.getSecrets(options, uidFilter);

            // ファイルのアップロード先のシークレットを取得
            KeeperRecord ownerRecord = secrets.getRecords().get(0);
        
            // アップロードするファイルからバイトを取得
            File file = new File("./myFile.json");
            FileInputStream fl = new FileInputStream(file);
            byte[] fileBytes = new byte[(int)file.length()];
            fl.read(fileBytes);
            fl.close();
            
            // アップロードするKeeperファイルを作成
            KeeperFileUpload myFile = new KeeperFileUpload(
                "myFile.json",
                "My File",
                "application/json",
                fileBytes
            )

            // 選択したレコードにファイルをアップロード
            SecretsManager.uploadFile(options, ownerRecord, myFile);
            
        } catch (Exception e) {
            System.out.println("KSM ran into an problem: " + e.getMessage());
        }
    }
}

レコードからファイルを削除する

必要なSDKバージョン: 17.1.1以上

UpdateOptions クラスの linksToRemove パラメータを使用して、レコードからファイル添付を削除できます。

要件

• ファイルを含むレコードのUID、または KeeperRecord オブジェクト

• 削除するファイルのファイルUID

• 削除対象のファイルがレコード上に存在していること

ファイルを削除

パラメータ	型	必須	デフォルト	説明
options	SecretsManagerOptions	はい		事前設定されたオプション
record	KeeperRecord	はい		更新対象のレコード
updateOptions	UpdateOptions	はい		削除するファイルを含むオプション

UpdateOptions

例 (Java)

例 (Kotlin)

完全な使用例

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

// ファイル付きのレコードを取得
QueryOptions queryOptions = new QueryOptions(
    Arrays.asList(recordUid),
    Collections.emptyList(),
    true  // ファイルをリクエスト
);

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

// 特定のファイルを削除
List<String> fileUidsToRemove = Arrays.asList("fileUid1", "fileUid2");

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

SecretsManager.updateSecretWithOptions(options, record, updateOptions);

シークレットの作成

要件

• 共有フォルダのUID

  • 共有フォルダには、シークレットマネージャーアプリケーションからアクセスできる必要があります。

  • ユーザーとシークレットマネージャーアプリケーションには編集権限が必要です。

  • 共有フォルダには、少なくとも1つのレコードが存在する必要があります。

• 作成されたレコードとレコードのフィールドは正しく形式である必要があります。

  • レコードタイプごとの適切なフィールド形式については、こちらのページをご参照ください。

• TOTPフィールドには、KSM SDK以外で生成されたURLのみを指定できます。

• レコード作成後、uploadFileファイルをで添付ファイルをアップロードできます。

レコードを作成

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

パラメータ	型	必須	デフォルト
options	SecretsManagerOptions	はい
folderUid	String	はい
newRecordData	KeeperRecordData	はい
secrets	KeeperSecrets	オプション	Keeperサーバーから新たに取得したすべてのシークレットのリスト

サブフォルダにレコードを作成

ログインレコードの例

カスタムタイプの例

シークレットの削除

Java/Kotlin KSM SDKでKeeperボルトのレコードを削除できます。

シークレットの削除

deleteSecret(smOptions, recordUids);

パラメータ	型	必須
smOptions	SecretsManagerOptions	はい
recordUids	List<Sting>	はい

使用例

キャッシュ

ネットワークアクセスが失われたときにシークレットにアクセスできない状況を避けるため、Java SDKを使用してシークレットを暗号化されたファイルを使用してローカルマシンにキャッシュできます。

キャッシュの設定と構成

Java SDKでキャッシュを設定するには、SecretsManagerOptions オブジェクトをインスタンス化するときに、2番目の引数としてキャッシュポスト関数を指定します。

Java SDKには、クエリをキャッシュしてファイルに保存するデフォルトのキャッシュ関数cachingPostFunction が含まれています。

// キャッシュオプションを作成
SecretsManagerOptions options = new SecretsManagerOptions(storage, SecretsManager::cachingPostFunction);

// 例すべてのシークレットを取得
SecretsManager.getSecrets(options)

フォルダ

フォルダは完全なCRUD (作成、読み取り、更新、削除操作) をサポートしています。

フォルダの読み取り

フォルダの完全な階層構造をダウンロードします。

getFolders(options:SecretsManagerOptions):List<KeeperFolder>

レスポンス

型: List<KeeperFolder>

使用例

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

フォルダの作成

CreateOptions とフォルダ名の指定が必要です。CreateOptions はフォルダのUIDパラメータ (共有フォルダのUID) が必須ですが、サブフォルダのUIDはオプションであり、指定されていない場合は、通常の新しいフォルダが親 (共有フォルダ) の直下に作成されます。サブフォルダは、親の共有フォルダの直接の下位オブジェクトである必要はありません。親フォルダから何階層も深い位置にサブフォルダを作成することができます。

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

パラメータ	型	必須	デフォルト	説明
options	SecretsManagerOptions	はい		事前に設定されたオプション
createOptions	CreateOptions	はい		親およびサブフォルダのUID
folderName	String	はい		フォルダ名
folders	List<KeeperFolder>	いいえ	List<KeeperFolder>	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
)

使用例

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

フォルダの更新

フォルダのメタデータ (現在はフォルダ名のみ) を更新します。

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

パラメータ	型	必須	デフォルト	説明
options	SecretsManagerOptions	はい		事前に設定されたオプション
folderUid	String	はい		フォルダのUID
folderName	String	はい		新しいフォルダ名
folders	List<KeeperFolder>	いいえ	List<KeeperFolder>	親フォルダの検索に使用するフォルダのリスト

使用例

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

フォルダの削除

フォルダのリストを削除します。空でないフォルダを削除するには、forceDeletionフラグを使用します。

forceDeletionを使用する場合は、親フォルダと子フォルダのUIDを一緒に送信しないようにしてください。削除する順序によっては、エラーが発生する可能性があります。たとえば、親が子を先に強制削除した場合などです。リストが必ずしもFIFO順で処理される保証はありません。

ボルトに存在しないフォルダのUIDやKSMアプリケーションで共有されていないフォルダのUIDはエラーになりません。

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

パラメータ	型	必須	デフォルト	説明
options	SecretsManagerOptions	はい		事前に設定されたオプション
folderUids	List<String>	はい		フォルダUIDリスト
forceDeletion	Boolean	いいえ	false	空でないフォルダを強制的に削除

使用例

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レコードタイプ - リンク済み認証情報へのアクセス

必要なSDKバージョン: 17.1.1 以上

PAMリソースレコードタイプ (PAMマシン、PAMディレクトリ、PAMデータベース) では、以下の認証情報をリンクできます。

• 管理者認証情報 リソース上で管理操作を実行するために使用される認証情報

• 接続用認証情報 リソースへのセッションを起動する際の認証に使用される認証情報

要件

• getSecrets() ではなく、getSecrets2() メソッドを使用すること

• QueryOptions で requestLinks = true を設定し、GraphSync™を有効化すること

• requestLinks = false の場合、links は null になります

• requestLinks = true でもリンクが存在しない場合、links は空のリストになります

パラメータ	型	必須	デフォルト	説明
options	SecretsManagerOptions	はい	なし	事前に構成されたオプション
queryOptions	QueryOptions	はい	なし	requestLinks=true を設定する必要があります

QueryOptionsのパラメータ

パラメータ	型	必須	デフォルト	説明
recordsFilter	List	はい	空	レコードUIDでフィルタリング
foldersFilter	List	いいえ	空	フォルダUIDでフィルタリング
requestLinks	boolean	はい	false	GraphSync™を有効にするにはtrueに設定する必要があります

リンク方式

メソッド	戻り値	説明
getRecordUid()	String	対象レコードのUID
isAdminUser()	boolean	管理者権限を持つ場合にtrue
allowsRotation()	boolean	ローテーションが許可されている場合にtrue
allowsConnections()	boolean	接続が許可されている場合にtrue

基本的な使い方 - リンク付きレコードの取得

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

// GraphSync™ を有効化
QueryOptions queryOptions = new QueryOptions(
    Collections.emptyList(),  // recordsFilter
    Collections.emptyList(),  // foldersFilter
    true                      // requestLinks - 必須
);

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

// リンクへアクセス
for (KeeperRecord record : secrets.getRecords()) {
    List<KeeperRecordLink> links = record.getLinks();
    if (links != null && !links.isEmpty()) {
        for (KeeperRecordLink link : links) {
            System.out.println("リンク先: " + link.getRecordUid());
        }
    }
}

リンクプロパティの確認

for (KeeperRecordLink link : record.getLinks()) {
    // ユーザー権限を確認
    if (link.isAdminUser()) {
        System.out.println("管理者ユーザー");
    }
    
    // パーミッションを確認
    if (link.allowsRotation()) {
        System.out.println("パスワードのローテーションが許可されています");
    }
}

一般的な例 - PAMユーザーの検索

// PAMマシンに関連付けられているユーザーを検索
for (KeeperRecord machine : secrets.getRecords()) {
    if ("pamMachine".equals(machine.getType())) {
        System.out.println("PAMマシン: " + machine.getTitle());
        
        List<KeeperRecordLink> links = machine.getLinks();
        if (links != null) {
            for (KeeperRecordLink link : links) {
                // ユーザーが管理者かどうか確認
                if (link.isAdminUser()) {
                    System.out.println("  管理者ユーザー: " + link.getRecordUid());
                }
            }
        }
    }
}

追加情報

PAMレコードタイプで取得可能なフィールドの詳細については、レコードフィールドクラスのページをご参照ください。

高度なPAM活用事例におけるリンク済み認証情報の扱いについては、PAMレコードのリンク済み認証情報のページをご覧ください。