.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) + "]");
}
}
}
シークレットから値を取得
パスワードを取得
secret.FieldValue("password")
フィールドはタイプで検索されます。フィールドタイプの一覧は、レコードタイプのドキュメントをご参照ください。
Keeper表記法を使用して他のフィールドを取得
GetValue(KeeperSecrets secrets, string notation)
パラメータ
型
必須
デフォルト
説明
secrets
KeeperSecrets
はい
照会するシークレット
notation
string
はい
ドット記法形式のフィールドクエリ
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
はい
フィールドに設定する値
ランダムなパスワードを生成
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のみを指定できます
シークレットマネージャーSDKで作成したKeeperのレコードは、現時点ではファイル添付をサポートしていません
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番目の引数として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);
最終更新