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(), "]")
	}
}

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

パスワードを取得

Get Password

secret.GetFieldsByType("password")

Example Usage

	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表記法を使用して値を取得

Get Notation

sm.GetNotation(query)

Example Usage

	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コードを取得

Get TOTP Code

GetTotpCode(url)

Example Usage

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

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

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

Generate Password

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

Example Usage

// レコードを取得
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のレコードは、現時点ではファイル添付をサポートしていません

Create a Record

secretsManager.CreateSecretWithRecordData(recordUid, folderUid, record)

パラメータ	型	必須	デフォルト
recordUid	string	いいえ	自動生成されたランダムなUID
folderUid	string	はい
record	*RecordCreate	はい

Login Record Example

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

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

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

Custom Type Example

例にある[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("[e-mail]"),
	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:[e-mail]?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ボルトのレコードを削除できます。

Delete Secret

secretsManager.DeleteSecrets(recordUids)

パラメータ	型	必須
recordUids	[]string	はい

Example

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