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.
packagemainimport ( ksm "github.com/keeper-security/secrets-manager-go/core")funcmain() { 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
// get all matching recordsGetSecretsByTitle(recordTitle string) (records []*Record, err error)// get only the first matching recordGetSecretByTitle(recordTitle string) (records *Record, err error)
Parameter
Type
Required
Description
recordTitle
string
Yes
Record title to search for
Example Usage
packagemain// Import Secrets Managerimport ksm "github.com/keeper-security/secrets-manager-go/core"funcmain() { 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
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
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") } }
Keeper Notation query for getting a value from a specified field
Returns
Type: []interface{}
The value of the queried field
Retrieve TOTP Code
GetTotpCode(url)
clientOptions :=&ksm.ClientOptions{ Token: "[One Time Access Token]", Config: ksm.NewFileKeyValueStorage("ksm-config.json")}sm := ksm.NewSecretsManager(clientOptions)// Get all recordsallRecords, 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
Record update commands don't update local record data on success (esp. updated record revision) so any consecutive updates to an already updated record will fail due to revision mismatch. Make sure to reload all updated records after each update batch.
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
packagemainimport ( ksm "github.com/keeper-security/secrets-manager-go/core")funcmain() { 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)// Transactional updates// rotate password on the record record.SetPassword("NewPassword1234$")// start a transaction ksm.SaveBeginTransaction(secret, ksm.TransactionTypeRotation)// rotate password on remote host success :=rotateRemoteSshPassword("NewPassword1234$")// complete the transaction - commit or rollback ksm.CompleteTransaction(secret.Uid, !success)}
Update other fields
packagemainimport ( ksm "github.com/keeper-security/secrets-manager-go/core")funcmain() { 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.
// get a recordallRecords, err := sm.GetSecrets([]string{})record := allRecords[0]// generate a random passwordpassword :=GeneratePassword(64, 0,0,0,0)// updaterecord with new passwordrecord.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.
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 updaterecord, err := sm.GetSecrets([]string{"[Record UID]"})// download a file attached to the recordrecord.DownloadFileByTitle("certs.txt","secret_files/certs.txt")
typeKeeperFileUploadstruct { 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
packagemain// Import Secrets Managerimport ksm "github.com/keeper-security/secrets-manager-go/core"funcmain() { 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
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 recordnewLoginRecord :=NewRecordCreate("login", "Sample KSM Record: Go SDK")// fill in login and password fieldspassword, _ :=GeneratePassword(32,0,0,0,0)newLoginRecord.Fields =append(newLoginRecord.Fields,NewLogin("username@email.com"),NewPassword(password))// fill in notesnewLoginRecord.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("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)
Delete a Secret
The Go KSM SDK can delete records in the Keeper Vault.
secretsManager.DeleteSecrets(recordUids)
Parameter
Type
Required
recordUids
[]string
Yes
import ksm "github.com/keeper-security/secrets-manager-go/core"funcmain() {// 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.
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.
Removes a list of folders. Use forceDeletion flag to remove non-empty folders.
When using forceDeletion avoid sending parent with its children folder UIDs. Depending on the delete order you may get an error - ex. if parent force-deleted child first. There's no guarantee that list will always be processed in FIFO order.
Any folders UIDs missing from the vault or not shared to the KSM Application will not result in error.