Go SDK

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

要件

Go SDKではGo 1.16以上が必要です。

Goのバージョンを確認するには、以下のコマンドを実行します。

$ go version

アップグレードが必要な場合はhttps://go.dev/dl/をご参照ください。

v1.7.0の破壊的変更: 最低Goバージョンが1.16以上に引き上げられました。

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

GitHubからインストール

Go SDKの最新リリースは、GitHubのリポジトリから入手できます。

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

詳細については、pkg.go.dev のパッケージドキュメントをご参照ください。

ソースコード

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

SDKの使用

初期化

（後から再利用する場合）トークンのみで新しい構成を用意するには、読み取り操作を少なくとも 1 回実行し、トークンをバインドして config.json を完全に埋める必要があります。

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

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

ClientOptions のパラメータ

パラメータ

型

必須

デフォルト

説明

Token

string

初回のみ

リージョンプレフィックス付きのワンタイムアクセストークン (例: US:...)。初回バインドに必要です。

Config

IKeyValueStorage

はい

構成の永続化用ストレージ実装 (ファイルまたはメモリ)。

HostName

string

いいえ

トークンから導出

サーバーホスト名の上書き。トークンのリージョンプレフィックスから自動算出されます。

VerifySslCerts

bool

いいえ

true

SSL証明書の検証の有効/無効。*

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

sm := ksm.NewSecretsManager(options)

シークレットの取得

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

パラメータ

型

説明

uids

[]string

取得するレコードのUID。空のスライス []string{} を渡すと、共有されているすべてのレコードを取得

レスポンス

型: []*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) (record *Record, err error)

パラメータ

型

説明

recordTitle

string

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

使用例

package main

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

func main() {

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

  sm := ksm.NewSecretsManager(options)

  // タイトルが一致する最初の1件のレコードを取得
  aRecord, err := sm.GetSecretByTitle("My Credentials")
  if err != nil {
    fmt.Printf("Error retrieving record: %v\n", err)
    return
  }
  fmt.Printf("Found record: %s\n", aRecord.Title())

  // タイトルが一致するすべてのレコードを取得
  allRecords, err := sm.GetSecretsByTitle("My Credentials")
  
  if err != nil {
    fmt.Printf("Error retrieving records: %v\n", err)
    return
  }

  for _, record := range allRecords {
    fmt.Printf("UID %s, title [%s]\n", record.Uid, record.Title())
  }
}

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

パスワードを取得

(r *Record) Password() string

フィールド型から値を取得

(r *Record) GetFieldValueByType(fieldType string) string

パラメータ

型

説明

fieldType

string

フィールド型 (例: login、url)

一致する標準フィールドの先頭の値を文字列で返します。フィールドが存在しない場合は空文字列を返します。複数値や構造化フィールドには GetFieldsByType を使用します。

フィールド型はKeeperのレコードタイプに基づきます。レコードタイプごとの利用可能なフィールドの一覧は、Keeperコマンダーの record-type-info コマンドをご参照ください。

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

GetNotation

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

クエリに一致したフィールドの値

GetNotationResults

(c *SecretsManager) GetNotationResults(notation string) ([]string, error)
(c *SecretsManager) TryGetNotationResults(notation string) []string

パラメータ

型

説明

notation

string

Keeper表記法のクエリ

GetNotationResults はフィールド値を []string として返します。値が文字列のときは GetNotation の代わりにこちらを使います。TryGetNotationResults はエラーを返さない版で、失敗時は空のスライスを返します。

使用例

values, err := sm.GetNotationResults("[Record UID]/field/password")
if err == nil && len(values) > 0 {
    password := values[0]
}

password := ""
if values := sm.TryGetNotationResults("[Record UID]/field/password"); len(values) > 0 {
    password = values[0]
}

TOTPコードを取得

GetTotpCode(url)

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

urls, err := sm.GetNotation("[Record UID]/field/oneTimeCode")
if err == nil && len(urls) == 1 {
    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

*Record

保存する更新済みフィールドを含むレコード

使用例

パスワードを更新

package main

import (
  "fmt"
  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]"})
  if err != nil {
    fmt.Printf("Error: %v\n", err)
    return
  }

  if len(records) == 0 {
    fmt.Println("No records found")
    return
  }

  record := records[0]
  record.SetPassword("NewPassword123$")

  err = sm.Save(record)
  if err != nil {
    fmt.Printf("Error saving record: %v\n", err)
    return
  }

  record.SetPassword("NewPassword1234$")

  err = sm.SaveBeginTransaction(record, ksm.TransactionTypeRotation)
  if err != nil {
    fmt.Printf("Error starting transaction: %v\n", err)
    return
  }

  success := rotateRemoteSshPassword("NewPassword1234$")

  err = sm.CompleteTransaction(record.Uid, !success)
  if err != nil {
    fmt.Printf("Error completing transaction: %v\n", err)
    return
  }
}

func rotateRemoteSshPassword(newPassword string) bool {
  return true
}

CompleteTransaction(uid, rollback bool) では、false を渡すとローテーションをコミットし、true を渡すとロールバックします。例では !success を渡しており、ローテーション関数が false (失敗) を返したときに true (ロールバック) になります。

他のフィールドを更新

package main

import (
  "fmt"
  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]"})
  if err != nil {
    fmt.Printf("Error: %v\n", err)
    return
  }

  if len(records) == 0 {
    fmt.Println("No records found")
    return
  }

  record := records[0]
  record.SetFieldValueSingle("login", "New Login Value")
  record.SetTitle("New Title")
  record.SetNotes("Updated notes with additional context")

  err = sm.Save(record)
  if err != nil {
    fmt.Printf("Error saving record: %v\n", err)
    return
  }
}

v1.7.0: SetNotes はUPSERT動作になり、レコードにメモフィールドが存在しない場合は作成します。v1.6.x以前では、メモのないレコードに対する SetNotes は何も行いませんでした。

レコードの各フィールド型はクラスとして表現されます。値を正しく扱うには、フィールドを対応する型にキャストします。フィールド型の一覧は、レコードタイプのドキュメントをご参照ください。

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

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

allRecords, err := sm.GetSecrets([]string{})
if err != nil {
  fmt.Printf("Error: %v\n", err)
  return
}

if len(allRecords) == 0 {
  fmt.Println("No records found")
  return
}

record := allRecords[0]

password, err := ksm.GeneratePassword(64, "", "", "", "", "")
if err != nil {
  fmt.Printf("Error generating password: %v\n", err)
  return
}

record.SetPassword(password)

err = sm.Save(record)
if err != nil {
  fmt.Printf("Error saving record: %v\n", err)
  return
}

パラメータ

型

説明

length

int

パスワード長。0 以下を渡すとデフォルト (32文字) を使用します

lowercase

string

小文字の最小数。最小を設けない場合は ""

uppercase

string

大文字の最小数。最小を設けない場合は ""

digits

string

数字の最小数。最小を設けない場合は ""

specialCharacters

string

記号の最小数。最小を設けない場合は ""

specialCharacterSet

string

使用する記号の集合。"" の場合はデフォルト "!@#$%()+;<>=?[]{}^.," を使用します

ファイルのダウンロード

DownloadFileByTitle

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

パラメータ

型

説明

title

string

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

path

string

保存先のパス

レスポンス

型: error

成功時は nil を返します。失敗時は、タイトル不一致・ディレクトリ不存在・書き込み失敗などを示すエラーを返します。ログ出力や上位へのラップに利用します。

使用例

import (
  "fmt"
  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)

records, err := sm.GetSecrets([]string{"[Record UID]"})
if err != nil {
  fmt.Printf("Error: %v\n", err)
  return
}

if len(records) == 0 {
  fmt.Println("No records found")
  return
}

record := records[0]

record.DownloadFileByTitle("certs.txt","secret_files/certs.txt")

DownloadFile

(r *Record) DownloadFile(fileUid string, path string) error

パラメータ

型

説明

fileUid

string

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

path

string

保存先のパス

レスポンス

型: error

使用例

records, err := sm.GetSecrets([]string{"[Record UID]"})
if err != nil || len(records) == 0 {
    return
}
for _, file := range records[0].Files {
    if err := records[0].DownloadFile(file.Uid, "/tmp/"+file.Name); err != nil {
        fmt.Printf("error downloading %s: %v\n", file.Name, err)
    }
}

SaveFile

(f *KeeperFile) SaveFile(path string, createFolders bool) error

パラメータ

型

説明

path

string

書き込み先のフルパス

createFolders

bool

true のとき、親ディレクトリがなければ作成します

レスポンス

型: error

record.Files から得た *KeeperFile に対して使用します。

使用例

records, err := sm.GetSecrets([]string{"[Record UID]"})
if err != nil || len(records) == 0 {
    return
}
for _, file := range records[0].Files {
    if err := file.SaveFile("/tmp/"+file.Name, true); err != nil {
        fmt.Printf("error saving %s: %v\n", file.Name, err)
    }
}

ファイルのアップロード

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 (
  "fmt"
  "os"

  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, err := sm.GetSecrets([]string{"[Record UID]"})
  if err != nil {
    fmt.Printf("Error: %v\n", err)
    return
  }

  if len(allRecords) == 0 {
    fmt.Println("No records found")
    return
  }

  ownerRecord := allRecords[0]

  dat, err := os.ReadFile("/myFile.json")
  if err != nil {
    fmt.Printf("Error reading file: %v\n", err)
    return
  }

  myFile := ksm.KeeperFileUpload{
    Name:  "myFile.json",
    Title: "My File",
    Type:  "application/json",
    Data:  dat,
  }

  _, err = sm.UploadFile(ownerRecord, &myFile)
  if err != nil {
    fmt.Printf("Error uploading file: %v\n", err)
    return
  }

  fmt.Println("File uploaded successfully")
}

ファイルパスからアップロード

(c *SecretsManager) UploadFilePath(record *Record, filePath string) (uid string, err error)

パラメータ

型

説明

record

*Record

ファイルを添付するレコード

filePath

string

アップロードするローカルファイルのパス

レスポンス

型: string, error

アップロードされた添付ファイルのUIDを返します。ディスクから直接アップロードする場合に UploadFile の代わりに使います。ファイルを読み込み、MIMEタイプを推定して内部で UploadFile を呼び出します。

使用例

records, err := sm.GetSecrets([]string{"[Record UID]"})
if err != nil || len(records) == 0 {
    return
}
uid, err := sm.UploadFilePath(records[0], "/path/to/myFile.json")
if err != nil {
    fmt.Printf("error uploading file: %v\n", err)
    return
}
fmt.Printf("uploaded file UID: %s\n", uid)

レコードからファイルを削除する

SaveWithOptions() 呼び出し時に LinksToRemove にファイルUIDを指定すると、レコードからファイルを外せます。

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

func removeFileFromRecord(sm *ksm.SecretsManager, recordUid string, fileUid string) error {
    records, err := sm.GetSecrets([]string{recordUid})
    if err != nil {
        return err
    }

    if len(records) == 0 {
        return fmt.Errorf("record not found: %s", recordUid)
    }

    record := records[0]

    updateOptions := ksm.UpdateOptions{
        LinksToRemove: []string{fileUid},
    }

    err = sm.SaveWithOptions(record, updateOptions)
    if err != nil {
        return fmt.Errorf("failed to remove file: %w", err)
    }

    fmt.Printf("File %s removed from record %s\n", fileUid, recordUid)
    return nil
}

複数ファイルの削除:

updateOptions := ksm.UpdateOptions{
    LinksToRemove: []string{"FILE_UID_1", "FILE_UID_2", "FILE_UID_3"},
}
err := sm.SaveWithOptions(record, updateOptions)

UpdateOptions

UpdateOptions は SaveWithOptions および SaveBeginTransaction のオプション動作を制御します。

フィールド

型

説明

TransactionType

UpdateTransactionType

二相のトランザクション更新には Rotation を指定。通常の保存では省略。

LinksToRemove

[]string

保存時にレコードから切り離すファイルのUID。

シークレットの作成

要件

共有フォルダのUID
- 共有フォルダには、シークレットマネージャーアプリケーションからアクセスできる必要があります
- ユーザーとシークレットマネージャーアプリケーションの双方に編集権限が必要です
- 共有フォルダには、少なくとも1つのレコードが存在する必要があります
作成されたレコードとレコードのフィールドは正しく書式設定されている必要があります
- レコードタイプごとのフィールド形式の詳細は、レコードタイプ定義をご参照ください
TOTPフィールドには、KSM SDKの外で生成したURLのみを指定できます
レコード作成後は、ファイルのアップロードの UploadFile を使ってファイル添付をアップロードできます

secretsManager.CreateSecretWithRecordData(recordUid, folderUid, record)

パラメータ

型

必須

デフォルト

recordUid

string

いいえ

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

folderUid

string

はい

record

*RecordCreate

はい

recordUid は任意です。"" を渡すと、SDKがUIDを自動生成します。

secretsManager.CreateSecretWithRecordDataAndOptions(createOptions, recordData, folders)

パラメータ

型

必須

デフォルト

createOptions

*CreateOptions

はい

recordData

*RecordCreate

はい

folders

[]*KeeperFolder

いいえ

folders に nil を渡すと、SDKがフォルダ一覧を自動取得します。

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

例に含まれる [FOLDER UID] を、シークレットマネージャーがアクセスできる共有フォルダのUIDに置き換えてください。

package main

import (
  "fmt"
  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)

  newLoginRecord := ksm.NewRecordCreate("login", "Sample KSM Record: Go SDK")

  password, err := ksm.GeneratePassword(32, "", "", "", "", "")
  if err != nil {
    fmt.Printf("Error generating password: %v\n", err)
    return
  }

  newLoginRecord.Fields = append(newLoginRecord.Fields,
    ksm.NewLogin("username@email.com"),
    ksm.NewPassword(password))

  newLoginRecord.Notes = "This is a Go record creation example"

  recordUid, err := sm.CreateSecretWithRecordData("", "[FOLDER UID]", newLoginRecord)
  if err != nil {
    fmt.Printf("Error creating record: %v\n", err)
    return
  }

  fmt.Printf("Record created with UID: %s\n", recordUid)
}

例に含まれる [FOLDER UID] を、シークレットマネージャーがアクセスできる共有フォルダのUIDに置き換えてください。

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

package main

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

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

customLogin := ksm.NewRecordCreate("Custom Login", "Sample Custom Type KSM Record: Go SDK")
password, err := ksm.GeneratePassword(32, "", "", "", "", "")
if err != nil {
  fmt.Printf("Error generating password: %v\n", err)
  return
}
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)
if err != nil {
  fmt.Printf("Error creating record: %v\n", err)
  return
}

fmt.Printf("Custom record created with UID: %s\n", recordUid)
}

シークレットの削除

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

statuses, err := secretsManager.DeleteSecrets(recordUids)

パラメータ

型

説明

recordUids

[]string

削除するレコードのUID

戻り値

型

説明

statuses

map[string]string

UIDごとの削除結果

err

error

エラー (ある場合)

ボルトに存在しない、またはKSMアプリケーションからアクセスできないUIDは黙ってスキップされ、エラーにはなりません。

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

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

  statuses, err := secretsManager.DeleteSecrets([]string{"EG6KdJaaLG7esRZbMnfbFA"})
  if err != nil {
    fmt.Printf("Error deleting secrets: %v\n", err)
    return
  }

  for uid, status := range statuses {
    fmt.Printf("%s: %s\n", uid, status)
  }
}

キャッシュ

ネットワークに接続できないときでもシークレットを参照できるよう、Go SDKでシークレットを暗号化したファイルとしてローカルにキャッシュできます。

キャッシュの設定と構成

キャッシュを有効にするには、SetCache(cache ICache) を呼び出し、組み込みのメモリまたはファイルベースの実装のいずれかを渡すか、独自の 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)

オフライン時のフォールバック動作を示す完全な ICache 実装の例は、SDKリポジトリの example/custom-cache/main.go をご参照ください。

SDKは常にまずライブのネットワーク要求を試みます。キャッシュは、サーバーがHTTP 200以外を返した場合、またはDNS解決失敗・接続拒否・TLSハンドシェイク失敗・タイムアウトなどトランスポート層での失敗があった場合にフォールバックとして参照されます。ネットワーク層のエラーでキャッシュからレコードが返されると警告がログに出力されます。GetSecrets が成功するたびに、キャッシュは最新のレスポンスで更新されます。

直近のリクエストのみ: キャッシュは最も新しいレスポンスだけを保持します。最後に成功した呼び出しがUIDフィルタ付きだった場合、キャッシュフォールバックではそのレコードだけが返り、アプリケーションに共有されているすべてのレコードは返りません。キャッシュの使い方はこの点を踏まえて設計してください。

更新後: レコードを保存するとボルト上のリビジョンが変わります。更新後にキャッシュへフォールバックすると、キャッシュのリビジョンは古いままとなり、同じレコードへの続けての更新はリビジョン不一致で失敗します。保存のたびに GetSecrets を呼び出してキャッシュを更新してください。

フォルダ

フォルダでは、作成・読み取り・更新・削除 (CRUD) の操作がすべて利用できます。

フォルダの読み取り

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

GetFolders() ([]*KeeperFolder, error)

レスポンス

型: []*KeeperFolder, error

使用例

package main

import (
  "fmt"
  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()
  if err != nil {
    fmt.Printf("Error: %v\n", err)
    return
  }

  fmt.Printf("Retrieved %d folder(s)\n", len(folders))
}

フォルダの作成

フォルダの作成には CreateOptions とフォルダ名が必要です。CreateOptions のフォルダ UID パラメータ (共有フォルダの 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: "[PARENT_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を1つのリストにまとめて送らないでください。削除順によってはエラーになることがあります (例: 親が子より先に強制削除された場合)。リストが常にFIFO順で処理される保証はありません。

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

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

パラメータ

型

必須

説明

folderUids

[]string

はい

削除するフォルダのUID

forceDeletion

bool

いいえ

空でないフォルダを削除するには true

使用例

package main

import (
  "fmt"
  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)
  if err != nil {
    fmt.Printf("Error: %v\n", err)
    return
  }

  fmt.Printf("Deleted %d folder(s)\n", len(stats))
}

高度な構成

トークンのリージョンプレフィックス

トークンにリージョンプレフィックスが含まれている場合、接続先のKeeperデータセンターが自動的に選ばれます。

リージョンコード

データセンター

ホスト名

US

United States

keepersecurity.com

EU

Europe

keepersecurity.eu

AU

Australia

keepersecurity.com.au

GOV

US Government Cloud

govcloud.keepersecurity.us

JP

Japan

keepersecurity.jp

CA

Canada

keepersecurity.ca

トークンの例

US:KBChlYeZ15wLzvhLVXmT61euw0DJO0cTVfkD-b-qesw
EU:JhGxK92pLmNqR5TvWx3YzAbC8dEfGhI0jKlMnOpQrSt

SDKはリージョンプレフィックスから接続先を判断します。プレフィックスがない場合は、ClientOptions の Hostname を明示的に指定する必要があります。

HTTPプロキシ構成

Go SDKは、標準の環境変数からプロキシ設定を自動検出します。

環境変数

SDKは以下の順で環境変数を確認します。

HTTPS_PROXY または https_proxy - HTTPS向けに推奨
HTTP_PROXY または http_proxy - フォールバック用プロキシ
NO_PROXY または no_proxy - プロキシを使わないホストのカンマ区切りリスト

例

export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

認証付きプロキシ:

export HTTPS_PROXY=http://username:password@proxy.company.com:8080

バイパスリスト付き:

export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.company.com

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

func main() {
    os.Setenv("HTTPS_PROXY", "http://proxy.company.com:8080")

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

    records, err := sm.GetSecrets([]string{})
    if err != nil {
        // エラー処理
    }
}

認証情報の特殊文字: ユーザー名とパスワードに含まれる特殊文字はパーセントエンコーディングでURLエンコードします (例: @ は %40、! は %21)。

`KSM_CONFIG` 環境変数

CI/CDやコンテナ環境では、ClientOptions に Config を渡さない場合、SDKは KSM_CONFIG 環境変数から構成を自動読み込みします。

初回の端末バインド後に生成したJSON構成をBase64で設定します。

export KSM_CONFIG="<base64-encoded config JSON>"

sm := ksm.NewSecretsManager(&ksm.ClientOptions{})

既存の ksm-config.json からBase64値を生成する例です。

base64 -w 0 ksm-config.json

KSM_CONFIG は ClientOptions.Config が nil のときだけ読み込まれます。Config を明示的に渡すと、環境変数は無視されます。

構成ファイルのセキュリティ

NewFileKeyValueStorage() を使うと、SDKは自動的に以下を行います。

新規構成ファイルを権限 0600 (所有者のみ読み書き) で作成
アクセスを所有者に限定し、他ユーザーからの参照を防ぐ
暗号化キーとデバイストークンを安全に保存

権限の確認

$ ls -l ksm-config.json
-rw------- 1 user user 1234 Dec 26 10:00 ksm-config.json

rw------- (0600) により、構成ファイルは所有者だけが読み書きできます。

セキュリティ上の推奨事項

構成ファイルをバージョン管理にコミットしない (.gitignore に *.json を追加)
開発・ステージング・本番で別の構成を使う
ワンタイムアクセストークンは90日ごとにローテーション
構成ファイルは安全で暗号化されたディレクトリに保存

エラー処理

v1.7.0で改善: HTTPエラーは *core.KeeperHTTPError 型で返り、StatusCode、ResultCode、Message フィールドを持ちます。文字列を解析する代わりに errors.As で扱えます。エラーメッセージ文字列には、すべてのパスでHTTPステータスコードが一貫して含まれます。

よくあるHTTPステータスコード

ステータスコード

エラー種別

推奨アクション

401

Unauthorized

新しいワンタイムトークンで再初期化

403

Forbidden

シークレットマネージャーでアプリケーション権限を確認

404

Not Found

UIDが正しくアクセス可能か確認

429

Too Many Requests

指数バックオフで再試行

500

Internal Server Error

指数バックオフで再試行

503

Service Unavailable

しばらく待ってから再試行

v1.7.0の破壊的変更: 復号失敗時の nil 返却

以下の関数は、復号に失敗した場合に空のスタブではなく nil を返すようになりました。

レコード鍵またはレコードデータの復号に失敗したときの NewRecordFromJson
フォルダ復号に失敗したときの NewFolderFromJson / NewKeeperFolder
ファイル鍵の復号に失敗したときの NewKeeperFileFromJson

また、直後のバインドフローでアプリ鍵の復号に失敗した場合、GetSecrets は空リストと nil エラーではなくエラーを返します。

これらの関数を直接呼ぶ場合は、戻り値をデリファレンスする前に nil チェックを追加してください。

v1.7.0の破壊的変更: HTTPエラー文字列の形式

JSONエラー応答のエラー文字列には HTTPStatus=N プレフィックスが付くようになりました (例: POST Error: HTTPStatus=403 Error: access_denied, message=...)。以前のJSONエラーパスではステータスコードが文字列に含まれませんでした。文字列を解析している呼び出し側は、errors.As(err, &khe) へ移行し、khe.StatusCode、khe.ResultCode、khe.Message をコードから直接取得してください。

型付きHTTPエラー

GetSecrets および関連呼び出しからのHTTPエラーはすべて *core.KeeperHTTPError として返ります。文字列を解析する代わりに errors.As で構造化情報を取り出します。

type KeeperHTTPError struct {
    StatusCode int
    ResultCode string
    Message    string
    Body       []byte
}

GetSecrets から返ると、呼び出し側には POST Error: HTTPStatus=403 Error: access_denied, message=... のように見えます。

基本的なエラー処理

records, err := sm.GetSecrets([]string{"UID1", "UID2"})
if err != nil {
    fmt.Printf("Error retrieving secrets: %v\n", err)
    return
}

特定のHTTPステータスを判定

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

records, err := sm.GetSecrets([]string{"UID1"})
if err != nil {
    var khe *ksm.KeeperHTTPError
    if errors.As(err, &khe) {
        switch khe.StatusCode {
        case 401:
            fmt.Println("Authentication failed. Please re-initialize with a new token.")
        case 403:
            fmt.Printf("Access denied (%s). Check application permissions in Secrets Manager.\n", khe.ResultCode)
        case 404:
            fmt.Println("Record not found. Verify the UID is correct.")
        case 429:
            fmt.Println("Rate limit exceeded. Retrying with exponential backoff...")
        default:
            fmt.Printf("HTTP %d (%s): %s\n", khe.StatusCode, khe.ResultCode, khe.Message)
        }
        return
    }
    fmt.Printf("Unexpected error: %v\n", err)
    return
}

破損レコードの扱い

v1.7.0の耐性強化: レコード・ファイル・フォルダで暗号化が破損している場合でも、SDKは全体を失敗させずに処理を続けます。

破損したレコードは警告を出してスキップ
破損したファイルはファイル一覧から除外
破損したフォルダは全体失敗を引き起こさないように処理
有効なレコードは引き続き正常に返却

records, err := sm.GetSecrets([]string{})
if err != nil {
    fmt.Printf("Error: %v\n", err)
    return
}

fmt.Printf("Retrieved %d accessible records\n", len(records))

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

最終更新 1 か月前

こんばんは

要件

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

GitHubからインストール

ソースコード

SDKの使用

初期化

シークレットの取得

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

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

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

戻り値

GetNotationResults

TOTPコードを取得

シークレットを更新

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

ファイルのダウンロード

ファイルのアップロード

ファイルパスからアップロード

レコードからファイルを削除する

UpdateOptions

シークレットの作成

要件

シークレットの削除

キャッシュ

フォルダ

フォルダの読み取り

フォルダの作成

フォルダの更新

フォルダの削除

高度な構成

トークンのリージョンプレフィックス

HTTPプロキシ構成

KSM_CONFIG 環境変数

構成ファイルのセキュリティ

エラー処理

型付きHTTPエラー

`KSM_CONFIG` 環境変数