Go SDK

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

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

GitHubからインストール

Go SDKの最新リリースは、https://github.com/Keeper-Security/secrets-manager-goで入手できます

$ go get github.com/keeper-security/secrets-manager-go/core

ソースコード

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

SDKの使用

初期化

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

シークレットを取得するには、まずシークレットマネージャークライアントを初期化する必要があります。

package main

import (	
    ksm "github.com/keeper-security/secrets-manager-go/core"	
)

func main() {
	clientOptions := &ksm.ClientOptions{
		Token:  "[One Time Access Token]",
		Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
	sm := ksm.NewSecretsManager(clientOptions)
	// トークンのみを使用して（後で使用するために）設定を生成するには
	// トークンをバインドするアクセス操作が少なくとも1回必要です
	sm.GetSecrets([]string{})
}

パラメータ

型

必須

デフォルト

説明

token

string

はい

Keeperシークレットマネージャーのワンタイムトークン

hostName

string

はい

接続先のサーバー

verifySslCerts

bool

はい

SSL証明書を検証するか否かを選択します

config

IKeyValueStorage

はい

ファイルストレージの設定

NewSecretsManager関数は、指定したパラメータでシークレットマネージャーを初期化し、ClientOptions構造体の設定を格納します。

secretsManager := NewSecretsManager(options)

シークレットの取得

records, err := sm.GetSecrets([]string{})

パラメータ

型

必須

デフォルト

説明

uids

[]string

はい

空のスライス

取得するUIDレコード

レスポンス

型: []*Record

指定したUIDを持つレコード、またはUIDを指定していない場合は、シークレットマネージャークライアントと共有されるすべてのレコード

使用例

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

package main

import (	
    ksm "github.com/keeper-security/secrets-manager-go/core"	
)

func main() {
	clientOptions := &ksm.ClientOptions{
		Token:  "[One Time Access Token]",
		Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
	sm := ksm.NewSecretsManager(clientOptions)
	allRecords, err := sm.GetSecrets([]string{})
}

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

package main

import (	
    ksm "github.com/keeper-security/secrets-manager-go/core"	
)

func main() {
	clientOptions := &ksm.ClientOptions{
		Token:  "[One Time Access Token]",
		Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
	sm := ksm.NewSecretsManager(clientOptions)
	records, err := sm.GetSecrets([]string{"[Secret UID]"})
}

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

// 一致するレコードをすべて取得
GetSecretsByTitle(recordTitle string) (records []*Record, err error)

// 最初に一致したレコードだけを取得
GetSecretByTitle(recordTitle string) (records *Record, err error)

パラメータ

型

必須

説明

recordTitle

string

はい

検索するレコードタイトル

使用例

package main

// シークレットマネージャーのインポート
import ksm "github.com/keeper-security/secrets-manager-go/core"

func main() {

	options := &ksm.ClientOptions{
		// ワンタイムトークンは一度しか使用できません - 以後は、生成された設定ファイルを使用します
		Config: ksm.NewFileKeyValueStorage("ksm-config.json")}

	sm := ksm.NewSecretsManager(options)

	// タイトルで個々のレコードを取得
	allRecords, _ := ksm.GetSecretsByTitle("My Credentials")

	for _, record := range allRecords {
		println("UID", record.Uid, ", title [", record.Title(), "]")
	}
}

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

パスワードを取得

secret.GetFieldsByType("password")

	clientOptions := &ksm.ClientOptions{
		Token:  "[One Time Access Token]",
		Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
	sm := ksm.NewSecretsManager(clientOptions)
	
	// すべてのレコードを取得
	allRecords, err := sm.GetSecrets([]string{})
	if err != nil {
		println("Error retrieving all records: ", err.Error())
		os.Exit(1)
	}

	// 最初のレコードを取得
	firstRecord := allRecords[0]

	// パスワードタイプのレコードの最初のフィールドを取得
	passwordField := map[string]interface{}{}
	if passwordFields := firstRecord.GetFieldsByType("password"); len(passwordFields) > 0 {
		passwordField = passwordFields[0]
	}

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

Keeper表記法を使用して値を取得

sm.GetNotation(query)

	clientOptions := &ksm.ClientOptions{
		Token:  "[One Time Access Token]",
		Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
	sm := ksm.NewSecretsManager(clientOptions)

	// 指定したUIDを持つレコードからパスワードを取得
	value, err := sm.GetNotation("[Record UID]/field/password")
	if err == nil && len(value) > 0 {
		if password, ok := value[0].(string); ok {
			println("Successfully retrieved field value using notation")
		}
	}

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

パラメータ

型

必須

デフォルト

説明

query

String

はい

指定したフィールドの値を取得するためのKeeper表記法を使用したクエリ

戻り値

型: []interface{}

照会したフィールドの値

TOTPコードを取得

GetTotpCode(url)

clientOptions := &ksm.ClientOptions{
	Token:  "[One Time Access Token]",
	Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
sm := ksm.NewSecretsManager(clientOptions)

// すべてのレコードを取得
allRecords, err := sm.GetSecrets([]string{})
if err == nil {
	// レコードからTOTP urlを取得
	urls, err := sm.GetNotation("[Record UID]/field/OneTimeCode")
	if err == nil && len(urls) == 1 {
		// urlからTOTPコードを取得
		url := urls[0].(string)
		totp, err := ksm.GetTotpCode(url)
		if err == nil {
			println(totp.Code, totp.TimeLeft)
		}
	}
}

パラメータ

型

必須

デフォルト

説明

url

string

はい

TOTP Url

シークレットを更新

パスワードを更新

(r *Record) SetPassword(password string)

パラメータ

型

必須

デフォルト

説明

password

string

はい

レコードに設定する新しいパスワード

他のフィールドを更新

(r *Record) SetFieldValueSingle(field string, value string)

パラメータ

型

必須

デフォルト

説明

field

string

はい

更新するフィールドの名前

value

string

はい

フィールドに設定する値

ボルトのシークレットを更新

レコードを保存して、変更内容を表示

(c *secretsManager) Save(record *Record) (err error)

パラメータ

型

必須

デフォルト

説明

record

KeeperRecord

はい

変更の保存が必要な更新されたフィールドのあるレコード

使用例

パスワードを更新

package main

import (	
    ksm "github.com/keeper-security/secrets-manager-go/core"	
)

func main() {
	clientOptions := &ksm.ClientOptions{
		Token:  "[One Time Access Token]",
		Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
	sm := ksm.NewSecretsManager(clientOptions)
	records, err := sm.GetSecrets([]string{"[Record UID]"})

	// 更新するレコードを取得
	record := records[0]

	// 新しいパスワードを設定
	record.SetPassword("NewPassword123$")

	// 変更を保存
	ksm.Save(record)
}

他のフィールドを更新

package main

import (	
    ksm "github.com/keeper-security/secrets-manager-go/core"	
)

func main() {
	clientOptions := &ksm.ClientOptions{
		Token:  "[One Time Access Token]",
		Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
	sm := ksm.NewSecretsManager(clientOptions)
	records, err := sm.GetSecrets([]string{"[Record UID]"})

	// 更新するレコードを取得
	record := records[0]

	// ログインフィールドを新しい値に設定
	record.SetFieldValueSingle("login", "New Login Value")

	// 変更を保存
	ksm.Save(record)
}

レコードの各フィールドタイプは、クラスに相当します。フィールドの値に正しくアクセスするために、フィールドを対応するクラスにキャストします。フィールドタイプの一覧は、レコードタイプのドキュメントをご確認ください。

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

GeneratePassword(length, lowercase, uppercase, digits, specialCharacters)

// レコードを取得
allRecords, err := sm.GetSecrets([]string{})
record := allRecords[0]
// ランダムなパスワードを生成
password := GeneratePassword(64, 0,0,0,0)
// 新しいパスワードでレコードを更新
record.SetPassword(password)

パラメータ

型

必須

デフォルト

length

int

はい

lowercase

int

はい

uppercase

int

はい

digits

int

はい

specialCharacters

int

はい

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

ファイルのダウンロード

(r *Record) DownloadFileByTitle(title string, path string) bool

パラメータ

型

必須

デフォルト

説明

title

string

はい

ダウンロードするファイルの名前

path

string

はい

ファイルの保存先のパス

レスポンス

型: bool

ファイルの保存が成功したか否か

使用例

import (	
    ksm "github.com/keeper-security/secrets-manager-go/core"	
)
clientOptions := &ksm.ClientOptions{
	Token:  "[One Time Access Token]",
	Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
sm := ksm.NewSecretsManager(clientOptions)

// 更新するレコードを取得
record, err := sm.GetSecrets([]string{"[Record UID]"})

// レコードに添付されたファイルをダウンロード
record.DownloadFileByTitle("certs.txt","secret_files/certs.txt")

ファイルのアップロード

UploadFile(record *Record, file *KeeperFileUpload) (uid string, err error)

パラメータ

型

必須

説明

ownerRecord

Record

はい

アップロードされたファイルを添付するレコード

file

KeeperFileUpload

はい

アップロードするファイル

type KeeperFileUpload struct {
	Name  string
	Title string
	Type  string
	Data  []byte
}

パラメータ

型

必須

説明

name

string

はい

アップロード後にKeeperに格納されるファイルの名前

title

string

はい

アップロード後にKeeperに格納されるファイルのタイトル

type

string

はい

ファイルのデータのMIMEタイプ（「application/octet-stream」など）

data

[]byte

はい

バイト型のファイルデータ

使用例

package main

// シークレットマネージャーのインポート
import ksm "github.com/keeper-security/secrets-manager-go/core"

func main() {

	options := &ksm.ClientOptions{
		// ワンタイムトークンは一度しか使用できません - 以後は、生成された設定ファイルを使用します
		Config: ksm.NewFileKeyValueStorage("ksm-config.json")}

	sm := ksm.NewSecretsManager(options)

	// ファイルをアップロードするレコードを取得
	allRecords, _ := sm.GetSecrets([]string{"[Record UID]"})
	ownerRecord := allRecords[0]
	
	// ファイルのデータを取得してアップロードを準備
	dat, err := ioutil.ReadFile("/myFile.json")
	var myFile := KeeperFileUpload{
		Name: "myFile.json",
		Title:"My File",
		Type: "application/json",
		Data: dat
	}
	
	// 選択したレコードにファイルをアップロード
	sm.UploadFile(ownerRecord, myFile)
}

シークレットの作成

前提条件:

共有フォルダのUID
- 共有フォルダには、シークレットマネージャーアプリケーションからアクセスできる必要があります
- あなたとシークレットマネージャーアプリケーションには編集権限が必要です
- 共有フォルダには、少なくとも1つのレコードが存在する必要があります
作成されたレコードとレコードのフィールドは正しく書式設定されている必要があります
- レコードタイプごとの適切なフィールド形式については、このドキュメントをご参照ください
TOTPフィールドには、KSM SDK以外で生成されたURLのみを指定できます

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

secretsManager.CreateSecretWithRecordData(recordUid, folderUid, record)

パラメータ

型

必須

デフォルト

recordUid

string

いいえ

自動生成されたランダムなUID

folderUid

string

はい

record

*RecordCreate

はい

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

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

// 新しいログインレコードを作成
newLoginRecord := NewRecordCreate("login", "Sample KSM Record:Go SDK")
// ログインフィールドとパスワードフィールドに入力
password, _ := GeneratePassword(32,0,0,0,0)
newLoginRecord.Fields = append(newLoginRecord.Fields,
    NewLogin("username@email.com"),
    NewPassword(password))
// メモに入力
newLoginRecord.Notes = "This is a Go record creation example"
// 新しいレコードを作成 
recordUid, err := secretsManager.CreateSecretWithRecordData("", "[FOLDER UID]", newLoginRecord)

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

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

customLogin := ksm.NewRecordCreate("Custom Login", "Sample Custom Type KSM Record:Go SDK")
password, _ := ksm.GeneratePassword(32, 0, 0, 0, 0)
customLogin.Fields = append(customLogin.Fields,
	ksm.NewHosts(ksm.Host{Hostname:"127.0.0.1", Port:"8080"}),
	ksm.NewLogin("login@email.com"),
	ksm.NewPassword(password),
	ksm.NewUrl("http://localhost:8080/login"),
	ksm.NewSecurityQuestions(ksm.SecurityQuestion{Question:"What is one plus one (write just a number)", Answer:"2"}),
	ksm.NewPhones(ksm.Phone{Region:"US", Number:"510-444-3333", Ext:"2345", Type:"Mobile"}),
	ksm.NewDate(1641934793000),
	ksm.NewNames(ksm.Name{First:"John", Middle:"Patrick", Last:"Smith"}),
	ksm.NewOneTimeCode("otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Example"),
)
customLogin.Custom = append(customLogin.Custom,
	ksm.NewPhones(ksm.Phone{Region:"US", Number:"510-222-5555", Ext:"99887", Type:"Mobile"}),
	ksm.NewPhones(ksm.Phone{Region:"US", Number:"510-111-3333", Ext:"45674", Type:"Mobile"}),
)
customLogin.Notes = "\tThis custom type record was created\n\tvia Go SDK copied from https://docs.keeper.io/secrets-manager/secrets-manager/developer-sdk-library/golang-sdk"
recordUid, err := sm.CreateSecretWithRecordData("", "[FOLDER UID]", customLogin)

シークレットの削除

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

secretsManager.DeleteSecrets(recordUids)

パラメータ

型

必須

recordUids

[]string

はい

import ksm "github.com/keeper-security/secrets-manager-go/core"

func main() {
	// シークレットマネージャーを設定
	options := &ksm.ClientOptions{
		// Token:  "<One Time Access Token>",
		Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
	secretsManager := ksm.NewSecretsManager(options)
	
	// UIDレコードで特定のシークレットを削除
	secrets, err = secretsManager.DeleteSecrets([]string{"EG6KdJaaLG7esRZbMnfbFA"})
}

キャッシュ

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

キャッシュの設定と構成

Go SDKでキャッシュを設定するには、SetCache(cache ICache)関数を使用して、内蔵メモリもしくはファイルベースのキャッシュのいずれかにキャッシュを設定するか、または独自の実装を使用します。

type ICache interface {
	SaveCachedValue(data []byte) error
	GetCachedValue() ([]byte, error)
	Purge() error
}

Go SDKには利便性を考慮して、メモリベースのキャッシュとファイルベースのキャッシュが組み込まれています。

options := &ksm.ClientOptions{Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
sm := ksm.NewSecretsManager(options)

// メモリベースのキャッシュ
memCache := ksm.NewMemoryCache()
sm.SetCache(memCache)

// ファイルベースのキャッシュ
fileCache := ksm.NewFileCache("ksm_cache.bin")
sm.SetCache(fileCache)

フォルダ

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

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

フォルダの読み取り

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

GetFolders() ([]*KeeperFolder, error)

レスポンス

型: []*KeeperFolder, error

使用例

package main

import ksm "github.com/keeper-security/secrets-manager-go/core"

func main() {
	options := &ksm.ClientOptions{Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
	sm := ksm.NewSecretsManager(options)
	folders, err := sm.GetFolders()
}

フォルダの作成

CreateOptionsとフォルダ名の指定が必要です。CreateOptionsはフォルダのUIDパラメータ（共有フォルダのUID）が必須ですが、サブフォルダのUIDはオプションであり、指定されていない場合は、通常の新しいフォルダが親 (共有フォルダ) の直下に作成されます。サブフォルダは、親の共有フォルダの直接の下位オブジェクトである必要はありません。深さレベルは様々な場合があります。

CreateFolder(createOptions CreateOptions, folderName string, folders []*KeeperFolder) (folderUid string, err error)

パラメータ

型

必須

説明

createOptions

CreateOptions

はい

親およびサブフォルダのUID

folderName

string

はい

フォルダ名

folders

[]*KeeperFolder

いいえ

CreateOptionsで作成した親とサブフォルダの検索に使用するフォルダのリスト

type CreateOptions struct {
	FolderUid    string
	SubFolderUid string
}

type KeeperFolder struct {
	FolderKey []byte
	FolderUid string
	ParentUid string
	Name      string
}

使用例

package main

import ksm "github.com/keeper-security/secrets-manager-go/core"

func main() {
	options := &ksm.ClientOptions{Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
	sm := ksm.NewSecretsManager(options)

	co := ksm.CreateOptions{FolderUid: "[SHARED_FOLDER_UID]", SubFolderUid: ""}
	uid, err := sm.CreateFolder(co, "new_folder", nil)
}

フォルダの更新

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

UpdateFolder(folderUid, folderName string, folders []*KeeperFolder) (err error)

パラメータ

型

必須

説明

folderUid

string

はい

フォルダのUID

folderName

string

はい

新しいフォルダ名

folders

[]*KeeperFolder

いいえ

親フォルダの検索に使用するフォルダのリスト

使用例

package main

import ksm "github.com/keeper-security/secrets-manager-go/core"

func main() {
	options := &ksm.ClientOptions{Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
	sm := ksm.NewSecretsManager(options)

	err := sm.UpdateFolder("[FOLDER_UID]", "new_folder_name", nil)
}

フォルダの削除

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

forceDeletionを使用する場合は、親フォルダと子フォルダのUIDを一緒に送信しないでください。削除する順序によっては、エラーが発生する可能性があります。_たとえば、_親が子を先に強制削除した場合。リストが必ずしもFIFO順で処理される保証はありません。

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

DeleteFolder(folderUids []string, forceDeletion bool) (statuses map[string]string, err error)

パラメータ

型

必須

説明

folderUids

[]string

はい

フォルダUIDリスト

forceDeletion

bool

はい

空でないフォルダを強制的に削除

使用例

package main

import ksm "github.com/keeper-security/secrets-manager-go/core"

func main() {
	options := &ksm.ClientOptions{Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
	sm := ksm.NewSecretsManager(options)

	stats, err := sm.DeleteFolder([]string{"[FOLDER_UID1]", "[FOLDER_UID2]"}, true)
}

前へ.NET SDK 次へレコードフィールドクラス

最終更新 3 か月前