Java/Kotlin SDK

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

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

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

build.gradle

repositories {
    mavenCentral()
}

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

pom.xml

<dependency>
    <groupId>com.keepersecurity.secrets-manager</groupId>
    <artifactId>core</artifactId>
    <version>[17.2.0,)</version>
</dependency>
<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bc-fips</artifactId>
    <version>2.1.1</version>
</dependency>

詳細についてはhttps://central.sonatype.com/artifact/com.keepersecurity.secrets-manager/coreをご参照ください。

暗号プロバイダーに関する注意事項

KeeperシークレットマネージャーSDKでは、BouncyCastleは必須ではありません。以下の暗号プロバイダーを利用できます。

BouncyCastle FIPS ( bc-fips:2.1.1、上記のインストール手順で使用しているバージョン )
Javaの標準暗号プロバイダー
JCE互換の暗号プロバイダー

本ドキュメント内のサンプルでは、説明を目的としてBouncyCastle FIPSを使用しています。

暗号化プロバイダ

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

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

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

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

ソースコード

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

SDKの使用

ストレージの初期化

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

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

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

パラメータ

型

必須

デフォルト

説明

storage

KeyValueStorage

はい

ストレージの実装

oneTimeToken

String

はい

ワンタイムアクセストークン

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

Security.addProvider(new BouncyCastleFipsProvider());

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

バインディングライフサイクル

ワンタイムトークンは、クライアント作成時ではなく、最初の getSecrets() 呼び出し時に引き換えられます。構成を外部ストア (AWS Secrets Manager、Azure Key Vaultなど) に保存する場合は、バインド後に読み出してから永続化します。詳しくは、バインディングライフサイクルをご参照ください。

import com.keepersecurity.secretsManager.core.*

// 初回実行: ストレージファイルにワンタイムトークンが含まれています。
val storage = LocalConfigStorage("ksm-config.json")
val options = SecretsManagerOptions(storage)
val secrets = SecretsManager.getSecrets(options)
// ここでトークンが引き換えられ、ksm-config.json がバインド済み認証情報で更新されます。

// 以降の実行: 変更は不要です。ストレージにバインド済み認証情報が保存されています。
val secrets2 = SecretsManager.getSecrets(options)

シークレットの取得

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

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

            // 取得対象レコードのタイトル
            String recordTitle = "My Credentials";

            // タイトルを指定してレコードを検索
            KeeperRecord myCredentials = secrets.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()

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

// 最初のレコードを取得
KeeperRecord firstRecord = secrets.getRecords().get(0);

// 最初のレコードからパスワードを取得
String password = firstRecord.getPassword();
System.out.println("Password: " + password);

フィールドを取得

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

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();
KeeperRecord firstRecord = secrets.getRecords().get(0);

// 最初のレコードからパスワードを取得
KeeperRecordField pwd = firstRecord.getData().getField(Password.class)

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

Keeper表記法

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

import static com.keepersecurity.secretsManager.core.SecretsManager.*
import static com.keepersecurity.secretsManager.core.Notation.*;
import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

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

// シークレットを取得
KeeperSecrets secrets = getSecrets(options);

// ドット記法でログインを取得
String login = getValue(secrets, "BediNKCMG21ztm5xGYgNww/field/login");

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

パラメータ

型

必須

説明

secrets

KeeperSecrets

はい

表記法の解決対象となるシークレットのコレクション

query

String

はい

目的フィールドのドット記法クエリ

TOTPコードを取得

TotpCode.uriToTotpCode(url)

import static com.keepersecurity.secretsManager.core.Notation.*;
import static com.keepersecurity.secretsManager.core.TotpCode.*;
import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

...

// シークレットを取得
KeeperSecrets secrets = getSecrets(options);

// レコードからTOTP urlを取得
String url= getValue(secrets, "BediNKCMG21ztm5xGYgNww/field/oneTimeCode");

// TOTPコードを取得
TotpCode totp = uriToTotpCode(url);

パラメータ

型

必須

説明

url

String

はい

TOTP Url

PAMレコードタイプ

PAMレコードは record.getType() で識別できます。

for (record in secrets.records) {
    when (record.getType()) {
        "pamMachine"  -> { /* host フィールドが利用可能 */ }
        "pamUser"     -> { /* login フィールドが利用可能 */ }
        "pamDatabase" -> { /* databaseType フィールドが利用可能 */ }
    }
}

全11種類のPAMレコードタイプのフィールド定義は、PAMレコードタイプをご参照ください。

リンク済み認証情報

PAMリソースレコードとリンク済み認証情報を含めて取得するには、QueryOptions で requestLinks = true を指定します。各リンクは KeeperRecordLink として返り、対象レコードのUIDや権限・許可操作 (isAdminUser()、isLaunchCredential()、allowsRotation()、allowsConnections() など) を型付きアクセサで参照できます。詳しくはPAMレコードのリンク済み認証情報をご参照ください。

val queryOptions = QueryOptions(requestLinks = true)
val secrets = SecretsManager.getSecrets2(options, queryOptions)

for (record in secrets.records) {
    // requestLinks 未設定の場合は links が null、設定済みでリンクがない場合は空
    record.links?.forEach { link ->
        println("link -> ${link.recordUid} (admin=${link.isAdminUser()}, launch=${link.isLaunchCredential()})")
    }
}

QueryOptionsのパラメータ

パラメータ

型

必須

デフォルト

説明

recordsFilter

List<String>

いいえ

空

レコードUIDでフィルタリング

foldersFilter

List<String>

いいえ

空

フォルダUIDでフィルタリング

requestLinks

Boolean?

いいえ

null

リンク取得時は true。null / false の場合はリンクなし

リンク済み認証情報の取得手順の概要は、リンク済み認証情報をご参照ください。

シークレットの値を更新

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

シークレットを更新

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.*;

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

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

// 最初のレコードを更新
KeeperRecord recordToUpdate = secrets.getRecords().get(0);

// パスワードを更新
recordToUpdate.updatePassword("aP1$t367QOCvL$eM$bG#");

// タイトルとメモを更新
recordToUpdate.data.title = "New Title"
recordToUpdate.data.notes = "My Notes"

// 変更を保存
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.*;

...

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

// 最初のレコードを更新
KeeperRecord record = secrets.getRecords().get(0);

// レコードのパスワードをローテーション
record.updatePassword("aP1$t367QOCvL$eM$bG#");

// トランザクションを開始
updateSecret(options, record, transactionType = UpdateTransactionType.GENERAL);

// リモートホストでパスワードをローテーション
boolean success = rotateRemoteSshPassword("aP1$t367QOCvL$eM$bG#");

// トランザクション完了 (コミットかロールバック)
completeTransaction(options, record.recordUid, rollback = !success);

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

KeeperRecord.isEditable は、シークレットマネージャーアプリケーションの共有に設定されている書き込み権限を反映します。書き込みを行う前に読み取り専用レコードを検出したい場合は、updateSecret を呼び出す前にこの値を確認してください。SDKはこのフィールドを強制しないため、読み取り専用レコードへの書き込みはサーバー側で失敗します。

パラメータ

型

必須

説明

options

SecretsManagerOptions

はい

ストレージとクエリの設定

recordToUpdate

KeeperRecord

はい

更新するレコード

transactionType

UpdateTransactionType

いいえ

2段階更新を開始する場合に設定し、completeTransactionで完了させます

パスワードを更新

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;

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

// 最初のレコードを更新
KeeperRecord recordToUpdate = secrets.getRecords().get(0);

// パスワードを更新
recordToUpdate.updatePassword("aP1$t367QOCvL$eM$bG#");

// 変更を保存
SecretsManager.updateSecret(options, recordToUpdate);

パラメータ

型

必須

説明

password

String

はい

設定する新しいパスワード

他のフィールドを更新

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

// 編集するフィールドを取得
Login recordLogin = (Login) recordToUpdate.getData().getField(Login.class);

// フィールド値を更新
recordLogin.getValue().set(0, "New Login");

// 変更を保存
SecretsManager.updateSecret(options, recordToUpdate);

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

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

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

generatePassword(
    minLength: Int = 32,
    lowercase: Int? = null,
    uppercase: Int? = null,
    digits: Int? = null,
    specialCharacters: Int? = null,
    specialCharacterSet: String = "\"!@#$%()+;<>=?[]{}^.,"
)

import com.keepersecurity.secretsManager.core.CryptoUtils;

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

// 編集するフィールドを取得
Password recordPassword = (Password) recordToUpdate.getData().getField(Password.class);

// ランダムなパスワードを生成
String password = CryptoUtils.generatePassword();

// フィールド値を更新
recordPassword.getValue().set(0, password);

// 変更を保存
SecretsManager.updateSecret(options, recordToUpdate);

パラメータ

型

必須

デフォルト

説明

minLength

Int

オプション

生成するパスワードの最小長

lowercase

Int

オプション

null

小文字の最小数 (0以下の場合は正確な個数として扱う)

uppercase

Int

オプション

null

大文字の最小数 (0以下の場合は正確な個数として扱う)

digits

Int

オプション

null

数字の最小数 (0以下の場合は正確な個数として扱う)

specialCharacters

Int

オプション

null

特殊文字の最小数 (0以下の場合は正確な個数として扱う)

specialCharacterSet

String

オプション

"!@#$%()+;<>=?[]{}^.,

特殊文字の取得に使うカスタム文字セット

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

ファイルのダウンロード

SecretsManager.downloadFile(file): ByteArray

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

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

// 最初のレコードから最初のファイルをダウンロード
KeeperRecord firstRecord = secrets.getRecords().get(0);
KeeperFile file = firstRecord.getFileByName("acme.cer");
byte[] fileBytes = SecretsManager.downloadFile(file);

// ファイルをディスクに書き込む
try (FileOutputStream fos = new FileOutputStream(file.getData().getName())) {
    fos.write(fileBytes);
} catch (IOException ioException){
    ioException.printStackTrace();
}

パラメータ

型

必須

説明

file

KeeperFile

はい

ダウンロードするファイル

レスポンス

型: ByteArray

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

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

SecretsManager.downloadThumbnail(file): ByteArray

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

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

// 最初のレコードから最初のファイルをダウンロード
KeeperRecord firstRecord = secrets.getRecords().get(0);
KeeperFile file = firstRecord.getFileByName("acme.cer");
byte[] fileBytes = SecretsManager.downloadThumbnail(file);

// ファイルをディスクに書き込む
try (FileOutputStream fos = new FileOutputStream(file.getData().getName())) {
    fos.write(fileBytes);
} catch (IOException ioException){
    ioException.printStackTrace();
}

パラメータ

型

必須

説明

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

はい

削除するファイルを含むオプション

パラメータ

型

必須

デフォルト

説明

transactionType

UpdateTransactionType

いいえ

null

バッチ処理のトランザクションタイプ

linksToRemove

List<String>

はい

削除するファイルUIDのリスト

// "temp_"で始まるファイルを削除
List<String> filesToRemove = new ArrayList<>();
for (KeeperFile file : record.getFiles()) {
    if (file.getData().getTitle().startsWith("temp_")) {
        filesToRemove.add(file.getFileUid());
    }
}

if (!filesToRemove.isEmpty()) {
    UpdateOptions updateOptions = new UpdateOptions(null, filesToRemove);
    SecretsManager.updateSecretWithOptions(options, record, updateOptions);
}

// "temp_"で始まるファイルを削除
val filesToRemove = record.files
    ?.filter { it.data?.title?.startsWith("temp_") == true }
    ?.map { it.fileUid }
    ?: emptyList()

if (filesToRemove.isNotEmpty()) {
    updateSecretWithOptions(
        options,
        record,
        UpdateOptions(linksToRemove = filesToRemove)
    )
}

完全な使用例

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サーバーから新たに取得したすべてのシークレットのリスト

SecretsManager.createSecret2(options, createOptions, newRecordData, folders);

パラメータ

型

必須

デフォルト

options

SecretsManagerOptions

はい

createOptions

CreateOptions

はい

newRecordData

KeeperRecordData

はい

folders

KeeperFolder[]

オプション

Keeperサーバーから新たに取得したすべてのフォルダのリスト

この例では、ログイン値と生成されたパスワードを含むログインタイプのレコードを作成します。

例にある「[FOLDER UID]」をシークレットマネージャーアプリケーションがアクセスできる共有フォルダのUIDに置き換えます。

import com.keepersecurity.secretsManager.core.*;

KeeperRecordData newRecordData = new KeeperRecordData(
        "Sample KSM Record: Java",
        "login",
        Arrays.asList(
                new Login("My Username"),
                new Password(CryptoUtils.generatePassword())
        ),
        null,
        "This is a \nmultiline\n\n\tnote"
);

String recordUid = SecretsManager.createSecret(options, folderUid, newRecordData);

この例では、ホスト、ユーザー名、パスワードを含むサーバーログインの serverCredentials レコードを作成します。

例にある <FOLDER UID> を、シークレットマネージャーアプリケーションがアクセスできる共有フォルダのUIDに置き換えます。

import com.keepersecurity.secretsManager.core.*;

KeeperRecordData newRecordData = new KeeperRecordData(
        "prod-ssh-server",
        "serverCredentials",
        Arrays.asList(
                new Hosts(new Host("prod.example.com", "22")),
                new Login("admin"),
                new Password(CryptoUtils.generatePassword())
        )
);

String recordUid = SecretsManager.createSecret(options, "<FOLDER UID>", newRecordData);

databaseCredentialsの例

この例では、接続情報を含むデータベースログインの databaseCredentials レコードを作成します。

例にある <FOLDER UID> を、シークレットマネージャーアプリケーションがアクセスできる共有フォルダのUIDに置き換えます。

import com.keepersecurity.secretsManager.core.*;

KeeperRecordData dbRecordData = new KeeperRecordData(
        "prod-mysql",
        "databaseCredentials",
        Arrays.asList(
                new Text("MySQL"),
                new Hosts(new Host("db.example.com", "3306")),
                new Login("db_admin"),
                new Password(CryptoUtils.generatePassword())
        )
);

String recordUid = SecretsManager.createSecret(options, "<FOLDER UID>", dbRecordData);

sshKeysの例

この例では、ホストとログインを含むSSH鍵ペアの sshKeys レコードを作成します。

例にある <FOLDER UID> を、シークレットマネージャーアプリケーションがアクセスできる共有フォルダのUIDに置き換えます。

import com.keepersecurity.secretsManager.core.*;

KeeperRecordData sshRecordData = new KeeperRecordData(
        "prod-ssh-key",
        "sshKeys",
        Arrays.asList(
                new Login("admin"),
                new KeyPairs(new KeyPair("<PUBLIC KEY>", "<PRIVATE KEY>")),
                new Hosts(new Host("prod.example.com", "22"))
        )
);

String recordUid = SecretsManager.createSecret(options, "<FOLDER UID>", sshRecordData);

シークレットの削除

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

deleteSecret(smOptions, recordUids);

パラメータ

型

必須

smOptions

SecretsManagerOptions

はい

recordUids

List<String>

はい

// シークレットマネージャーを設定
LocalConfigStorage storage = new LocalConfigStorage("ksm-config.json");
//initializeStorage(storage, "<One Time Access Token>")
SecretsManagerOptions smOptions = new SecretsManagerOptions(storage);

// UIDレコードで特定のシークレットを削除
SecretsManager.deleteSecret(smOptions, List.of("EG6KdJaaLG7esRZbMnfbFA"));

キャッシュ

ネットワークアクセスが失われたときにシークレットにアクセスできない状況を避けるため、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("[PARENT_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を指定しても、例外はスローされません。フォルダ単位の失敗を検出するには、返される SecretsManagerDeleteFolderResponse.folders の各要素の responseCode を確認してください。

SecretsManagerDeleteFolderResponse deleteFolder(SecretsManagerOptions options, List<String> folderUids, boolean forceDeletion)

レスポンス

型: SecretsManagerDeleteFolderResponse

public class SecretsManagerDeleteFolderResponse {
    public List<SecretsManagerDeleteFolderResponseRecord> folders;
}

public class SecretsManagerDeleteFolderResponseRecord {
    public String errorMessage;   // 成功時はnull、項目単位で失敗した場合に設定
    public String folderUid;
    public String responseCode;   // 成功時は"ok"
}

パラメータ

型

必須

デフォルト

説明

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

レコードフィールドクラス

各レコードフィールドタイプはクラスで表されます。フィールドの値にアクセスするには、対応するクラスにキャストします。フィールドタイプの一覧は、レコードタイプのドキュメントをご参照ください。

List<KeeperRecordField> fields = record.getData().getFields();
for (KeeperRecordField field : fields) {
    if (field instanceof Login) {
        Login loginField = (Login) field;
        String loginValue = loginField.getValue().get(0);
    } else if (field instanceof Password) {
        Password passwordField = (Password) field;
        String passwordValue = passwordField.getValue().get(0);
    }
}

プロキシサポート

SDKの通信をHTTPまたはHTTPSプロキシ経由にするには、SecretsManagerOptions に proxyUrl を設定します。

Java (静的ファクトリメソッド、推奨):

SecretsManagerOptions options = SecretsManagerOptions.withProxy(
    storage, "http://proxy.local:8080");

Kotlin (名前付き引数):

val options = SecretsManagerOptions(storage, proxyUrl = "http://proxy.local:8080")

認証が必要なプロキシでは、http://user:password@host:port の形式のURLを使用します。パスワードに含まれる予約文字は、たとえば p@ss を p%40ss にするなど、パーセントエンコードしてください。

認証が必要なプロキシとJVMフラグ

Javaでは、HTTPS CONNECTトンネル上でのBasic認証がデフォルトで無効になっています。プロキシの認証情報が設定されている場合、SDKはこの制限を自動的に解除しますが、これはSDKが最初に呼び出しを行う前に、他のHTTPまたはHTTPS通信が HttpURLConnection を読み込んでいない場合に限られます。アプリケーションサーバーやフレームワークは、通常SDKより先にこの読み込みを行うため、注意してください。

認証が必要なプロキシを使用する場合は、アプリケーションが他のHTTPまたはHTTPS通信を行う前に、以下のJVMフラグを設定してください。

-Djdk.http.auth.tunneling.disabledSchemes=

コマンドラインまたは JDK_JAVA_OPTIONS (Java 9以降) で指定します。このフラグが設定されていない場合、SDKは単純な407エラーではなく、この対処方法を示す SecretsManagerException をスローします。

アンビエントプロキシ設定

proxyUrl が設定されていない場合、SDKはまずJVMのシステムプロパティ (https.proxyHost/https.proxyPort) を読み取り、続いて HTTPS_PROXY/https_proxy 環境変数を読み取ります。NO_PROXY/no_proxy および http.nonProxyHosts による除外設定も適用されます。

17.4.0以降、SDKはこれまで無視していたアンビエントプロキシ設定を反映するようになりました。他のツール用に環境で HTTPS_PROXY や https.proxyHost を設定している場合は、アップグレード前にその値を確認してください。

接続タイムアウトと読み取りタイムアウト

SecretsManagerOptions には connectTimeoutMillis (デフォルト5,000ミリ秒) と readTimeoutMillis (デフォルト30,000ミリ秒) があります。応答がないサーバーに対しては、待ち続けるのではなく SocketTimeoutException が発生します。必要な値だけをKotlinの名前付き引数で設定できます。

val options = SecretsManagerOptions(
    storage,
    connectTimeoutMillis = 10_000,
    readTimeoutMillis = 60_000
)

前へPython SDK

次へレコードフィールドクラス

最終更新 1 か月前