gokwallet/README.adoc

134 lines
4.0 KiB
Plaintext
Raw Normal View History

2021-12-28 05:48:08 -05:00
= 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)
}
----