Documentation ¶
Overview ¶
Package gosecret is(/was originally) a fork of go-libsecret (see https://github.com/gsterjov/go-libsecret and https://pkg.go.dev/github.com/gsterjov/go-libsecret).
It was forked in order to present bugfixes, actually document the library, conform to more Go-like patterns, and provide missing functionality (as the original seems to be unmaintained). As such, hopefully this library should serve as a more effective libsecret/SecretService interface.
Backwards Compatibility ¶
Version series `v0.X.X` of this library promises full and non-breaking backwards compatibility/drop-in support of API interaction with the original project. The only changes should be internal optimizations, adding documentation, some file reorganizing, adding Golang module support, etc. -- all transparent from the library API itself.
To use this library as a replacement without significantly modifying your code, you can simply use a `replace` directive in your go.mod file:
// ... replace ( github.com/gsterjov/go-libsecret dev => r00t2.io/gosecret v0 )
and then run `go mod tidy`.
Do NOT use the master branch. For anything. I make no promises on the stability of that branch at any given time. New features will be added to V1 branch, and stable releases will be tagged. V0 branch is reserved only for optimization and bug fixes.
New Developer API ¶
Starting from `v1.0.0` onwards, entirely breaking changes can be assumed from the original project. To use the new version,
import ( `r00t2.io/gosecret/v1` )
To reflect the absolute breaking changes, the module name changes as well from `libsecret` to `gosecret`.
SecretService Concepts ¶
For reference:
- A Service allows one to retrieve and operate on/with Session and Collection objects.
- A Session allows one to operate on/with Item objects (e.g. parsing/decoding/decrypting them).
- A Collection allows one to retrieve and operate on/with Item objects.
- An Item allows one to retrieve and operate on/with Secret objects.
(Secrets are considered "terminating objects" in this model, and contain actual secret value(s) and metadata).
Various interactions are handled by Prompts.
So the object hierarchy in THEORY looks kind of like this:
Service ├─ Session "A" ├─ Session "B" ├─ Collection "A" │ ├─ Item "A.1" │ │ ├─ Secret "A_1_a" │ │ └─ Secret "A_1_b" │ └─ Item "A.2" │ ├─ Secret "A_2_a" │ └─ Secret "A_2_b" └─ Collection "B" ├─ Item "B.1" │ ├─ Secret "B_1_a" │ └─ Secret "B_1_b" └─ Item "B.2" ├─ Secret "B_2_a" └─ Secret "B_2_b"
And so on. In PRACTICE, however, most users will only have two Collection items (a default "system" one named "login", which usually is unlocked upon login, and a temporary one that may or may not exist, running in memory for the current login session named `session`).
Usage ¶
Full documentation can be found via inline documentation. Additionally, use either https://pkg.go.dev/r00t2.io/gosecret or https://pkg.go.dev/golang.org/x/tools/cmd/godoc (or `go doc`) in the source root.
Index ¶
- Constants
- Variables
- func NewErrors(errs ...error) (err error)
- func TranslateError(ssErr SecretServiceErrEnum) (ok bool, err error)
- type Collection
- func (c *Collection) CreateItem(label string, attrs map[string]string, secret *Secret, replace bool, ...) (item *Item, err error)
- func (c *Collection) Created() (created time.Time, err error)
- func (c *Collection) Delete() (err error)
- func (c *Collection) Items() (items []*Item, err error)
- func (c *Collection) Label() (label string, err error)
- func (c *Collection) Locked() (isLocked bool, err error)
- func (c *Collection) Modified() (modified time.Time, isChanged bool, err error)
- func (c *Collection) PathName() (realName string)
- func (c *Collection) Relabel(newLabel string) (err error)
- func (c *Collection) SearchItems(profile string) (items []*Item, err error)deprecated
- type CollectionInitFlag
- type ConnPathCheckResult
- type DbusObject
- type Item
- func (i *Item) Attributes() (attrs map[string]string, err error)
- func (i *Item) Created() (created time.Time, err error)
- func (i *Item) Delete() (err error)
- func (i *Item) GetSecret(session *Session) (secret *Secret, err error)
- func (i *Item) Label() (label string, err error)
- func (i *Item) Locked() (isLocked bool, err error)
- func (i *Item) Modified() (modified time.Time, isChanged bool, err error)
- func (i *Item) ModifyAttributes(replaceAttrs map[string]string) (err error)
- func (i *Item) Relabel(newLabel string) (err error)
- func (i *Item) ReplaceAttributes(newAttrs map[string]string) (err error)
- func (i *Item) SetSecret(secret *Secret) (err error)
- func (i *Item) Type() (itemType string, err error)
- type ItemInitFlag
- type ItemSearchFlag
- type MultiError
- type Prompt
- type Secret
- type SecretServiceErrEnum
- type SecretServiceError
- type SecretValue
- type Service
- func (s *Service) Close() (err error)
- func (s *Service) Collections() (collections []*Collection, err error)
- func (s *Service) CreateAliasedCollection(label, alias string) (collection *Collection, err error)
- func (s *Service) CreateCollection(label string) (collection *Collection, err error)
- func (s *Service) GetCollection(name string) (c *Collection, err error)
- func (s *Service) GetSecrets(itemPaths ...dbus.ObjectPath) (secrets map[dbus.ObjectPath]*Secret, err error)
- func (s *Service) GetSession() (ssn *Session, err error)
- func (s *Service) Lock(objectPaths ...dbus.ObjectPath) (err error)
- func (s *Service) OpenSession(algo, input string) (session *Session, output dbus.Variant, err error)
- func (s *Service) ReadAlias(alias string) (collection *Collection, err error)
- func (s *Service) SearchItems(attributes map[string]string) (unlockedItems []*Item, lockedItems []*Item, err error)
- func (s *Service) SetAlias(alias string, objectPath dbus.ObjectPath) (err error)
- func (s *Service) Unlock(objectPaths ...dbus.ObjectPath) (err error)
- type ServiceInitFlag
- type ServiceSearchFlag
- type Session
Constants ¶
const ( // DbusService is the Dbus service bus identifier. DbusService string = "org.freedesktop.secrets" // DbusServiceBase is the base identifier used by interfaces. DbusServiceBase string = "org.freedesktop.Secret" // DbusPrompterInterface is an interface for issuing a Prompt. Yes, it should be doubled up like that. DbusPrompterInterface string = DbusServiceBase + ".Prompt.Prompt" /* DbusDefaultItemType is the default type to use for Item.Type/Collection.CreateItem. */ DbusDefaultItemType string = DbusServiceBase + ".Generic" )
Libsecret/SecretService Dbus interfaces.
const ( /* DbusInterfaceService is the Dbus interface for working with a Service. Found at /org/freedesktop/secrets/(DbusInterfaceService) */ DbusInterfaceService string = DbusServiceBase + ".Service" // DbusServiceCreateCollection is used to create a new Collection via Service.CreateCollection. DbusServiceCreateCollection string = DbusInterfaceService + ".CreateCollection" // DbusServiceGetSecrets is used to fetch multiple Secret values from multiple Item items in a given Collection (via Service.GetSecrets). DbusServiceGetSecrets string = DbusInterfaceService + ".GetSecrets" // DbusServiceLock is used by Service.Lock. DbusServiceLock string = DbusInterfaceService + ".Lock" // DbusServiceOpenSession is used by Service.OpenSession. DbusServiceOpenSession string = DbusInterfaceService + ".OpenSession" // DbusServiceReadAlias is used by Service.ReadAlias to return a Collection based on its aliased name. DbusServiceReadAlias string = DbusInterfaceService + ".ReadAlias" // DbusServiceSearchItems is used by Service.SearchItems to get arrays of locked and unlocked Item objects. DbusServiceSearchItems string = DbusInterfaceService + ".SearchItems" // DbusServiceSetAlias is used by Service.SetAlias to set an alias for a Collection. DbusServiceSetAlias string = DbusInterfaceService + ".SetAlias" // DbusServiceUnlock is used by Service.Unlock. DbusServiceUnlock string = DbusInterfaceService + ".Unlock" // DbusServiceCollections is used to get a Dbus array of Collection items (Service.Collections). DbusServiceCollections string = DbusInterfaceService + ".Collections" )
Service interface.
const ( /* DbusInterfaceSession is the Dbus interface for working with a Session. Found at /org/freedesktop/secrets/session/<session ID>/(DbusInterfaceSession) */ DbusInterfaceSession = DbusServiceBase + ".Session" // DbusSessionClose is used for Session.Close. DbusSessionClose string = DbusInterfaceSession + ".Close" )
Session interface.
const ( /* DbusInterfaceCollection is the Dbus interface for working with a Collection. Found at /org/freedesktop/secrets/collection/<collection name>/(DbusInterfaceCollection) */ DbusInterfaceCollection string = DbusServiceBase + ".Collection" // DbusCollectionCreateItem is used for Collection.CreateItem. DbusCollectionCreateItem string = DbusInterfaceCollection + ".CreateItem" // DbusCollectionDelete is used for Collection.Delete. DbusCollectionDelete string = DbusInterfaceCollection + ".Delete" // DbusCollectionSearchItems is used for Collection.SearchItems. DbusCollectionSearchItems string = DbusInterfaceCollection + ".SearchItems" // DbusCollectionItems is a Dbus array of Item. DbusCollectionItems string = DbusInterfaceCollection + ".Items" // DbusCollectionLocked is a Dbus boolean for Collection.Locked. DbusCollectionLocked string = DbusInterfaceCollection + ".Locked" // DbusCollectionLabel is the name (label) for Collection.Label. DbusCollectionLabel string = DbusInterfaceCollection + ".Label" // DbusCollectionCreated is the time a Collection was created (in a UNIX Epoch uint64) for Collection.Created. DbusCollectionCreated string = DbusInterfaceCollection + ".Created" // DbusCollectionModified is the time a Collection was last modified (in a UNIX Epoch uint64) for Collection.Modified. DbusCollectionModified string = DbusInterfaceCollection + ".Modified" )
Collection interface.
const ( /* DbusInterfaceItem is the Dbus interface for working with Item items. Found at /org/freedesktop/secrets/collection/<collection name>/<item index>/(DbusInterfaceItem) */ DbusInterfaceItem string = DbusServiceBase + ".Item" // DbusItemDelete is used by Item.Delete. DbusItemDelete string = DbusInterfaceItem + ".Delete" // DbusItemGetSecret is used by Item.GetSecret. DbusItemGetSecret string = DbusInterfaceItem + ".GetSecret" // DbusItemSetSecret is used by Item.SetSecret. DbusItemSetSecret string = DbusInterfaceItem + ".SetSecret" // DbusItemLocked is a Dbus boolean for Item.Locked. DbusItemLocked string = DbusInterfaceItem + ".Locked" /* DbusItemAttributes contains attributes (metadata, schema, etc.) for Item.Attributes, Item.ReplaceAttributes, and Item.ModifyAttributes. */ DbusItemAttributes string = DbusInterfaceItem + ".Attributes" // DbusItemLabel is the name (label) for Item.Label. DbusItemLabel string = DbusInterfaceItem + ".Label" // DbusItemType is the type of Item (Item.ItemType). DbusItemType string = DbusInterfaceItem + ".Type" // DbusItemCreated is the time an Item was created (in a UNIX Epoch uint64) for Item.Created. DbusItemCreated string = DbusInterfaceItem + ".Created" // DbusItemModified is the time an Item was last modified (in a UNIX Epoch uint64) for Item.Modified. DbusItemModified string = DbusInterfaceItem + ".Modified" )
Item interface.
const ( // DbusPath is the path for DbusService. DbusPath string = "/org/freedesktop/secrets" // DbusPromptPrefix is the path used for prompts comparison. DbusPromptPrefix string = DbusPath + "/prompt/" // DbusNewCollectionPath is used to create a new Collection. DbusNewCollectionPath string = DbusPath + "/collection/" // DbusNewSessionPath is used to create a new Session. DbusNewSessionPath string = DbusPath + "/session/" )
Dbus paths.
const ( /* ExplicitAttrEmptyValue is the constant used in Item.ModifyAttributes to explicitly set a value as empty. Between the surrounding with %'s, the weird name that includes "gosecret", and the UUID4... I am fairly confident this is unique enough. */ ExplicitAttrEmptyValue string = "%EXPLICIT_GOSECRET_BLANK_VALUE_8A4E3D7D-F30E-4754-8C56-9C172D1400F6%" )
Constants for use with gosecret.
Variables ¶
var ( // ErrBadDbusPath indicates an invalid path - either nothing exists at that path or the path is malformed. ErrBadDbusPath error = errors.New("invalid dbus path") // ErrInvalidProperty indicates a dbus.Variant is not the "real" type expected. ErrInvalidProperty error = errors.New("invalid variant type; cannot convert") // ErrNoDbusConn gets triggered if a connection to Dbus can't be detected. ErrNoDbusConn error = errors.New("no valid dbus connection") // ErrMissingPaths gets triggered if one or more Dbus object paths are expected but non/not enough are received. ErrMissingPaths error = errors.New("one or more Dbus object paths were expected but an insufficient amount were received") // ErrMissingAttrs gets triggered if attributes were expected but not passed. ErrMissingAttrs error = errors.New("attributes must not be empty/nil") // ErrDoesNotExist gets triggered if a Collection, Item, etc. is attempted to be fetched but none exists via the specified identifier. ErrDoesNotExist error = errors.New("the object under that name/label/alias does not exist") )
General errors.
var ( ErrUnknownSecretServiceErr error = errors.New("cannot find matching SecretService error") ErrSecretServiceProto SecretServiceError = SecretServiceError{ ErrCode: EnumErrProtocol, ErrName: "SECRET_ERROR_PROTOCOL", ErrDesc: "an invalid message or data was received from SecretService", } ErrSecretServiceLocked SecretServiceError = SecretServiceError{ ErrCode: EnumErrIsLocked, ErrName: "SECRET_ERROR_IS_LOCKED", ErrDesc: "the item/collection is locked; the specified operation cannot be performed", } ErrSecretServiceNoObj SecretServiceError = SecretServiceError{ ErrCode: EnumErrNoSuchObject, ErrName: "SECRET_ERROR_NO_SUCH_OBJECT", ErrDesc: "no such item/collection was found in SecretService", } ErrSecretServiceExists SecretServiceError = SecretServiceError{ ErrCode: EnumErrAlreadyExists, ErrName: "SECRET_ERROR_ALREADY_EXISTS", ErrDesc: "a relevant item/collection already exists", } ErrSecretServiceInvalidFormat SecretServiceError = SecretServiceError{ ErrCode: EnumErrInvalidFileFormat, ErrName: "SECRET_ERROR_INVALID_FILE_FORMAT", ErrDesc: "the file/content format is invalid", } /* AllSecretServiceErrs provides a slice of these for easier iteration when translating. TECHNICALLY, because they are indexed in the order of their enums, you could simplify and optimize translation by just doing e.g. err = AllSecretServiceErrs[EnumErrProtocol] But this should be considered UNSTABLE and UNSAFE due to it being potentially unpredictable in the future. There are only 5 errors currently, so the performance benefits would be negligible compared to iteration. If SecretService adds more errors, however, this may be more desirable. */ AllSecretServiceErrs []SecretServiceError = []SecretServiceError{ ErrSecretServiceProto, ErrSecretServiceLocked, ErrSecretServiceNoObj, ErrSecretServiceExists, ErrSecretServiceInvalidFormat, } )
Translated SecretService errors. See https://developer-old.gnome.org/libsecret/unstable/libsecret-SecretError.html#SecretError. Used by TranslateError.
Functions ¶
func NewErrors ¶ added in v1.0.0
NewErrors returns a new MultiError based on a slice of error.Error (errs). Any nil errors are trimmed. If there are no actual errors after trimming, err will be nil.
func TranslateError ¶ added in v1.0.0
func TranslateError(ssErr SecretServiceErrEnum) (ok bool, err error)
TranslateError translates a SecretServiceErrEnum into a SecretServiceError. If a matching error was found, ok will be true and err will be the matching SecretServiceError. If no matching error was found, however, then ok will be false and err will be ErrUnknownSecretServiceErr.
Types ¶
type Collection ¶
type Collection struct { *DbusObject // contains filtered or unexported fields }
Collection is an accessor for libsecret collections, which contain multiple Secret Item items. Reference: https://developer-old.gnome.org/libsecret/0.18/SecretCollection.html https://specifications.freedesktop.org/secret-service/latest/ch03.html
func NewCollection ¶
func NewCollection(service *Service, path dbus.ObjectPath) (coll *Collection, err error)
NewCollection returns a pointer to a Collection based on a Service and a Dbus path. You will almost always want to use Service.GetCollection instead.
func (*Collection) CreateItem ¶
func (c *Collection) CreateItem(label string, attrs map[string]string, secret *Secret, replace bool, itemType ...string) (item *Item, err error)
CreateItem returns a pointer to an Item based on a label, some attributes, a Secret, whether any existing secret with the same label should be replaced or not, and the optional itemType.
itemType is optional; if specified, it should be a Dbus interface (only the first element is used). If not specified, the default DbusDefaultItemType will be used. The most common itemType is DbusDefaultItemType and is the current recommendation. Other types used are:
org.gnome.keyring.NetworkPassword org.gnome.keyring.Note
These are libsecret schemas as defined at https://gitlab.gnome.org/GNOME/libsecret/-/blob/master/libsecret/secret-schemas.c (and bundled in with libsecret). Support for adding custom schemas MAY come in the future but is unsupported currently.
func (*Collection) Created ¶ added in v1.0.0
func (c *Collection) Created() (created time.Time, err error)
Created returns the time.Time of when a Collection was created.
func (*Collection) Delete ¶
func (c *Collection) Delete() (err error)
Delete removes a Collection. While *technically* not necessary, it is recommended that you iterate through Collection.Items and do an Item.Delete for each item *before* calling Collection.Delete; the item paths are cached as "orphaned paths" in Dbus otherwise if not deleted before deleting their Collection. They should clear on a reboot or restart of Dbus (but rebooting Dbus on a system in use is... troublesome).
func (*Collection) Items ¶
func (c *Collection) Items() (items []*Item, err error)
Items returns a slice of Item pointers in the Collection.
func (*Collection) Label ¶ added in v1.0.0
func (c *Collection) Label() (label string, err error)
Label returns the Collection label (name).
func (*Collection) Locked ¶
func (c *Collection) Locked() (isLocked bool, err error)
Locked indicates if a Collection is locked (true) or unlocked (false).
func (*Collection) Modified ¶ added in v1.0.0
func (c *Collection) Modified() (modified time.Time, isChanged bool, err error)
Modified returns the time.Time of when a Collection was last modified along with a boolean that indicates if the collection has changed since the last call of Collection.Modified.
Note that when calling NewCollection, the internal library-tracked modification time (Collection.lastModified) will be set to the latest modification time of the Collection itself as reported by Dbus rather than the time that NewCollection was called.
func (*Collection) PathName ¶ added in v1.0.0
func (c *Collection) PathName() (realName string)
PathName returns the "real" name of a Collection. In some cases, the Collection.Label may not be the actual *name* of the collection (i.e. the label is different from the name used in the Dbus path). This is a thin wrapper around simply extracting the last item from the Collection.Dbus.Path().
func (*Collection) Relabel ¶ added in v1.0.0
func (c *Collection) Relabel(newLabel string) (err error)
Relabel modifies the Collection's label in Dbus.
func (*Collection) SearchItems
deprecated
func (c *Collection) SearchItems(profile string) (items []*Item, err error)
SearchItems searches a Collection for a matching profile string. It's mostly a carry-over from go-libsecret, and is here for convenience. IT MAY BE REMOVED IN THE FUTURE.
I promise it's not useful for any other implementation/storage of SecretService whatsoever.
Deprecated: Use Service.SearchItems instead.
type CollectionInitFlag ¶ added in v1.0.0
type CollectionInitFlag int
CollectionInitFlag is a flag for Collection.SearchItems and Collection.Items.
const ( FlagCollectionNone CollectionInitFlag = iota FlagCollectionLoadItems )
type ConnPathCheckResult ¶ added in v1.0.0
type ConnPathCheckResult struct { // ConnOK is true if the dbus.Conn is valid. ConnOK bool `json:"conn"` // PathOK is true if the Dbus path given is a valid type and value. PathOK bool `json:"path"` }
ConnPathCheckResult contains the result of validConnPath.
type DbusObject ¶ added in v1.0.0
type DbusObject struct { // Conn is an active connection to the Dbus. Conn *dbus.Conn `json:"-"` // Dbus is the Dbus bus object. Dbus dbus.BusObject `json:"-"` }
DbusObject is a base struct type to be anonymized by other types.
type Item ¶
type Item struct { *DbusObject // Secret is the corresponding Secret object. Secret *Secret `json:"secret"` // contains filtered or unexported fields }
Item is an entry in a Collection that contains a Secret. https://developer-old.gnome.org/libsecret/0.18/SecretItem.html https://specifications.freedesktop.org/secret-service/latest/re03.html
func NewItem ¶
func NewItem(collection *Collection, path dbus.ObjectPath) (item *Item, err error)
NewItem returns a pointer to an Item based on Collection and a Dbus path.
func (*Item) Attributes ¶ added in v1.0.0
Attributes returns the Item's attributes from Dbus.
func (*Item) Created ¶ added in v1.0.0
Created returns the time.Time of when an Item was created.
func (*Item) GetSecret ¶
GetSecret returns the Secret in an Item using a Session.
func (*Item) Label ¶
Label returns the label ("name") of an Item.
func (*Item) Locked ¶
Locked indicates if an Item is locked (true) or unlocked (false).
func (*Item) Modified ¶ added in v1.0.0
Modified returns the time.Time of when an Item was last modified along with a boolean that indicates if the collection has changed since the last call of Item.Modified.
Note that when calling NewItem, the internal library-tracked modification time (Item.lastModified) will be set to the latest modification time of the Item itself as reported by Dbus rather than the time that NewItem was called.
func (*Item) ModifyAttributes ¶ added in v1.0.0
ModifyAttributes modifies the Item's attributes in Dbus. This is similar to Item.ReplaceAttributes but will only modify the map's given keys so you do not need to provide the entire attribute map. If you wish to remove an attribute, use the value "" (empty string). If you wish to explicitly provide a blank value/empty string, use the constant gosecret.ExplicitAttrEmptyValue.
This is more or less a convenience/wrapper function around Item.ReplaceAttributes.
func (*Item) Relabel ¶ added in v1.0.0
Relabel modifies the Item's label in Dbus.
func (*Item) ReplaceAttributes ¶ added in v1.0.0
ReplaceAttributes replaces the Item's attributes in Dbus.
func (*Item) SetSecret ¶ added in v1.0.0
SetSecret sets the Secret for an Item.
type ItemInitFlag ¶ added in v1.0.0
type ItemInitFlag int
ItemInitFlag are flags for Collection.SearchItems and Collection.Items.
const ( FlagItemNone ItemInitFlag = iota FlagItemLoadSecret )
type ItemSearchFlag ¶ added in v1.0.0
type ItemSearchFlag int
ItemSearchFlag are flags for Collection.CreateItem.
const ( FlagItemCreateNone ItemSearchFlag = iota FlatItemCreateReplace )
type MultiError ¶ added in v1.0.0
type MultiError struct { // Errors is a slice of errors to combine/concatenate when .Error() is called. Errors []error `json:"errors"` // ErrorSep is a string to use to separate errors for .Error(). The default is "\n". ErrorSep string `json:"separator"` }
MultiError is a type of error.Error that can contain multiple error.Errors. Confused? Don't worry about it.
func (*MultiError) Error ¶ added in v1.0.0
func (e *MultiError) Error() (errStr string)
type Prompt ¶
type Prompt struct {
*DbusObject
}
Prompt is an interface to handling unlocking prompts. https://developer-old.gnome.org/libsecret/0.18/SecretPrompt.html https://specifications.freedesktop.org/secret-service/latest/ch09.html
type Secret ¶
type Secret struct { // Session is a Dbus object path for the associated Session (the actual Session is stored in an unexported field). Session dbus.ObjectPath `json:"session_path"` /* Parameters are "algorithm dependent parameters for secret value encoding" - likely this will just be an empty byteslice. Refer to Session for more information. */ Parameters []byte `json:"params"` // Value is the secret's content in []byte format. Value SecretValue `json:"value"` // ContentType is the MIME type of Value. ContentType string `json:"content_type"` // contains filtered or unexported fields }
Secret is the "Good Stuff" - the actual secret content. https://developer-old.gnome.org/libsecret/0.18/SecretValue.html https://specifications.freedesktop.org/secret-service/latest/re03.html https://specifications.freedesktop.org/secret-service/latest/ch14.html#type-Secret
type SecretServiceErrEnum ¶ added in v1.0.0
type SecretServiceErrEnum int
SecretServiceErrEnum are just constants for the enum'd errors; see SecretServiceError type and ErrSecretService* vars for what actually gets returned. They're used for finding the appropriate matching error.
const ( EnumErrProtocol SecretServiceErrEnum = iota EnumErrIsLocked EnumErrNoSuchObject EnumErrAlreadyExists EnumErrInvalidFileFormat )
type SecretServiceError ¶ added in v1.0.0
type SecretServiceError struct { // ErrCode is the SecretService API's enum value. ErrCode SecretServiceErrEnum `json:"code"` // ErrName is the SecretService API's error name. ErrName string `json:"name"` /* ErrDesc is the actual error description/text. This is what should be displayed to users, and is returned by SecretServiceError.Error. */ ErrDesc string `json:"desc"` }
SecretServiceError is a translated error from SecretService API. See https://developer-old.gnome.org/libsecret/unstable/libsecret-SecretError.html#SecretError and ErrSecretService* errors.
func (SecretServiceError) Error ¶ added in v1.0.0
func (e SecretServiceError) Error() (errStr string)
Error returns the string format of the error; this is necessary to be considered a valid error interface.
type SecretValue ¶ added in v1.0.0
type SecretValue []byte
SecretValue is a custom type that handles JSON encoding/decoding a little more easily.
func (*SecretValue) MarshalJSON ¶ added in v1.0.0
func (s *SecretValue) MarshalJSON() (b []byte, err error)
MarshalJSON converts a SecretValue to a JSON representation. For compat reasons, the MarshalText is left "unmolested" (i.e. renders to a Base64 value). I don't bother with an UnmarshalJSON because it makes exactly 0 sense to unmarshal due to runtime and unexported fields in Secret.
type Service ¶
type Service struct { *DbusObject // Session is a default Session initiated automatically. Session *Session `json:"-"` }
Service is a general SecretService interface, sort of handler for Dbus - it's used for fetching a Session, Collections, etc. https://developer-old.gnome.org/libsecret/0.18/SecretService.html https://specifications.freedesktop.org/secret-service/latest/re01.html
func NewService ¶
NewService returns a pointer to a new Service connection.
func (*Service) Close ¶ added in v1.0.0
Close cleanly closes a Service and all its underlying connections (e.g. Service.Session).
func (*Service) Collections ¶
func (s *Service) Collections() (collections []*Collection, err error)
Collections returns a slice of Collection items accessible to this Service.
func (*Service) CreateAliasedCollection ¶ added in v1.0.0
func (s *Service) CreateAliasedCollection(label, alias string) (collection *Collection, err error)
CreateAliasedCollection creates a new Collection (keyring) via a Service with the name specified by label, aliased to the name specified by alias, and returns the new Collection.
func (*Service) CreateCollection ¶
func (s *Service) CreateCollection(label string) (collection *Collection, err error)
CreateCollection creates a new Collection (keyring) via a Service with the name specified by label and returns the new Collection. It is a *very* thin wrapper around Service.CreateAliasedCollection, but with a blank alias.
func (*Service) GetCollection ¶ added in v1.0.0
func (s *Service) GetCollection(name string) (c *Collection, err error)
GetCollection returns a single Collection based on the name (name can also be an alias). It's a helper function that avoids needing to make multiple calls in user code.
func (*Service) GetSecrets ¶ added in v1.0.0
func (s *Service) GetSecrets(itemPaths ...dbus.ObjectPath) (secrets map[dbus.ObjectPath]*Secret, err error)
GetSecrets allows you to fetch values (Secret) from multiple Item object paths using this Service's Session. An ErrMissingPaths will be returned for err if itemPaths is nil or empty. The returned secrets is a map with itemPaths as the keys and their corresponding Secret as the value.
func (*Service) GetSession ¶ added in v1.0.0
GetSession returns a single Session. It's a helper function that wraps Service.OpenSession.
func (*Service) Lock ¶
Lock locks an Unlocked Service, Collection, etc. You can usually get objectPath for the object(s) to unlock via <object>.Dbus.Path(). If objectPaths is nil or empty, the Service's own path will be used.
func (*Service) OpenSession ¶ added in v1.0.0
func (s *Service) OpenSession(algo, input string) (session *Session, output dbus.Variant, err error)
OpenSession returns a pointer to a Session from the Service. It's a convenience function around NewSession.
func (*Service) ReadAlias ¶ added in v1.0.0
func (s *Service) ReadAlias(alias string) (collection *Collection, err error)
ReadAlias allows one to fetch a Collection based on an alias name. An ErrDoesNotExist will be raised if the alias does not exist. You will almost assuredly want to use Service.GetCollection instead; it works for both alias names and real names.
func (*Service) SearchItems ¶ added in v1.0.0
func (s *Service) SearchItems(attributes map[string]string) (unlockedItems []*Item, lockedItems []*Item, err error)
SearchItems searches all Collection objects and returns all matches based on the map of attributes.
func (*Service) SetAlias ¶ added in v1.0.0
SetAlias sets an alias for an existing Collection. To remove an alias, set objectPath to dbus.ObjectPath("/").
type ServiceInitFlag ¶ added in v1.0.0
type ServiceInitFlag int
ServiceInitFlag is a flag for Service.OpenSession.
const ( FlagServiceNone ServiceInitFlag = iota FlagServiceOpenSession FlagServiceLoadCollections )
type ServiceSearchFlag ¶ added in v1.0.0
type ServiceSearchFlag int
ServiceSearchFlag is a flag for Service.SearchItems.
const ( FlagServiceSearchNone ServiceSearchFlag = iota FlagServiceSearchAll FlagServiceSearchUnlock FlagServiceSearchLoadSecrets )
type Session ¶
type Session struct { *DbusObject // contains filtered or unexported fields }
Session is a session/instance/connection to SecretService. https://developer-old.gnome.org/libsecret/0.18/SecretService.html https://specifications.freedesktop.org/secret-service/latest/ch06.html
func NewSession ¶
NewSession returns a pointer to a new Session based on a Service and a dbus.ObjectPath. You will almost always want to use Service.GetSession or Service.OpenSession instead.