.NET SDK

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

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

要件

dotnet add package Keeper.SecretsManager

ソースコード

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

SDKの使用

ストレージの初期化

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

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

SecretsManagerClient.InitializeStorage(storage:KeyValueStorage, clientKey:String? = null, hostName:String? = null)

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

使用例

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

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

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

パラメーター	型	必須	デフォルト値
storage	KeyValueStorage	必須	ー
queryFunction	String	任意	null
allowUnverifiedCertificate	Bool	任意	false
proxyUrl	String	任意	null

シークレットの取得

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

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

レスポンス

型: KeeperSecrets

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

使用例

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

var options = new SecretsManagerOptions(storage, testPostFunction);
var secrets = 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")
        ).Records;
    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);

使用例

トランザクション更新

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

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

フィールド値を更新

フィールド値を更新

UpdateFieldValue(string fieldType, object value)

使用例

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

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

Generate Password

CryptoUtils.GeneratePassword(int length, lowercase int, uppercase int, digits int, specialCharacters);

使用例

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

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

ファイルのダウンロード

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, firstRecord, 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("[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:[email protected]:3128 dotnet run

SecretsManagerOptionsにURLを渡す例

var options = new SecretsManagerOptions(storage, null, false, "http://user:[email protected]:3128");