Java/Kotlin SDK

Keeper Secrets Manager用JavaとKotlin SDKの詳細なドキュメント

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

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

pom.xml
<dependency>
  <groupId>com.keepersecurity.secrets-manager</groupId>
  <artifactId>core</artifactId>
  <version>[16.5.4,)</version>
</dependency>

ソースコード

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

SDKの使用

ストレージの初期化

トークンのみを使用して(後で使用するために)新しい設定を生成するには、トークンをバインドして、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;

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

// シークレットを取得
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;

// シークレットを取得
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){
        // 事前に初期化されたストレージを取得
        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 Secrets Managerから取得すると、このショートカットでそのシークレットのパスワードを取得します。

secret.getPassword()

フィールドを取得

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

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

Keeper表記法

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

Keeper表記法の形式と機能については、Keeper表記法のドキュメントをご参照ください

パラメータ必須デフォルト説明

secret

KeeperRecord

はい

フィールド値を取得する記録

query

String

はい

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

TOTPコードを取得

TotpCode.uriToTotpCode(url)
パラメータ必須デフォルト説明

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){
        // 事前に初期化されたストレージを取得
        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());
        }
    }
}

シークレットの作成

前提条件:

  • 共有フォルダのUID

    • 共有フォルダには、Secrets Managerアプリケーションからアクセスできる必要があります

    • あなたとSecrets Managerアプリケーションには編集権限が必要です

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

  • 作成された記録と記録のフィールドは正しく書式設定されている必要があります

    • 記録タイプごとの適切なフィールド形式については、このドキュメントをご参照ください

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

Secrets Manager SDKで作成したKeeperの記録は、現時点ではファイル添付をサポートしていません

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番目の引数としてPOSTキャッシュ関数を指定します。

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

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

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

フォルダ

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

追加のパラメータ(バッチ処理の高速化などに有効なKeeperFolderのリスト)を指定できるメソッドもあります。パラメータが見つからないか空の場合は、呼び出されるたびに完全なフォルダメタデータをそれぞれダウンロードします。

フォルダの読み取り

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

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

最終更新