gokwallet

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 28, 2021 License: MIT Imports: 6 Imported by: 2

README 

= gokwallet
Brent Saner <bts@square-r00t.net>
:doctype: book
:docinfo: shared
:data-uri:
:imagesdir: images
:sectlinks:
:sectnums:
:sectnumlevels: 7
:toc: preamble
:toc2: left
:idprefix:
:toclevels: 7
:source-highlighter: rouge

image::https://pkg.go.dev/badge/r00t2.io/gokwallet.svg[link="https://pkg.go.dev/r00t2.io/gokwallet"]

Package `gokwallet` serves as a Golang interface to KDE's https://utils.kde.org/projects/kwalletmanager/[KWallet^].

Note that to use this library, the running machine must have both Dbus and kwalletd running.

Relatedly, note also that this library interfaces with kwalletd. KWallet is in the process of moving to libsecret/SecretService
(see https://bugs.kde.org/show_bug.cgi?id=313216[here^] and https://invent.kde.org/frameworks/kwallet/-/merge_requests/11[here^]),
thus replacing kwalletd. While there is a pull request in place, it has not yet been merged in (and it may be a while before downstream distributions incorporate that version). However, when that time comes I highly recommend using my `gosecret` library to interface with that (module https://pkg.go.dev/r00t2.io/gosecret[`r00t2.io/gosecret`^]).

== KWallet Concepts

For reference, KWallet has the following structure (modified slightly to reflect this library):

* A main Dbus service interface ("org.kde.kwalletd5"), `WalletManager`, allows one to retrieve and operate on/with `Wallet` items.

* One or more `Wallet` items allow one to retrieve and operate on/with `Folder` items.

* One or more `Folder` items allow one to retrieve and operate on/with `Passwords`, `Maps`, `BinaryData`, and `UnknownItem` `WalletItem` items.

Thus, the hierarchy (as exposed by this library) looks like this:

----
WalletManager
├─ Wallet "A"
│	├─ Folder "A_1"
│	│	├─ Passwords
│	│	│	├─ Password "A_1_a"
│	│	│	└─ Password "A_1_b"
│	│	├─ Maps
│	│	│	├─ Map "A_1_a"
│	│	│	└─ Map "A_1_b"
│	│	├─ BinaryData
│	│	│	├─ Blob "A_1_a"
│	│	│	└─ Blob "A_1_b"
│	│	└─ Unknown
│	│		├─ UnknownItem "A_1_a"
│	│		└─ UnknownItem "A_1_b"
│	└─ Folder "A_2"
│		├─ Passwords
│		│	├─ Password "A_2_a"
│		│	└─ Password "A_2_b"
│		├─ Maps
│		│	├─ Map "A_2_a"
│		│	└─ Map "A_2_b"
│		├─ BinaryData
│		│	├─ Blob "A_2_a"
│		│	└─ Blob "A_2_b"
│		└─ Unknown
│			├─ UnknownItem "A_2_a"
│			└─ UnknownItem "A_2_b"
└─ Wallet "B"
    └─ Folder "B_1"
        ├─ Passwords
        │	├─ Password "B_1_a"
        │	└─ Password "B_1_b"
        ├─ Maps
        │	├─ Map "B_1_a"
        │	└─ Map "B_1_b"
        ├─ BinaryData
        │	├─ Blob "B_1_a"
        │	└─ Blob "B_1_b"
        └─ Unknown
            ├─ UnknownItem "B_1_a"
            └─ UnknownItem "B_1_b"
----

This is an approximation, but should show a relatively accurate representation of the model.
Note that most systems are likely to only have a single wallet, "kdewallet".

== Usage

Full documentation can be found via inline documentation.
Additionally, use either https://pkg.go.dev/r00t2.io/gokwallet or https://pkg.go.dev/golang.org/x/tools/cmd/godoc (or `go doc`) in the source root.

You most likely do *not* want to call any New<object> function directly;
NewWalletManager with its RecurseOpts parameter (`recursion`) should get you everything you want/need.

Here's a quick demonstration:

[source,go]
----
package main

import (
	`fmt`
	`log`

	`r00t2.io/gokwallet`
)

func main() {

	var err error
	var r *gokwallet.RecurseOpts
	var wm *gokwallet.WalletManager
	var w *gokwallet.Wallet
	var f *gokwallet.Folder
	var p *gokwallet.Password

	r = gokwallet.DefaultRecurseOpts
	r.AllWalletItems = true

	if wm, err = gokwallet.NewWalletManager(r, "ExampleKWalletApplication"); err != nil {
		log.Panicln(err)
	}

	w = wm.Wallets["kdewallet"]

	f = w.Folders["Passwords"]

	if p, err = f.WritePassword("test_password", "this is a test password"); err != nil {
		log.Panicln(err)
	}

	fmt.Println(p.Value)
}
----

Documentation

Overview

Package gokwallet serves as a Golang interface to KDE's KWallet (https://utils.kde.org/projects/kwalletmanager/).

Note that to use this library, the running machine must have both Dbus and kwalletd running.

Relatedly, note also that this library interfaces with kwalletd. KWallet is in the process of moving to libsecret/SecretService (see https://bugs.kde.org/show_bug.cgi?id=313216 and https://invent.kde.org/frameworks/kwallet/-/merge_requests/11), thus replacing kwalletd. While there is a pull request in place, it has not yet been merged in (and it may be a while before downstream distributions incorporate that version). However, when that time comes I highly recommend using my `gosecret` library to interface with that (module r00t2.io/gosecret; see https://pkg.go.dev/r00t2.io/gosecret).

KWallet Concepts

KWallet has the following structure (modified slightly to reflect this library):

- A main Dbus service interface ("org.kde.kwalletd5"), WalletManager, allows one to retrieve and operate on/with Wallet items.

- One or more Wallet items allow one to retrieve and operate on/with Folder items.

- One or more Folder items allow one to retrieve and operate on/with Passwords, Maps, BinaryData, and Unknown WalletItem items.

Thus, the hierarchy (as exposed by this library) looks like this: 

WalletManager
├─ Wallet "A"
│	├─ Folder "A_1"
│	│	├─ Passwords
│	│	│	├─ Password "A_1_a"
│	│	│	└─ Password "A_1_b"
│	│	├─ Maps
│	│	│	├─ Map "A_1_a"
│	│	│	└─ Map "A_1_b"
│	│	├─ BinaryData
│	│	│	├─ Blob "A_1_a"
│	│	│	└─ Blob "A_1_b"
│	│	└─ Unknown
│	│		├─ UnknownItem "A_1_a"
│	│		└─ UnknownItem "A_1_b"
│	└─ Folder "A_2"
│		├─ Passwords
│		│	├─ Password "A_2_a"
│		│	└─ Password "A_2_b"
│		├─ Maps
│		│	├─ Map "A_2_a"
│		│	└─ Map "A_2_b"
│		├─ BinaryData
│		│	├─ Blob "A_2_a"
│		│	└─ Blob "A_2_b"
│		└─ Unknown
│			├─ UnknownItem "A_2_a"
│			└─ UnknownItem "A_2_b"
└─ Wallet "B"
	└─ Folder "B_1"
		├─ Passwords
		│	├─ Password "B_1_a"
		│	└─ Password "B_1_b"
		├─ Maps
		│	├─ Map "B_1_a"
		│	└─ Map "B_1_b"
		├─ BinaryData
		│	├─ Blob "B_1_a"
		│	└─ Blob "B_1_b"
		└─ Unknown
			├─ UnknownItem "B_1_a"
			└─ UnknownItem "B_1_b"

This is an approximation, but should show a relatively accurate representation of the model. Note that most systems are likely to only have a single wallet, "kdewallet".

Usage

Full documentation can be found via inline documentation. Additionally, use either https://pkg.go.dev/r00t2.io/gokwallet or https://pkg.go.dev/golang.org/x/tools/cmd/godoc (or `go doc`) in the source root.

You most likely do *not* want to call any New<object> function directly; NewWalletManager with its RecurseOpts parameter (`recursion`) should get you everything you want/need.

Here's a quick demonstration: 

package main

import (
	`fmt`
	`log`

	`r00t2.io/gokwallet`
)

func main() {

	var err error
	var r *gokwallet.RecurseOpts
	var wm *gokwallet.WalletManager
	var w *gokwallet.Wallet
	var f *gokwallet.Folder
	var p *gokwallet.Password

	r = gokwallet.DefaultRecurseOpts
	r.AllWalletItems = true

	if wm, err = gokwallet.NewWalletManager(r, "ExampleKWalletApplication"); err != nil {
		log.Panicln(err)
	}

	w = wm.Wallets["kdewallet"]

	f = w.Folders["Passwords"]

	if p, err = f.WritePassword("test_password", "this is a test password"); err != nil {
		log.Panicln(err)
	}

	fmt.Println(p.Value)
}

Index

Constants

View Source 
const (
	DbusSuccess int32 = 0
	DbusFailure int32 = 1
)

KwalletD Dbus returns.

View Source 
const (
	KwalletdEnumTypeUnknown  kwalletdEnumType = iota // UnknownItem (0)
	KwalletdEnumTypePassword                         // Password (1)
	KwalletdEnumTypeStream                           // Blob (2)
	KwalletdEnumTypeMap                              // Map (3)
	KwalletdEnumTypeUnused   = 0xffff                // 65535
)

KwalletD Dbus enums for WalletItem types.

View Source 
const (
	// DbusService is the Dbus service bus identifier.
	DbusService string = "org.kde.kwalletd5"
	// DbusServiceBase is the base identifier used by interfaces.
	DbusServiceBase string = "org.kde"
)

KWalletD Dbus interfaces.

View Source 
const (
	// DefaultWalletName is the name of the default Wallet to use.
	DefaultWalletName string = "kdewallet"
	// DefaultAppID is the default name for the application (see WalletManager.AppID).
	DefaultAppID string = "GoKwallet"
	// DefaultWindowID is 0; we aren't guaranteed to have a window, so we pass 0 (per upstream headers' comments).
	DefaultWindowID int64 = 0
)

gokwallet defaults.

View Source 
const (
	/*
		DbusInterfaceWM is the Dbus interface for working with a WalletManager.
	*/
	DbusInterfaceWM string = DbusServiceBase + ".KWallet"

	// DbusWMChangePassword changes the password for a Wallet.
	DbusWMChangePassword string = DbusInterfaceWM + ".changePassword"

	// DbusWMClose closes an App (WalletManager) or Wallet.
	DbusWMClose string = DbusInterfaceWM + ".close"

	// DbusWMCloseAllWallets closes all WalletManager.Wallets.
	DbusWMCloseAllWallets string = DbusInterfaceWM + ".closeAllWallets"

	// DbusWMCreateFolder creates a Folder.
	DbusWMCreateFolder string = DbusInterfaceWM + ".createFolder"

	// DbusWMDeleteWallet deletes/removes a Wallet.
	DbusWMDeleteWallet string = DbusInterfaceWM + ".deleteWallet"

	// DbusWMDisconnectApp disconnects a WalletManager (or other App).
	DbusWMDisconnectApp string = DbusInterfaceWM + ".disconnectApplication"

	// DbusWMEntriesList returns a *map* of the WalletItem objects in a Folder (with their entry name as the map key).
	DbusWMEntriesList string = DbusInterfaceWM + ".entriesList"

	// DbusWMEntryList returns a *slice* of WalletItem names in a Folder.
	DbusWMEntryList string = DbusInterfaceWM + ".entryList"

	// DbusWMEntryType returns the type of a WalletItem.
	DbusWMEntryType string = DbusInterfaceWM + ".entryType"

	// DbusWMFolderNotExist indicates if a Folder exists within a Wallet or not.
	DbusWMFolderNotExist string = DbusInterfaceWM + ".folderDoesNotExist"

	// DbusWMFolderList lists the Folder objects (as Folder.Name) in a Wallet.
	DbusWMFolderList string = DbusInterfaceWM + ".folderList"

	// DbusWMHasEntry indicates if a Folder has a WalletItem or not.
	DbusWMHasEntry string = DbusInterfaceWM + ".hasEntry"

	// DbusWMHasFolder indicates if a Wallet has a Folder or not.
	DbusWMHasFolder string = DbusInterfaceWM + ".hasFolder"

	/*
		DbusWMIsEnabled indicates if KWallet is enabled.
		TODO: Is this accurate?
	*/
	DbusWMIsEnabled string = DbusInterfaceWM + ".isEnabled"

	// DbusWMIsOpen indicates if a Wallet is open (unlocked).
	DbusWMIsOpen string = DbusInterfaceWM + ".isOpen"

	// DbusWMKeyNotExist indicates if a Folder has a WalletItem or not.
	DbusWMKeyNotExist string = DbusInterfaceWM + ".keyDoesNotExist"

	// DbusWMLocalWallet gives the name of the local (default?) Wallet.
	DbusWMLocalWallet string = DbusInterfaceWM + ".localWallet"

	// DbusWMMapList gives a list of Map names in a Folder.
	DbusWMMapList string = DbusInterfaceWM + ".mapList"

	/*
		DbusWMNetWallet indicates if a Wallet is a Network Wallet or not.
		TODO: is/was this ever used?
	*/
	DbusWMNetWallet string = DbusInterfaceWM + ".networkWallet"

	// DbusWMOpen opens (unlocks) a Wallet.
	DbusWMOpen string = DbusInterfaceWM + ".open"

	// DbusWMOpenAsync opens (unlocks) a Wallet asynchronously.
	DbusWMOpenAsync string = DbusInterfaceWM + ".openAsync"

	// DbusWMOpenPath opens a Wallet by its filepath.
	DbusWMOpenPath string = DbusInterfaceWM + ".openPath"

	// DbusWMOpenPathAsync opens a Wallet by its filepath asynchronously.
	DbusWMOpenPathAsync string = DbusInterfaceWM + ".openPath"

	// DbusWMPamOpen opens (unlocks) a Wallet via PAM.
	DbusWMPamOpen string = DbusInterfaceWM + ".pamOpen"

	/*
		DbusWMPasswordList returns a map of Password objects in a Folder.
		Password.Name is the map key.
	*/
	DbusWMPasswordList string = DbusInterfaceWM + ".passwordList"

	// DbusWMReadEntry fetches a WalletItem by its name from a Folder (as a byteslice).
	DbusWMReadEntry string = DbusInterfaceWM + ".readEntry"

	// DbusWMReadMap returns a Map from a Folder (as a byteslice).
	DbusWMReadMap string = DbusInterfaceWM + ".readMap"

	// DbusWMReadPassword returns a Password from a Folder (as a byteslice).
	DbusWMReadPassword string = DbusInterfaceWM + ".readPassword"

	// DbusWMRemoveEntry removes a WalletItem from a Folder.
	DbusWMRemoveEntry string = DbusInterfaceWM + ".removeEntry"

	// DbusWMRemoveFolder removes a Folder from a Wallet.
	DbusWMRemoveFolder string = DbusInterfaceWM + ".removeFolder"

	// DbusWMRenameEntry renames ("moves") a WalletItem.
	DbusWMRenameEntry string = DbusInterfaceWM + ".renameEntry"

	// DbusWMUsers returns a slice of users.
	DbusWMUsers string = DbusInterfaceWM + ".users"

	// DbusWMWallets returns an array of Wallet names.
	DbusWMWallets string = DbusInterfaceWM + ".wallets"

	// DbusWMWriteEntry writes (creates) a WalletItem to/in a Folder.
	DbusWMWriteEntry string = DbusInterfaceWM + ".writeEntry"

	// DbusWMWriteMap writes (creates) a Map (via a byteslice) to/in a Folder.
	DbusWMWriteMap string = DbusInterfaceWM + ".writeMap"

	// DbusWMWritePassword writes (creates) a Password to/in a Folder.
	DbusWMWritePassword string = DbusInterfaceWM + ".writePassword"
)

WalletManager interface.

View Source 
const (
	// DbusPath is the path for DbusService.
	DbusPath string = "/modules/kwalletd5"
)

Dbus paths.

Variables

View Source 
var (
	/*
		ErrNotInitialized will be triggered if attempting to interact with an object that has not been properly initialized.
		Notably, in most/all cases this means that it was not created via a New<object> func (for instance,
		this would lead to a Wallet missing a handler).
		It is intended as a safety check (so that you don't accidentally delete a wallet with e.g. a handler of 0 when
		trying to delete a different wallet).
		It's mostly a placeholder for more specific errors.
	*/
	ErrNotInitialized error = errors.New("object not properly initialized")
	/*
		ErrOperationFailed is a generic failure message that will occur of a Dbus operation returns non-success.
		It is a placeholder for more specific messages.
	*/
	ErrOperationFailed error = errors.New("a Dbus operation has failed to execute successfully")
	/*
		ErrNoCreate is triggered if attempting to create an item (Folder, Password, etc.) but it fails.
		It is a placeholder for more specific messages.
	*/
	ErrNoCreate error = errors.New("failed to create an object")
	// ErrNoDisconnect can occur if trying to disconnect a Wallet from a WalletManager/application and a failure occurs.
	ErrNoDisconnect error = errors.New("failed to disconnect wallet from application")
	// ErrInvalidMap will get triggered if a populated map[string]string (even an empty one) is expected but a nil is received.
	ErrInvalidMap error = errors.New("invalid map; cannot be nil")
)
View Source 
var (
	// ErrDbusOpfailNoHandle returns when attempting to open a Wallet and assign to Wallet.handle but received a nil handle.
	ErrDbusOpfailNoHandle error = errors.New("a wallet handler request returned nil")
	// ErrDbusOpfailRemoveFolder occurs when attempting to delete/remove a Folder from a Wallet but it did not complete successfully.
	ErrDbusOpfailRemoveFolder error = errors.New("failed to remove/delete a Folder from a Wallet")
)

Dbus Operation failures.

View Source 
var (
	// ErrInitWM occurs if a WalletManager is not initialized properly.
	ErrInitWM error = errors.New("a WalletManager was not properly initialized")
	// ErrInitWallet occurs if a Wallet is not initialized properly.
	ErrInitWallet error = errors.New("a Wallet was not properly initialized")
	// ErrInitFolder occurs if a Folder is not initialized properly.
	ErrInitFolder error = errors.New("a Folder was not properly initialized")
	// ErrInitBlob occurs if a Blob is not initialized properly.
	ErrInitBlob error = errors.New("a Blob was not properly initialized")
	// ErrInitMap occurs if a Map is not initialized properly.
	ErrInitMap error = errors.New("a Map was not properly initialized")
	// ErrInitPassword occurs if a Password is not initialized properly.
	ErrInitPassword error = errors.New("a Password was not properly initialized")
	// ErrInitUnknownItem occurs if an UnknownItem is not initialized properly.
	ErrInitUnknownItem error = errors.New("an UnknownItem was not properly initialized")
)

Initialization errors. They are more "detailed" ErrNotInitialized errors.

Functions

func NewErrors 

func NewErrors(errs ...error) (err error)

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.

Types

type Blob 

type Blob struct {
	*DbusObject
	// Name is the name of this Blob.
	Name string `json:"name"`
	// Value is this Blob's value.
	Value []byte `json:"value"`
	// Recurse contains the relevant RecurseOpts.
	Recurse *RecurseOpts `json:"recurse_opts"`
	// contains filtered or unexported fields
}

Blob (binary large object, typographically BLOB) is secret binary data.

func NewBlob 

func NewBlob(f *Folder, keyName string, recursion *RecurseOpts) (blob *Blob, err error)

NewBlob returns a Blob. It requires a RecurseOpts (you can use DefaultRecurseOpts, call NewRecurseOpts, or provide your own RecurseOpts struct). It also requires a Folder.

func (*Blob) Delete 

func (b *Blob) Delete() (err error)

Delete will delete this Blob from its parent Folder. You may want to run Folder.UpdateBlobs to update the existing map of Blob items.

func (*Blob) Exists 

func (b *Blob) Exists() (exists bool, err error)

Exists returns true if this Blob actually exists.

func (*Blob) Rename 

func (b *Blob) Rename(newName string) (err error)

Rename renames this Blob (changes its key).

func (*Blob) SetValue 

func (b *Blob) SetValue(newValue []byte) (err error)

SetValue will replace this Blob's Blob.Value.

func (*Blob) Update 

func (b *Blob) Update() (err error)

Update fetches a Blob's Blob.Value.

type ConnPathCheckResult 

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 

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 Folder 

type Folder struct {
	*DbusObject
	// Name is the name of this Folder.
	Name string `json:"name"`
	/*
		Passwords contains a map of all Password objects in this Folder.
		Password.Name is the map key.
	*/
	Passwords map[string]*Password `json:"passwords"`
	/*
		Maps contains a map of all Map objects in this Folder.
		Map.Name is the map key.
	*/
	Maps map[string]*Map `json:"maps"`
	/*
		BinaryData contains a map if all Blob objects in this Folder.
		Blob.Name is the map key.
	*/
	BinaryData map[string]*Blob `json:"binary_data"`
	/*
		Unknown contains a map of all UnknownItem objects in this Folder.
		Unknown.Name is the map key.
	*/
	Unknown map[string]*UnknownItem `json:"unknown"`
	// Recurse contains the relevant RecurseOpts.
	Recurse *RecurseOpts `json:"recurse_opts"`
	// contains filtered or unexported fields
}

Folder contains secret object collections of Password, Map, Blob, and UnknownItem objects.

func NewFolder 

func NewFolder(w *Wallet, name string, recursion *RecurseOpts) (folder *Folder, err error)

NewFolder returns a Folder. It requires a RecurseOpts (you can use DefaultRecurseOpts, call NewRecurseOpts, or provide your own RecurseOpts struct). It also requires a Wallet.

func (*Folder) Delete 

func (f *Folder) Delete() (err error)

Delete will delete this Folder, and all its WalletItems, from the parent Wallet. You may want to run Wallet.Update upon completion to update the Wallet.Folders cache if you're using it.

func (*Folder) HasEntry 

func (f *Folder) HasEntry(entryName string) (hasEntry bool, err error)

HasEntry specifies if a Folder has an entry (WalletItem item) by the give entryName.

func (*Folder) KeyNotExist 

func (f *Folder) KeyNotExist(entryName string) (doesNotExist bool, err error)

KeyNotExist returns true if a key/entry name entryName does *not* exist. Essentially the same as Folder.HasEntry, but whereas Folder.HasEntry requires the parent wallet to be open/unlocked, Folder.KeyNotExist does not require this. However, it's prone to somewhat unreliable results; it's best to use Folder.HasEntry wherever/whenever possible.

func (*Folder) ListEntries 

func (f *Folder) ListEntries() (entryNames []string, err error)

ListEntries lists all entries (WalletItem items) in a Folder (regardless of type) by name.

func (*Folder) RemoveEntry 

func (f *Folder) RemoveEntry(entryName string) (err error)

RemoveEntry removes a WalletItem from a Folder given its entryName (key).

func (*Folder) RenameEntry 

func (f *Folder) RenameEntry(entryName, newEntryName string) (err error)

RenameEntry renames a WalletItem in a Folder from entryName to newEntryName.

func (*Folder) Update 

func (f *Folder) Update() (err error)

Update runs all of the configured Update[type] methods for a Folder, depending on Folder.Recurse configuration.

func (*Folder) UpdateBlobs 

func (f *Folder) UpdateBlobs() (err error)

UpdateBlobs updates (populates) a Folder's Folder.BinaryData.

func (*Folder) UpdateMaps 

func (f *Folder) UpdateMaps() (err error)

UpdateMaps updates (populates) a Folder's Folder.Maps.

func (*Folder) UpdatePasswords 

func (f *Folder) UpdatePasswords() (err error)

UpdatePasswords updates (populates) a Folder's Folder.Passwords.

func (*Folder) UpdateUnknowns 

func (f *Folder) UpdateUnknowns() (err error)

UpdateUnknowns updates (populates) a Folder's Folder.Unknown.

func (*Folder) WriteBlob 

func (f *Folder) WriteBlob(entryName string, entryValue []byte) (b *Blob, err error)

WriteBlob adds or replaces a Blob to/in a Folder.

func (*Folder) WriteEntry 

func (f *Folder) WriteEntry(entryName string, entryType kwalletdEnumType, entryValue []byte) (err error)

WriteEntry is used for adding/replacing a WalletItem as a general interface. If possible, you'll want to use a item-type-specific method (e.g. Folder.WritePassword) as this one is a little unwieldy to use. entryType must be the relevant KwalletdEnumType* constant (do not use KwalletdEnumTypeUnused).

func (*Folder) WriteMap 

func (f *Folder) WriteMap(entryName string, entryValue map[string]string) (m *Map, err error)

WriteMap adds or replaces a Map to/in a Folder.

func (*Folder) WritePassword 

func (f *Folder) WritePassword(entryName, entryValue string) (p *Password, err error)

WritePassword adds or replaces a Password to/in a Folder.

func (*Folder) WriteUnknown 

func (f *Folder) WriteUnknown(entryName string, entryValue []byte) (u *UnknownItem, err error)

WriteUnknown adds or replaces an UnknownItem to/in a Folder.

type Map 

type Map struct {
	*DbusObject
	// Name is the name of this Map.
	Name string `json:"name"`
	// Value is this Map's value.
	Value map[string]string `json:"value"`
	// Recurse contains the relevant RecurseOpts.
	Recurse *RecurseOpts `json:"recurse_opts"`
	// contains filtered or unexported fields
}

Map is a dictionary or key/value secret.

func NewMap 

func NewMap(f *Folder, keyName string, recursion *RecurseOpts) (m *Map, err error)

NewMap returns a Map. It requires a RecurseOpts (you can use DefaultRecurseOpts, call NewRecurseOpts, or provide your own RecurseOpts struct). It also requires a Folder.

func (*Map) Delete 

func (m *Map) Delete() (err error)

Delete will delete this Map from its parent Folder. You may want to run Folder.UpdateMaps to update the existing map of Map items.

func (*Map) Exists 

func (m *Map) Exists() (exists bool, err error)

Exists returns true if this Map actually exists.

func (*Map) Rename 

func (m *Map) Rename(newName string) (err error)

Rename renames this Map (changes its key).

func (*Map) SetValue 

func (m *Map) SetValue(newValue map[string]string) (err error)

SetValue will replace this Map's Map.Value.

func (*Map) Update 

func (m *Map) Update() (err error)

Update fetches a Map's Map.Value.

type MultiError 

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 

func (e *MultiError) Error() (errStr string)

Error returns a string representation of a MultiError (to conform with the error interface).

type Password 

type Password struct {
	*DbusObject
	// Name is the name of this Password.
	Name string `json:"name"`
	// Value is this Password's value.
	Value string `json:"value"`
	// Recurse contains the relevant RecurseOpts.
	Recurse *RecurseOpts `json:"recurse_opts"`
	// contains filtered or unexported fields
}

Password is a straightforward single-value secret of text.

func NewPassword 

func NewPassword(f *Folder, keyName string, recursion *RecurseOpts) (password *Password, err error)

NewPassword returns a Password. It requires a RecurseOpts (you can use DefaultRecurseOpts, call NewRecurseOpts, or provide your own RecurseOpts struct). It also requires a Folder.

func (*Password) Delete 

func (p *Password) Delete() (err error)

Delete will delete this Password from its parent Folder. You may want to run Folder.UpdatePasswords to update the existing map of Password items.

func (*Password) Exists 

func (p *Password) Exists() (exists bool, err error)

Exists returns true if this Password actually exists.

func (*Password) Rename 

func (p *Password) Rename(newName string) (err error)

Rename renames this Password (changes its key).

func (*Password) SetValue 

func (p *Password) SetValue(newValue string) (err error)

SetValue will replace this Password's Password.Value.

func (*Password) Update 

func (p *Password) Update() (err error)

Update fetches a Password's Password.Value.

type RecurseOpts 

type RecurseOpts struct {
	/*
		All, if true, specifies that all possible recursions should be done.
		If true, it takes precedent over all over RecurseOpts fields (with the exception of RecurseOpts.AllWalletItems).

		Performed in/from:
		WalletManager
		Wallet
		Folder
		(WalletItem)
	*/
	All bool `json:"none"`
	/*
		Wallets, if true, indicates that Wallet objects should have Wallet.Update called.

		Performed in/from: WalletManager
	*/
	Wallets bool `json:"wallet"`
	/*
		Folders, if true, indicates that Folder objects should have Folder.Update called.

		Performed in/from:
		Wallet

		May be performed in/from (depending on other fields):
		WalletManager
	*/
	Folders bool `json:"folder"`
	/*
		AllWalletItems, if true, indicates that all WalletItem entries should have (WalletItem).Update() called.
		If true, it takes precedent over all over relevant RecurseOpts fields for each WalletItem type
		(i.e. RecurseOpts.Passwords, RecurseOpts.Maps, RecurseOpts.Blobs, RecurseOpts.UnknownItems).

		Performed in/from:
		Folder

		May be performed in/from (depending on other fields):
		WalletManager
		Wallet
	*/
	AllWalletItems bool `json:"wallet_item"`
	/*
		Passwords, if true, indicates that Password objects should have Password.Update() called.

		Performed in/from:
		Folder

		May be performed in/from (depending on other fields):
		WalletManager
		Wallet
	*/
	Passwords bool `json:"password"`
	/*
		Maps, if true, indicates that Map objects should have Map.Update() called.

		Performed in/from:
		Folder

		May be performed in/from (depending on other fields):
		WalletManager
		Wallet
	*/
	Maps bool `json:"map"`
	/*
		Blobs, if true, indicates that Blob objects should have Blob.Update() called.

		Performed in/from:
		Folder

		May be performed in/from (depending on other fields):
		WalletManager
		Wallet
	*/
	Blobs bool `json:"blob"`
	/*
		UnknownItems indicates that UnknownItem objects should have UnknownItem.Update() called.

		Performed in/from:
		Folder

		May be performed in/from (depending on other fields):
		WalletManager
		Wallet
	*/
	UnknownItems bool `json:"unknown_item"`
}

RecurseOpts controls whether recursion should be done on objects when fetching them. E.g. if fetching a WalletManager (via NewWalletManager) and RecurseOpts.Wallet is true, then WalletManager.Wallets will be populated with Wallet objects. 

var (
	DefaultRecurseOpts *RecurseOpts = &RecurseOpts{
		All:            false,
		Wallets:        true,
		Folders:        true,
		AllWalletItems: false,
		Passwords:      false,
		Maps:           false,
		Blobs:          false,
		UnknownItems:   false,
	}
)

func NewRecurseOpts 

func NewRecurseOpts(recurseAll, wallets, folders, recurseAllWalletItems, passwords, maps, blobs, unknownItems bool) (opts *RecurseOpts, warn error)

NewRecurseOpts returns a RecurseOpts based on the specified options. See the documentation for RecurseOpts for descriptions of the behaviour for each recursion option. warn is a MultiError but should be treated as warnings rather than strictly errors.

type UnknownItem 

type UnknownItem struct {
	*DbusObject
	// Name is the name of this UnknownItem.
	Name string `json:"name"`
	// Value is the Dbus path of this UnknownItem.
	Value []byte `json:"value"`
	// Recurse contains the relevant RecurseOpts.
	Recurse *RecurseOpts `json:"recurse_opts"`
	// contains filtered or unexported fields
}

UnknownItem is a secret item of unknown classification, so there isn't exactly a good way of determining a type for UnknownItem.Value. As such, its UnknownItem.Value is just raw bytes.

func NewUnknownItem 

func NewUnknownItem(f *Folder, keyName string, recursion *RecurseOpts) (unknown *UnknownItem, err error)

NewUnknownItem returns an UnknownItem. It requires a RecurseOpts (you can use DefaultRecurseOpts, call NewRecurseOpts, or provide your own RecurseOpts struct). It also requires a Folder.

func (*UnknownItem) Delete 

func (u *UnknownItem) Delete() (err error)

Delete will delete this UnknownItem from its parent Folder. You may want to run Folder.UpdateUnknowns to update the existing map of UnknownItem items.

func (*UnknownItem) Exists 

func (u *UnknownItem) Exists() (exists bool, err error)

Exists returns true if this UnknownItem actually exists.

func (*UnknownItem) Rename 

func (u *UnknownItem) Rename(newName string) (err error)

Rename renames this UnknownItem (changes its key).

func (*UnknownItem) SetValue 

func (u *UnknownItem) SetValue(newValue []byte) (err error)

SetValue will replace this UnknownItem's UnknownItem.Value.

func (*UnknownItem) Update 

func (u *UnknownItem) Update() (err error)

Update fetches an UnknownItem's UnknownItem.Value.

type Wallet 

type Wallet struct {
	*DbusObject
	// Name is the name of this Wallet.
	Name string `json:"name"`
	/*
		Folders contains all Folder objects in this Wallet.
		Folder.Name is the map key.
	*/
	Folders map[string]*Folder `json:"folders"`
	// Recurse contains the relevant RecurseOpts.
	Recurse *RecurseOpts `json:"recurse_opts"`
	// IsUnlocked specifies if this Wallet is open ("unlocked") or not.
	IsUnlocked bool `json:"open"`
	/*
		FilePath is:
		- empty if this is an internal Wallet, or
		- the filepath to the wallet file if this is an on-disk wallet (either .kwl or .xml)
	*/
	FilePath string `json:"wallet_file"`
	// contains filtered or unexported fields
}

Wallet contains one or more (or none) Folder objects.

func NewWallet 

func NewWallet(wm *WalletManager, name string, recursion *RecurseOpts) (wallet *Wallet, err error)

NewWallet returns a Wallet. It requires a RecurseOpts (you can use DefaultRecurseOpts, call NewRecurseOpts, or provide your own RecurseOpts struct). It also requires a WalletManager and wallet name.

func (*Wallet) ChangePassword 

func (w *Wallet) ChangePassword() (err error)

ChangePassword will change (or set) the password for a Wallet. Note that this *must* be done via the windowing/graphical layer. There is no way to change a Wallet's password via the Dbus API.

func (*Wallet) Close 

func (w *Wallet) Close() (err error)

Close closes a Wallet.

func (*Wallet) Connections 

func (w *Wallet) Connections() (connList []string, err error)

Connections lists the application names for connections to ("users of") this Wallet.

func (*Wallet) CreateFolder 

func (w *Wallet) CreateFolder(name string) (err error)

CreateFolder creates a new Folder in a Wallet. If you need a Folder object, use NewFolder instead.

func (*Wallet) Delete 

func (w *Wallet) Delete() (err error)

Delete deletes a Wallet.

func (*Wallet) Disconnect 

func (w *Wallet) Disconnect() (err error)

Disconnect disconnects this Wallet from its parent WalletManager. You may need to run WalletManager.Update after this to clear the WalletManager cache.

func (*Wallet) DisconnectApplication 

func (w *Wallet) DisconnectApplication(appName string) (err error)

DisconnectApplication disconnects this Wallet from a specified WalletManager/application (see Wallet.Connections).

func (*Wallet) FolderExists 

func (w *Wallet) FolderExists(folderName string) (exists bool, err error)

FolderExists indicates if a Folder exists in a Wallet or not. Similar to Wallet.HasFolder but does not need the Wallet to be opened/unlocked.

func (*Wallet) ForceClose 

func (w *Wallet) ForceClose() (err error)

ForceClose is like Close but will still close a Wallet even if currently in use by the WalletManager. (Despite the insinuation by the name, this should be a relatively safe operation).

func (*Wallet) HasFolder 

func (w *Wallet) HasFolder(folderName string) (hasFolder bool, err error)

HasFolder indicates if a Wallet has a Folder in it named folderName.

func (*Wallet) IsOpen 

func (w *Wallet) IsOpen() (isOpen bool, err error)

IsOpen returns whether a Wallet is open ("unlocked") or not (as well as updates Wallet.IsOpen).

func (*Wallet) ListFolders 

func (w *Wallet) ListFolders() (folderList []string, err error)

ListFolders lists all Folder names in a Wallet.

func (*Wallet) Open 

func (w *Wallet) Open() (err error)

Open will open ("unlock") a Wallet. It will no-op if the Wallet is already open.

func (*Wallet) RemoveFolder 

func (w *Wallet) RemoveFolder(folderName string) (err error)

RemoveFolder removes a Folder folderName from a Wallet. Note that this will also remove all WalletItems in the given Folder.

func (*Wallet) Update 

func (w *Wallet) Update() (err error)

Update fetches/updates all Folder objects in a Wallet.

type WalletItem 

type WalletItem interface {
	// contains filtered or unexported methods
}

WalletItem is an interface to manage wallet objects: Password, Map, Blob, or UnknownItem.

type WalletManager 

type WalletManager struct {
	*DbusObject
	/*
		AppID is the application ID.
		The default is DefaultAppID.
	*/
	AppID string `json:"app_id"`
	/*
		Wallets is the collection of Wallets accessible in/to this WalletManager.
		Wallet.Name is the map key.
		(TODO: When wallet file support is added, the *filename* will be the map key.
			   This is to mitigate namespace conflicts between Dbus and file wallets.)
	*/
	Wallets map[string]*Wallet `json:"wallets"`
	// Recurse contains the relevant RecurseOpts.
	Recurse *RecurseOpts `json:"recurse_opts"`
	// Enabled is true if KWalletD is enabled/running.
	Enabled bool `json:"enabled"`
	// Local is the "local" wallet.
	Local *Wallet `json:"local_wallet"`
	// Network is the "network" wallet.
	Network *Wallet `json:"network_wallet"`
	// contains filtered or unexported fields
}

WalletManager is a general KWallet interface, sort of a handler for Dbus. It's used for fetching Wallet objects.

func NewWalletManager 

func NewWalletManager(recursion *RecurseOpts, appID ...string) (wm *WalletManager, err error)

NewWalletManager returns a WalletManager. It requires a RecurseOpts (you can use DefaultRecurseOpts, call NewRecurseOpts, or provide your own RecurseOpts struct). If appId is empty/nil, DefaultAppID will be used as the app ID. If appId is specified, only the first string is used.

func (*WalletManager) Close 

func (wm *WalletManager) Close() (err error)

Close closes the Dbus connection. This does NOT close wallets; use WalletManager.CloseWallet, WalletManager.ForceCloseWallet, or WalletManager.CloseAllWallets instead for that.

func (*WalletManager) CloseAllWallets 

func (wm *WalletManager) CloseAllWallets() (err error)

CloseAllWallets closes all Wallet objects. They do *not* need to be part of WalletManager.Wallets. "All wallets" really means *all* wallets.

func (*WalletManager) CloseWallet 

func (wm *WalletManager) CloseWallet(walletName string) (err error)

CloseWallet closes a Wallet. Unlike Wallet.Close, this closes access for ALL applications/WalletManagers for the specified Wallet - not just this WalletManager.

func (*WalletManager) ForceCloseWallet 

func (wm *WalletManager) ForceCloseWallet(walletName string) (err error)

ForceCloseWallet is like WalletManager.CloseWallet but will still close a Wallet even if currently in use. Unlike Wallet.ForceClose, this closes access for ALL applications/WalletManagers for the specified Wallet - not just this WalletManager.

func (*WalletManager) IsEnabled 

func (wm *WalletManager) IsEnabled() (enabled bool, err error)

IsEnabled returns whether KWallet is enabled or not (and also updates WalletManager.Enabled).

func (*WalletManager) LocalWallet 

func (wm *WalletManager) LocalWallet() (w *Wallet, err error)

LocalWallet returns the "local" wallet (and updates WalletManager.Local).

func (*WalletManager) NetworkWallet 

func (wm *WalletManager) NetworkWallet() (w *Wallet, err error)

NetworkWallet returns the "network" wallet (and updates WalletManager.Network).

func (*WalletManager) Update 

func (wm *WalletManager) Update() (err error)

Update fetches/updates all Wallet objects in a WalletManager.

func (*WalletManager) WalletNames 

func (wm *WalletManager) WalletNames() (wallets []string, err error)

WalletNames returns a list of existing Wallet names.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.