.NET SDK

Keeperシークレットマネージャー用.Net SDKの詳細なドキュメント

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

要件

dotnet add package Keeper.SecretsManager

詳しくはこちらのウェブサイトをご覧ください。

ソースコード

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

SDKの使用

ストレージの初期化

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

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

SecretsManagerClient.InitializeStorage(storage: IKeyValueStorage, oneTimeToken: string, hostName: string = null)

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

パラメータ	型	必須	デフォルト	説明
storage	IKeyValueStorage	はい		構成を永続化するストレージ実装
oneTimeToken	string	はい		構成の初期化に使用するワンタイムアクセストークン
hostName	string	任意	null	Keeperサーバーのホスト名（省略時はトークンから自動検出）

使用例

var storage = new LocalConfigStorage("ksm-config.json");
SecretsManagerClient.InitializeStorage(storage, "[One Time Access Token]");
// トークンのみを使用して (後で使用するために) 設定を生成するには
// トークンをバインドするアクセス操作が少なくとも1回必要です
var options = new SecretsManagerOptions(storage);
await SecretsManagerClient.GetSecrets(options);

自動ファイルセキュリティ (v17.1.0以降)

.NET SDKでは、設定ファイルおよびキャッシュファイルのセキュリティが自動的に保護されます。

• Unix/macOS: chmod 600 (所有者のみ読み取り/書き込み可能) が設定されます。

• Windows: ACLが現在のユーザーのみに制限されます。

保護対象のファイル

• ksm-config.json (またはカスタム構成ファイル名)

• cache.dat (キャッシュを使用する場合)

追加の設定は不要です。SDKによって自動的に処理されます。

シークレットマネージャーのオプション

SecretsManagerOptions(
        IKeyValueStorage storage, 
        QueryFunction queryFunction = null, 
        bool allowUnverifiedCertificate = false, 
        string proxyUrl = null
)

パラメータ	型	必須	デフォルト
storage	IKeyValueStorage	はい
queryFunction	QueryFunction	任意	null
allowUnverifiedCertificate	bool	任意	false
proxyUrl	string	任意	null

シークレットの取得

GetSecrets(options: SecretsManagerOptions, recordsFilter: string[] = null): Task<KeeperSecrets>

パラメータ	型	必須	デフォルト	説明
options	SecretsManagerOptions	はい		ストレージとクエリの設定
recordsFilter	string[]	任意	null	レコードの検索フィルタ

レスポンス

型: KeeperSecrets

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

使用例

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

var options = new SecretsManagerOptions(storage, testPostFunction);
var secrets = await SecretsManagerClient.GetSecrets(options);

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

// 一致するレコードをすべて取得
async Task<IEnumerable<KeeperRecord>> GetSecretsByTitle(SecretsManagerOptions options, string recordTitle)

// 最初に一致したレコードだけを取得
async Task<KeeperRecord> GetSecretByTitle(SecretsManagerOptions options, string recordTitle)

パラメータ	型	必須	説明
options	SecretsManagerOptions	はい	事前に設定されたオプション
recordTitle	string	はい	検索するレコードタイトル

使用例

using System;
using System.Threading.Tasks;
using SecretsManager;

private static async Task getOneIndividualSecret()
{
    var storage = new LocalConfigStorage("ksm-config.json");
    var options = new SecretsManagerOptions(storage);
    var records = await SecretsManagerClient.GetSecretsByTitle(
            options, "My Credentials");
    foreach (var record in records)
    {
        Console.WriteLine(record.RecordUid + " - " + record.Data.title);
        foreach (var field in record.Data.fields)
        {
            Console.WriteLine("\t" + field.label + " (" + field.type + "): [" + String.Join(", ", field.value) + "]");
        }
    }
}

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

パスワードを取得

パスワードを取得

secret.FieldValue("password")

パスワード取得の例e

フィールドタイプはKeeperレコードタイプに基づきます。利用可能なフィールドの詳細な一覧については、コマンダーで record-type-info コマンドをご参照ください。

Keeper表記法を使用して他のフィールドを取得

値を取得

GetValue(KeeperSecrets secrets, string notation)

使用例

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

パラメータ	型	必須	デフォルト	説明
secrets	KeeperSecrets	はい		照会するシークレット
notation	string	はい		ドット記法形式のフィールドクエリ

TOTPコードを取得

TOTPコードを取得

CryptoUtils.GetTotpCode(string url)

使用例

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

シークレットの値を更新

レコード更新コマンドは成功してもローカルのレコードデータが更新されません（特に更新後のレコードリビジョン）。そのため、すでに更新されたレコードに連続して更新を行うと、リビジョンの不一致によって失敗します。各更新バッチの後には、必ず更新されたすべてのレコードを再読み込みしてください。

変更をシークレットに保存

シークレットを更新

UpdateSecret(options: SecretsManagerOptions, record: KeeperRecord, transactionType: UpdateTransactionType? = null);

使用例

トランザクション更新

パラメータ	型	必須	デフォルト	説明
options	SecretsManagerOptions	はい		ストレージとクエリの設定

パラメータ	型	必須	デフォルト	説明
options	SecretsManagerOptions	はい		ストレージとクエリの設定
record	KeeperRecord	はい		更新されたフィールド値を含むレコード
transactionType	UpdateTransactionType?	任意	null	トランザクション（2フェーズ）更新には Rotation を指定

UpdateSecret を使用して、シークレットレコードに加えた変更を保存してください。UpdateSecret を実行するまで、変更はKeeperボルトに反映されません。

フィールド値を更新

フィールド値を更新

UpdateFieldValue(string fieldType, object value)

使用例

パラメータ	型	必須	デフォルト	説明
fieldType	string	はい		更新するフィールド
value	object	はい		フィールドに設定する値

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

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

Generate Password

CryptoUtils.GeneratePassword(
    int minLength = 32, 
    int? lowercase = null, 
    int? uppercase = null, 
    int? digits = null, 
    int? specialCharacters = null, 
    string specialCharacterSet = AsciiSpecialCharacters
)

使用例

パラメータ	型	必須	デフォルト
minLength	int	任意	32
lowercase	int?	任意	null
uppercase	int?	任意	null
digits	int?	任意	null
specialCharacters	int?	任意	null
specialCharacterSet	string	任意	"!@#$%()+;<>=?[]{}^.,

各パラメータは、その文字種をパスワードに含める最小個数を表します。null の場合、ジェネレーターはすべての文字カテゴリにわたってバランスの取れた配分を使用します。specialCharacterSet パラメータは、候補となる特殊文字の集合を制御します。

ファイルのダウンロード

DownloadFile(file: KeeperFile): ByteArray

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

レスポンス

型: ByteArray

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

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

DownloadThumbnail(file: KeeperFile): ByteArray

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

レスポンス

型: ByteArray

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

ファイルのアップロード

ファイルのアップロード:

UploadFile(SecretsManagerOptions options, KeeperRecord ownerRecord, KeeperFileUpload file)

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

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

KeeperFileUpload(string name, string title, string type, byte[] data)

パラメータ	型	必須	説明
name	string	はい	アップロード後にKeeperに格納されるファイルの名前
title	string	はい	アップロード後にKeeperに格納されるファイルのタイトル
type	string	はい	ファイルのデータのMIMEタイプ（「application/octet-stream」など）
data	byte[]	はい	バイト型のファイルデータ

使用例

using System;
using System.Threading.Tasks;
using SecretsManager;

private static async Task uploadFile()
{
    // ストレージとオプションを初期化
    var storage = new LocalConfigStorage("ksm-config.json");
    var options = new SecretsManagerOptions(storage);
    
    // ファイルを添付するレコードを取得
    var records = (await SecretsManagerClient.GetSecrets(
            options, new[] { "XXX" })
        ).Records;
        
    var ownerRecord = records[0];
    
    // アップロードするファイルデータを取得
    var bytes = await File.ReadAllBytesAsync("my-file.json");
    var myFile = new KeeperFileUpload(
        "my-file1.json",
        "My File",
        null,
        bytes
    );
       
    // 選択したレコードにファイルをアップロード                     
    await SecretsManagerClient.UploadFile(options, ownerRecord, myFile);
    
}

シークレットの作成

要件

• 共有フォルダのUID

  • 共有フォルダへはシークレットマネージャーアプリケーションからアクセスできること

  • あなたとシークレットマネージャーアプリケーションに編集権限が付与されていること

  • 共有フォルダには、少なくとも1つのレコードが存在すること

• 作成されたレコードとレコードのフィールドは正しく書式設定されていること

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

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

• レコードを作成した後、UploadFileを使用してファイル添付をアップロードできます

レコード作成

SecretsManagerClient.CreateSecret(options, folderUid, record)

パラメータ	型	必須	デフォルト
options	SecretsManagerOptions	はい
folderUid	string	はい
record	KeeperRecordData	はい

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

ログイン情報レコードの例

カスタムタイプの例

シークレットの削除

.Net KSM SDKでKeeperボルトのレコードを削除できます。

シークレットの削除

DeleteSecret(smOptions, recordsUids);

パラメータ	型	必須
smOptions	SecretsManagerOptions	はい
recordsUids	string[]	はい

使用例

キャッシュ

ネットワークにアクセスできなくなった場合にシークレットへのアクセスを失わないよう、.Net SDKではシークレットをローカルマシン上の暗号化ファイルにキャッシュできます。

キャッシュの設定と構成

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

.Net SDKには標準のキャッシュ機能 cachingPostFunction が用意されており、キャッシュされたクエリをファイルに保存します。

var options = new SecretsManagerOptions(storage, SecretsManagerClient.CachingPostFunction);
var secrets = await SecretsManagerClient.GetSecrets(options);

フォルダ

フォルダは、作成・読み取り・更新・削除 (CRUD) のすべての操作に対応しています。

フォルダの読み取り

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

Task<KeeperFolder[]> GetFolders(SecretsManagerOptions options)

レスポンス

型: KeeperFolder[]

使用例

using SecretsManager;

var options = new SecretsManagerOptions(new LocalConfigStorage("ksm-config.json"));
var folders = await SecretsManagerClient.GetFolders(options);

フォルダの作成

CreateOptions とフォルダ名の指定が必要です。CreateOptions 内のフォルダUIDパラメータは必須で、共有フォルダのUIDを指定します。サブフォルダのUIDは任意であり、省略された場合は親 (共有フォルダ) 直下に通常のフォルダが新規作成されます。サブフォルダは必ずしも親共有フォルダの直接の子である必要はなく、階層を深く設定することも可能です。

Task<string> CreateFolder(SecretsManagerOptions options, CreateOptions createOptions, string folderName, KeeperFolder[] folders = null)

パラメータ	型	必須	デフォルト	説明
options	SecretsManagerOptions	はい		事前に設定されたオプション
createOptions	CreateOptions	はい		親およびサブフォルダのUID
folderName	string	はい		フォルダ名
folders	KeeperFolder[]	いいえ	null	CreateOptionsで作成した親とサブフォルダの検索に使用するフォルダのリスト

public class CreateOptions {
    public string FolderUid { get; }
    public string SubFolderUid { get; }
}

public class KeeperFolder {
        public byte[] FolderKey { get; }
        public string FolderUid { get; }
        public string ParentUid { get; }
        public string Name { get; }
}

使用例

using SecretsManager;

var options = new SecretsManagerOptions(new LocalConfigStorage("ksm-config.json"));
var co = new CreateOptions("[PARENT_SHARED_FOLDER_UID]");
var folderUid = await SecretsManagerClient.CreateFolder(options, co, "new_folder");

フォルダの更新

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

Task UpdateFolder(SecretsManagerOptions options, string folderUid, string folderName, KeeperFolder[] folders = null)

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

使用例

using SecretsManager;

var options = new SecretsManagerOptions(new LocalConfigStorage("ksm-config.json"));
await SecretsManagerClient.UpdateFolder(options, "[FOLDER_UID]", "new_folder_name");

フォルダの削除

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

forceDeletion を使用する場合、親フォルダとその子フォルダのUIDを同時に送信しないでください。削除の順序によってはエラーになることがあります（例: 親が子より先に強制削除される場合など）。リストが常にFIFO順で処理される保証はありません。

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

Task DeleteFolder(SecretsManagerOptions options, string[] folderUids, bool forceDeletion = false)

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

使用例

using SecretsManager;

var options = new SecretsManagerOptions(new LocalConfigStorage("ksm-config.json"));
await SecretsManagerClient.DeleteFolder(options, new string[]{"[FOLDER_UID1]", "[FOLDER_UID2]"}, true);

プロキシのサポート

.NET SDKでは、環境変数を使用する方法と、SecretsManagerOptionsに直接プロキシURLを渡す方法の2通りでプロキシを設定できます。

Keeperでは、環境変数を使用したプロキシ設定を推奨しています。この方法により、設定情報をコード内に含めずに済み、ツールや環境間で一貫性を保ちながら、デプロイと保守を簡素化できます。

環境変数による使用例

HTTPS_PROXY=http://user:password@127.0.0.1:3128 dotnet run

SecretsManagerOptions にURLを渡す使用例

var options = new SecretsManagerOptions(storage, null, false, "http://user:password@127.0.0.1:3128");