Go SDK

Detailed Go SDK docs for Keeper Secrets Manager
Download and Installation
Install from GitHub
Find the latest Go SDK release at: https://github.com/Keeper-Security/secrets-manager-go​
$ go get github.com/keeper-security/secrets-manager-go/core
Source Code
Find the Go source code in the GitHub repository​
Using the SDK
Initialize
Using token only to generate a new config (for later usage) requires at least one read operation to bind the token and fully populate config.json
In order to retrieve secrets, you must first initialize the secrets manager client.
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)
	// Using token only to generate a config (for later usage)
	// requires at least one access operation to bind the token
	//sm.GetSecrets([]string{})
}
Parameter
Type
Required
Default
Description
token
string
Yes
​
Keeper Secrets Manager One time token
hostName
string
Yes
​
Server to connect to
verifySslCerts
bool
yes
​
Choose whether to verify SSL certificates or not
config
IKeyValueStorage
yes
​
File Storage Configuration
The NewSecretsManager function will initialize Secrets Manager from provided parameters and store settings from ClientOptions struct.
secretsManager := NewSecretsManager(options)
Retrieve Secrets
records, err := sm.GetSecrets([]string{})
Parameter
Type
Required
Default
Description
uids
[]string
Yes
Empty slice
Record UIDs to get
Response
Type: []*Record
Records with the specified UIDs, or all records shared with the Secrets Manager client if no UIDs are provided
Example Usage
Retrieve all Secrets
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{})
}
​
Retrieve Secrets with a Filter
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]"})
}
Retrieve Secrets by Title
// get all matching records
GetSecretsByTitle(recordTitle string) (records []*Record, err error)
​
// get only the first matching record
GetSecretByTitle(recordTitle string) (records *Record, err error)
Parameter
Type
Required
Description
recordTitle
string
Yes
Record title to search for
Example Usage
package main
​
// Import Secrets Manager
import ksm "github.com/keeper-security/secrets-manager-go/core"
​
func main() {
​
	options := &ksm.ClientOptions{
		// One time tokens can be used only once - afterwards use the generated config file
		Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
​
	sm := ksm.NewSecretsManager(options)
​
	// Retrieve the first matching record by title
	aRecord, _ := ksm.GetSecretByTitle("My Credentials")
​
	// Retrieve all matching records by title
	allRecords, _ := ksm.GetSecretsByTitle("My Credentials")
	for _, record := range allRecords {
		println("UID", record.Uid, ", title [", record.Title(), "]")
	}
}
Get Values From a Secret
Get a Password
Get Password
Example Usage
secret.GetFieldsByType("password")
	clientOptions := &ksm.ClientOptions{
		Token:  "[One Time Access Token]",
		Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
	sm := ksm.NewSecretsManager(clientOptions)
	
	// Get all records
	allRecords, err := sm.GetSecrets([]string{})
	if err != nil {
		println("Error retrieving all records: ", err.Error())
		os.Exit(1)
	}
​
	// Get first record
	firstRecord := allRecords[0]
​
	// Get first field in a record of type password
	passwordField := map[string]interface{}{}
	if passwordFields := firstRecord.GetFieldsByType("password"); len(passwordFields) > 0 {
		passwordField = passwordFields[0]
	}
​
Fields are found by type, for a list of field types see the Record Types documentation.
Retrieve Values using Keeper Notation
Get Notation
Example Usage
sm.GetNotation(query)
	clientOptions := &ksm.ClientOptions{
		Token:  "[One Time Access Token]",
		Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
	sm := ksm.NewSecretsManager(clientOptions)
​
	// Get password from record with the given 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")
		}
	}
See Keeper Notation documentation to learn about Keeper Notation format and capabilities
Parameter
Type
Required
Default
Description
query
String
Yes
​
Keeper Notation query for getting a value from a specified field
Returns
Type: []interface{}
The value of the queried field
Retrieve TOTP Code
Get TOTP Code
Example Usage
GetTotpCode(url)
clientOptions := &ksm.ClientOptions{
	Token:  "[One Time Access Token]",
	Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
sm := ksm.NewSecretsManager(clientOptions)
​
// Get all records
allRecords, err := sm.GetSecrets([]string{})
if err == nil {
	// Get TOTP url from record
	urls, err := sm.GetNotation("[Record UID]/field/OneTimeCode")
	if err == nil && len(urls) == 1 {
		// Get TOTP code from url
		url := urls[0].(string)
		totp, err := ksm.GetTotpCode(url)
		if err == nil {
			println(totp.Code, totp.TimeLeft)
		}
	}
}
Parameter
Type
Required
Default
Description
url
string
Yes
​
TOTP Url
Update a Secret
Update Password
(r *Record) SetPassword(password string) 
Parameter
Type
Required
Default
Description
password
string
Yes
​
New password to set to the record
Update Other Fields
(r *Record) SetFieldValueSingle(field string, value string) 
Parameter
Type
Required
Default
Description
field
string
Yes
​
name of the field to update
value
string
Yes
​
Value to set the field to
Update Secret in Vault
Save the record to make the changes made appear in the 
(c *secretsManager) Save(record *Record) (err error) 
Parameter
Type
Required
Default
Description
record
KeeperRecord
Yes
​
Record with updated field to save changes for
Example Usage
Update Password
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]"})
​
	// get record to update
	record := records[0]
​
	// set new password
	record.SetPassword("NewPassword123$")
​
	// save changes
	ksm.Save(record)
}
Update other fields
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]"})
​
	// get record to update
	record := records[0]
​
	// set login field to a new value
	record.SetFieldValueSingle("login", "New Login Value")
​
	// save changes
	ksm.Save(record)
}
Each record field type is represented by a class.  Cast the field to the corresponding class in order to correctly access the field's value.  Check the Record Types documentation for a list of field types.
Generate a Random Password
Generate Password
Example Usage
GeneratePassword(length, lowercase, uppercase, digits, specialCharaters)
// get a record
allRecords, err := sm.GetSecrets([]string{})
record := allRecords[0]
// generate a random password
password := GeneratePassword(64, 0,0,0,0)
// updaterecord with new password
record.SetPassword(password)
Parameter
Type
Required
Default
length
int
Yes
​
lowercase
int
Yes
​
uppercase
int
Yes
​
digits
int
Yes
​
specialCharacters
int
Yes
​
Each parameter indicates the minimum number of a type of character to include. For example, uppercase indicates the minimum uppercase letters to include.
Download a File
(r *Record) DownloadFileByTitle(title string, path string) bool
Parameter
Type
Required
Default
Description
title
string
Yes
​
Name of file to download
path
string
Yes
​
Path to save the file to
Response
Type: bool
Did the file save succeed
Example Usage
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)
​
// get record to update
record, err := sm.GetSecrets([]string{"[Record UID]"})
​
// download a file attached to the record
record.DownloadFileByTitle("certs.txt","secret_files/certs.txt")
Upload a File
UploadFile(record *Record, file *KeeperFileUpload) (uid string, err error)
Parameter
Type
Required
Description
ownerRecord
Record
Yes
The record to attach the uploaded file to
file
KeeperFileUpload
Yes
The File to upload
type KeeperFileUpload struct {
	Name  string
	Title string
	Type  string
	Data  []byte
}
Parameter
Type
Required
Description
name
string
Yes
What the name of the file will be in Keeper once uploaded
title
string
Yes
What the title of the file will be in Keeper once uploaded
type
string
Yes
The mime type of data in the file.  'application/octet-stream' for example
data
[]byte
Yes
File data as bytes
Example Usage
package main
​
// Import Secrets Manager
import ksm "github.com/keeper-security/secrets-manager-go/core"
​
func main() {
​
	options := &ksm.ClientOptions{
		// One time tokens can be used only once - afterwards use the generated config file
		Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
​
	sm := ksm.NewSecretsManager(options)
​
	// Get a record to upload the file to
	allRecords, _ := sm.GetSecrets([]string{"[Record UID]"})
	ownerRecord := allRecords[0]
	
	// get file data and prepare for upload
	dat, err := ioutil.ReadFile("/myFile.json")
	var myFile := KeeperFileUpload{
		Name: "myFile.json",
		Title: "My File",
		Type: "application/json",
		Data: dat
	}
	
	// upload file to selected record
	sm.UploadFile(ownerRecord, myFile)
}
Create a Secret
Prerequisites:
Shared folder UID
Shared folder must be accessible by the Secrets Manager Application
You and the Secrets Manager application must have edit permission
There must be at least one record in the shared folder
Created records and record fields must be formatted correctly
See the documentation for expected field formats for each record type
TOTP fields accept only URL generated outside of the KSM SDK
After record creation, you can upload file attachments using UploadFile​
Create a Record
Login Record Example
Custom Type Example
secretsManager.CreateSecretWithRecordData(recordUid, folderUid, record)
Parameter
Type
Required
Default
recordUid
string
No
auto generated random UID
folderUid
string
Yes
​
record
*RecordCreate
Yes
​
This example creates a login type record with a login value and a generated password.
Replace [FOLDER UID] in the example with the UID of a shared folder that your Secrets Manager has access to.
// create a new login record
newLoginRecord := NewRecordCreate("login", "Sample KSM Record: Go SDK")
// fill in login and password fields
password, _ := GeneratePassword(32,0,0,0,0)
newLoginRecord.Fields = append(newLoginRecord.Fields,
    NewLogin("[email protected]"),
    NewPassword(password))
// fill in notes
newLoginRecord.Notes = "This is a Go record creation example"
// create the new record 
recordUid, err := secretsManager.CreateSecretWithRecordData("", "[FOLDER UID]", newLoginRecord)
Replace [FOLDER UID] in the example with the UID of a shared folder that your Secrets Manager has access to.
This example creates a record with a custom record type.
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("[email protected]"),
	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:a[email protected]?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)
Delete a Secret
The Go KSM SDK can delete records in the Keeper Vault.
Delete Secret
Example
secretsManager.DeleteSecrets(recordUids)
​
Parameter
Type
Required
recordUids
[]string
Yes
import ksm "github.com/keeper-security/secrets-manager-go/core"
​
func main() {
	// setup secrets manager
	options := &ksm.ClientOptions{
		// Token:  "<One Time Access Token>",
		Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
	secretsManager := ksm.NewSecretsManager(options)
	
	// delete a specific secret by record UID
	secrets, err = secretsManager.DeleteSecrets([]string{"EG6KdJaaLG7esRZbMnfbFA"})
}
Caching
To protect against losing access to your secrets when network access is lost, the Go SDK allows caching of secrets to the local machine in an encrypted file.
Setup and Configure Cache
In order to setup caching in the Go SDK, use the function SetCache(cache ICache) to set the cache to either one of the built-in memory or file based caches or use your own implementation.
type ICache interface {
	SaveCachedValue(data []byte) error
	GetCachedValue() ([]byte, error)
	Purge() error
}
The Go SDK includes a memory based cache and a file based cache for convenience.
options := &ksm.ClientOptions{Config: ksm.NewFileKeyValueStorage("ksm-config.json")}
sm := ksm.NewSecretsManager(options)
​
// Memory based cache
memCache := ksm.NewMemoryCache()
sm.SetCache(memCache)
​
// File based cache
fileCache := ksm.NewFileCache("ksm_cache.bin")
sm.SetCache(fileCache)
Folders
Folders have full CRUD support - create, read, update and delete operations.
Read Folders
Downloads full folder hierarchy.
GetFolders() ([]*KeeperFolder, error)
Response
Type: []*KeeperFolder, error
Example Usage
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()
}
Create a Folder
Requires CreateOptions and folder name to be provided. The folder UID parameter in CreateOptions is required - UID of a shared folder, while sub-folder UID is optional and if missing new regular folder is created directly under the parent (shared folder). There's no requirement for the sub-folder to be a direct descendant of the parent shared folder - it could be many levels deep.
CreateFolder(createOptions CreateOptions, folderName string, folders []*KeeperFolder) (folderUid string, err error)
Parameter
Type
Required
Description
createOptions
CreateOptions
Yes
The parent and sub-folder UIDs
folderName
string
Yes
The Folder name
folders
[]*KeeperFolder
No
List of folders to use in the search for parent and sub-folder from CreateOptions 
type CreateOptions struct {
	FolderUid    string
	SubFolderUid string
}
type KeeperFolder struct {
	FolderKey []byte
	FolderUid string
	ParentUid string
	Name      string
}
Example Usage
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)
}
Update a Folder
Updates the folder metadata - currently folder name only.
UpdateFolder(folderUid, folderName string, folders []*KeeperFolder) (err error)
Parameter
Type
Required
Description
folderUid
string
Yes
The folder UID
folderName
string
Yes
The new folder name
Parameter	Type	Required
`length`	`int`	Yes
`lowercase`	`int`	Yes
`uppercase`	`int`	Yes
`digits`	`int`	Yes
`specialCharacters`	`int`	Yes
Parameter	Type	Required	Description
`ownerRecord`	`Record`	Yes	The record to attach the uploaded file to
`file`	`KeeperFileUpload`	Yes	The File to upload
Parameter	Type	Required	Description
`name`	`string`	Yes	What the name of the file will be in Keeper once uploaded
`title`	`string`	Yes	What the title of the file will be in Keeper once uploaded
`type`	`string`	Yes	The mime type of data in the file. 'application/octet-stream' for example
`data`	`[]byte`	Yes	File data as bytes
Parameter	Type	Required	Default
`recordUid`	`string`	No	auto generated random UID
`folderUid`	`string`	Yes
`record`	`*RecordCreate`	Yes
Parameter	Type	Required	Description
`createOptions`	`CreateOptions`	Yes	The parent and sub-folder UIDs
`folderName`	`string`	Yes	The Folder name
`folders`	`[]*KeeperFolder`	No	List of folders to use in the search for parent and sub-folder from CreateOptions
Parameter	Type	Required	Description
`folderUid`	`string`	Yes	The folder UID
`folderName`	`string`	Yes	The new folder name