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

シークレットの取得

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) + "]");
        }
    }
}

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

パスワードを取得

Get Password

secret.FieldValue("password")

Example Usage

var storage = new LocalConfigStorage(configName);
Console.WriteLine($"Local Config Storage opened from the file {configName}");
if (clientKey != null)
    SecretsManagerClient.InitializeStorage(storage, "<One Time Access Token>");
}
var options = new SecretsManagerOptions(storage);
// シークレットを取得
var secrets= (await SecretsManagerClient.GetSecrets(options)).Records;

// 最初のシークレットからパスワードを取得
var firstSecret= secrets[0];
var password = firstSecret.FieldValue("password").ToString();

フィールドはタイプで検索されます。フィールドタイプの一覧は、レコードタイプのドキュメントをご参照ください。

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

Get Value

GetValue(KeeperSecrets secrets, string notation)

Example Usage

var storage = new LocalConfigStorage(configName);
Console.WriteLine($"Local Config Storage opened from the file {configName}");
if (clientKey != null)
    SecretsManagerClient.InitializeStorage(storage, "<One Time Access Token>");
}
var options = new SecretsManagerOptions(storage);
// シークレットを取得
var secrets (await SecretsManagerClient.GetSecrets(options)).Records;

// ドット記法を使用してログインフィールドの値を取得
var password = Notation.GetValue(secrets, "BediNKCMG21ztm5xGYgNww/field/login");

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

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

TOTPコードを取得

Get TOTP Code

CryptoUtils.GetTotpCode(string url)

Example Usage

var storage = new LocalConfigStorage(configName);
Console.WriteLine($"Local Config Storage opened from the file {configName}");
if (clientKey != null)
    SecretsManagerClient.InitializeStorage(storage, "<One Time Access Token>");
}
var options = new SecretsManagerOptions(storage);
// シークレットを取得
var secrets (await SecretsManagerClient.GetSecrets(options)).Records;

// レコードからTOTP urlを取得
var url = Notation.GetValue(secrets, "BediNKCMG21ztm5xGYgNww/field/OneTimeCode");

// TOTPコードを取得
var totp = CryptoUtils.GetTotpCode(url);
Console.WriteLine(totp.Code);

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

シークレットの値を更新

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

Update Secret

UpdateSecret(options:SecretsManagerOptions, record:KeeperRecord);

Example Usage

var options = SecretsManagerOptions(storage, testPostFunction)
updateSecret(options, secret)

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

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

フィールド値を更新

Update Field Value

UpdateFieldValue(string fieldType, object value)

Example Usage

var storage = new LocalConfigStorage(configName);
Console.WriteLine($"Local Config Storage opened from the file {configName}");
if (clientKey != null)
    SecretsManagerClient.InitializeStorage(storage, "<One Time Access Token>");
}
var options = new SecretsManagerOptions(storage);
// シークレットを取得
var secrets= (await SecretsManagerClient.GetSecrets(options)).Records;

// 最初のシークレットからパスワードを取得
var firstSecret= secrets[0];

// ログインフィールドを更新
firstSecret.updateFieldValue("login", "My New Login");

// 変更を保存
updateSecret(options, firstSecret);

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

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

Generate Password

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

Example Usage

// ランダムなパスワードを生成
var password = CryptoUtils.GeneratePassword();
// 新しいパスワードでレコードを更新
firstRecord.UpdateFieldValue("password", password);
await SecretsManagerClient.UpdateSecret(options, firstRecord);

パラメータ	型	必須	デフォルト
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のみを指定できます

シークレットマネージャーSDKで作成したKeeperのレコードは、現時点ではファイル添付をサポートしていません

Create a Record

SecretsManagerClient.CreateSecret(options, folderUid, record)

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

Login Record Example

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

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

var newRecord = new KeeperRecordData{type = "login", title = "Sample KSM Record:C#"};

newRecord.fields = new[]
{
    new KeeperRecordField { type = "login", value = new[] { "My Username" } },
    new KeeperRecordField { type = "password", value = new[] { CryptoUtils.GeneratePassword() } },
};
newRecord.notes = "This is a C# record creation example";

var recordUid = await SecretsManagerClient.CreateSecret(options, folderUid, newRecord);

Custom Type Example

この例では、カスタムのレコードタイプのレコードを作成します。

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

var newRecord = new KeeperRecordData();
newRecord.type = "Custom Login";
newRecord.title = "Sample Custom Type KSM Record:C#";
newRecord.fields = new[]
{
    new KeeperRecordField { 
        type = "host",
        value = new[] 
        {
            new Dictionary<string, string>
            {
                { "hostName", "127.0.0.1"},
                { "port", "8080"}
            }
        },
        label = "My Custom Host lbl",
        required = true
    },
    
    new KeeperRecordField { 
        type = "login",
        value = new[] { "[e-mail]" },
        required = true,
        label = "My Custom Login lbl"
    },
    
    new KeeperRecordField
    {
        type = "password",
        value = new[] { CryptoUtils.GeneratePassword() },
        required = true,
        label = "My Custom Password lbl"
    },
    
    new KeeperRecordField
    {
        type = "url",
        value = new[] { "http://localhost:8080/login" },
        label = "My Login Page",
        required = true
    },
    
    new KeeperRecordField { 
        type = "securityQuestion",
        value = new[]
        {
            new Dictionary<string, string>
            {
                {"question", "What is one plus one (write just a number)"},
                { "answer", "2" }
            }
        },
        label = "My Question 1",
        required = true
    },
    
    new KeeperRecordField { 
        type = "phone",
        value = new[]
        {
            new Dictionary<string,string>
            {
                { "region", "US" },
                { "number", "510-444-3333" },
                { "ext", "2345" },
                { "type", "Mobile" }
            }
        },
        label = "My Private Phone",
        privacyScreen = true
    },

    new KeeperRecordField
    {
        type = "date",
        value = new[] {(object) 1641934793000 },
        label = "My Date Lbl"
    },
    
    new KeeperRecordField { 
        type = "name",
        value = new[]
        {
            new Dictionary<string, string>
            {
                {"first", "John"},
                {"middle", "Patrick"},
                {"last", "Smith"}
            }
        },
        required = true
    },
    new KeeperRecordField
    {
        type = "oneTimeCode",
        value = new[]
        {
            "otpauth://totp/Example:[e-mail]?secret=JBSWY3DPEHPK3PXP&issuer=Example"
        },
        label = "My TOTP",
        required = true
    }
};
newRecord.notes = "\tThis custom type record was created\n\tvia Python SDK copied from https://docs.keeper.io/secrets-manager/secrets-manager/developer-sdk-library/.net-sdk";

var recordUid = await SecretsManagerClient.CreateSecret(options, "[FOLDER_UID]", newRecord);

シークレットの削除

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

Delete Secret

DeleteSecret(smOptions, recordsUids);

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

Example

using SecretsManager;

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

// UIDレコードで特定のシークレットを削除
await SecretsManagerClient.DeleteSecret(smOptions, new string[] {"EG6KdJaaLG7esRZbMnfbFA"});

キャッシュ

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

キャッシュの設定と構成

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

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

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

フォルダ

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

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

フォルダの読み取り

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

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