129 lines
3.9 KiB
Plaintext
129 lines
3.9 KiB
Plaintext
= libsecret/gosecret
|
|
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/gosecret.svg[link="https://pkg.go.dev/r00t2.io/gosecret"]
|
|
|
|
This project is originally forked from https://github.com/gsterjov/go-libsecret[go-libsecret^] due to:
|
|
|
|
* Lack of response from the developer
|
|
* Complete lack of documentation
|
|
* Poor, ineffecient, or just plain antipattern design
|
|
* Missing functionality
|
|
|
|
and as such, hopefully this library should serve as a more effective libsecret/SecretService interface.
|
|
|
|
== Backwards Compatability/Drop-In Replacement Support
|
|
|
|
Version series `v0.X.X` of this library promises full and non-breaking backwards 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:
|
|
|
|
// TODO: did I do this correctly? I never really use replacements so someone PR if this is incorrect.
|
|
.go.mod
|
|
[source]
|
|
----
|
|
// ...
|
|
replace (
|
|
github.com/gsterjov/go-libsecret dev => r00t2.io/gosecret v0
|
|
)
|
|
----
|
|
|
|
and then run `go mod tidy`.
|
|
|
|
== New Developer API
|
|
|
|
Starting from `v1.0.0` onwards, entirely breaking changes can be assumed from the original project.
|
|
|
|
To use the new version,
|
|
|
|
[source,go]
|
|
----
|
|
import (
|
|
`r00t2.io/gosecret/v1`
|
|
)
|
|
----
|
|
|
|
To reflect the absolute breaking changes, the module name changes as well from `libsecret` to `gosecret`.
|
|
|
|
=== Status
|
|
|
|
The new API is underway, and all functionality in V0 is present. However, It's not "complete". https://github.com/johnnybubonic/gosecret/pulls[PRs^] welcome, of course, but this will be an ongoing effort for a bit of time.
|
|
|
|
== SecretService Concepts
|
|
|
|
For reference:
|
|
|
|
* A *`Service`* allows one to operate on/with *`Session`* objects.
|
|
* A *`Session`* allows one to operate on/with `*Collection*` objects.
|
|
* A `*Collection*` allows one to operate on/with `*Item*` objects.
|
|
* An `*Item*` allows one to operate on/with `*Secrets*`.
|
|
(`*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"
|
|
│ ├─ Collection "A.1"
|
|
│ │ ├─ Item "A.1.a"
|
|
│ │ │ ├─ Secret "A_1_a_I"
|
|
│ │ │ └─ Secret "A_1_a_II"
|
|
│ │ └─ Item "A.1.b"
|
|
│ │ ├─ Secret "A_1_b_I"
|
|
│ │ └─ Secret "A_1_b_II"
|
|
│ └─ Collection "A.2"
|
|
│ ├─ Item "A.2.a"
|
|
│ │ ├─ Secret "A_2_a_I"
|
|
│ │ └─ Secret "A_2_a_II"
|
|
│ └─ Item "A.2.b"
|
|
│ ├─ Secret "A_2_b_I"
|
|
│ └─ Secret "A_2_b_II"
|
|
└─ Session "B"
|
|
├─ Collection "B.1"
|
|
│ ├─ Item "B.1.a"
|
|
│ │ ├─ Secret "B_1_a_I"
|
|
│ │ └─ Secret "B_1_a_II"
|
|
│ └─ Item "B.1.b"
|
|
│ ├─ Secret "B_1_b_I"
|
|
│ └─ Secret "B_1_b_II"
|
|
└─ Collection "B.2"#
|
|
├─ Item "B.2.a"
|
|
│ ├─ Secret "B_2_a_I"
|
|
│ └─ Secret "B_2_a_II"
|
|
└─ Item "B.2.b"
|
|
├─ Secret "B_2_b_I"
|
|
└─ Secret "B_2_b_II"
|
|
----
|
|
|
|
And so on.
|
|
|
|
In *practice*, however, most users will only have two Session types:
|
|
|
|
* a default "system" one, and
|
|
* a temporary one that may or may not exist, running in memory for the current login session
|
|
|
|
and a single Collection, named `login` (and aliased to `default`, usually).
|
|
|
|
== Usage
|
|
|
|
Full documentation can be found via inline documentation. Either via the https://pkg.go.dev/r00t2.io/gosecret[pkg.go.dev documentation^] or https://pkg.go.dev/golang.org/x/tools/cmd/godoc[`godoc`^] (or `go doc`) in the source root.
|
|
|
|
////
|
|
However, here's a quick demonstration.
|
|
////
|