ready for new release; docs update.
This commit is contained in:
parent
55e740793a
commit
df86089517
GPG Key ID:
8C004C2F93481F6B
191
README.adoc
191
README.adoc
@ -59,16 +59,17 @@ To reflect the absolute breaking changes, the module name changes as well from `
|
||||
|
||||
=== 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.
|
||||
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*`.
|
||||
* 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).
|
||||
|
||||
@ -79,50 +80,158 @@ 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"
|
||||
├─ 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 Session types:
|
||||
In *practice*, however, most users will only have two ``Collection``s:
|
||||
|
||||
* 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).
|
||||
* a default "system" one named `login` (usually 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. 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.
|
||||
////
|
||||
|
||||
[source,go]
|
||||
----
|
||||
package main
|
||||
|
||||
import (
|
||||
`fmt`
|
||||
`log`
|
||||
|
||||
// "github.com/johnnybubonic/gosecret" // GitHub mirror
|
||||
"r00t2.io/gosecret" // real upstream; recommended
|
||||
)
|
||||
|
||||
const (
|
||||
// The default collection; it should be available on all SecretService implementations.
|
||||
collectionName string = "login"
|
||||
// A label for an Item used in examples below.
|
||||
exampleLabel string = "Some Website Credentials"
|
||||
)
|
||||
|
||||
func main() {
|
||||
|
||||
var err error
|
||||
var service *gosecret.Service
|
||||
var collection *gosecret.Collection
|
||||
var item *gosecret.Item
|
||||
var itemAttrs map[string]string
|
||||
var itemLabel string
|
||||
var secret *gosecret.Secret
|
||||
|
||||
// All interactions with SecretService start with initiating a Service connection.
|
||||
if service, err = gosecret.NewService(); err != nil {
|
||||
log.Panicln(err)
|
||||
}
|
||||
defer service.Close()
|
||||
|
||||
// And unless operating directly on a Service via its methods, you probably need a Collection as well.
|
||||
if collection, err = service.GetCollection(collectionName); err != nil {
|
||||
log.Panicln(err)
|
||||
}
|
||||
|
||||
/*
|
||||
Create a Secret which gets stored in an Item which gets stored in a Collection.
|
||||
See the documentation for details.
|
||||
*/
|
||||
// Incidentally, I believe this is the only exported function/method that does not return an error returner.
|
||||
secret = gosecret.NewSecret(
|
||||
service.Session, // The session associated with this Secret. You're likely fine with the automatically-created *(Service).Session.
|
||||
[]byte{}, // The "parameters". Likely this is an empty byteslice.
|
||||
[]byte("a super secret password"), // The actual secret value.
|
||||
"text/plain", // The content type (MIME type/media type). See https://www.iana.org/assignments/media-types/media-types.xhtml.
|
||||
)
|
||||
|
||||
/*
|
||||
Item attributes are a map[string]string of *metadata* about a Secret/Item.
|
||||
Do *NOT* store sensitive information in these.
|
||||
They're primarily used for searching for Items.
|
||||
*/
|
||||
itemAttrs = map[string]string{
|
||||
"Use": "an example secret",
|
||||
"note": "These keys can be anything you want!",
|
||||
"url": "https://somewebsite.tld/login",
|
||||
"username": "user.name",
|
||||
}
|
||||
|
||||
// And create the Item (and add it to SecretService).
|
||||
if item, err = collection.CreateItem(
|
||||
exampleLabel, // The label of the item. This should also be considered not secret.
|
||||
itemAttrs, // Attributes for the item; see above.
|
||||
secret, // The actual secret.
|
||||
true, // Whether to replace an existing item with the same label or not.
|
||||
); err != nil {
|
||||
log.Panicln(err)
|
||||
}
|
||||
|
||||
/*
|
||||
Now let's fetch the same Item via its attributes.
|
||||
The results are split into locked items and unlocked items.
|
||||
*/
|
||||
var unlockedItems []*gosecret.Item
|
||||
var lockedItems []*gosecret.Item
|
||||
|
||||
if unlockedItems, lockedItems, err = service.SearchItems(itemAttrs); err != nil {
|
||||
log.Panicln(err)
|
||||
}
|
||||
|
||||
// We should only have one Item that matches the search attributes, and unless the item or collection is locked, ...
|
||||
item = unlockedItems[0]
|
||||
if itemLabel, err = item.Label(); err != nil {
|
||||
log.Panicln(err)
|
||||
}
|
||||
fmt.Printf("Found item: %v\n", itemLabel)
|
||||
|
||||
// Alternatively if you are unsure of the attributes but know the label of the item you want, you can iterate through them.
|
||||
var itemResults []*gosecret.Item
|
||||
|
||||
if itemResults, err = collection.Items(); err != nil {
|
||||
log.Panicln(err)
|
||||
}
|
||||
|
||||
for idx, i := range itemResults {
|
||||
if itemLabel, err = i.Label(); err != nil {
|
||||
fmt.Printf("Cannot read label for item at path '%v'\n", i.Dbus.Path())
|
||||
continue
|
||||
}
|
||||
if itemLabel != exampleLabel { // Matching against a desired label - exampleLabel, in this case.
|
||||
continue
|
||||
}
|
||||
fmt.Printf("Found item labeled '%v'! Index number %v at path '%v'\n", itemLabel, idx, i.Dbus.Path())
|
||||
fmt.Printf("Password: %v\n", string(i.Secret.Value))
|
||||
break
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
== Library Hacking
|
||||
|
||||
=== Tests
|
||||
|
||||
Many functions are consolidated into a single test due to how dependent certain processes are on other objects. However, all functionality should be covered by test cases and the error string will always be passed through the stack to `go test -v` output.
|
||||
|
||||
Obviously since this library interacts directly with Dbus (and I don't want to spend the time to mock up an entire Dbus-like interface to test), all tests are integration tests rather than unit tests. Therefore in the event of a failed run, you will need to open e.g. Seahorse or d-feet or some other Dbus/SecretService browser and manually delete the created Secret Service collection. It/they should be easily identified; they use a generated UUID4 string as the collection name and it is highly unlikely that you will see any other collections named as such. If running `go test` with the verbose flag (`-v`), the name and path of the collection will be printed out. If all tests pass, the test collection should be removed automatically.
|
||||
|
||||
The same UUID is used for all tests in a test run.
|
||||
|
||||
You may be prompted during a test run for a password; you can simply use a blank password for this as it is the password used to protect a collection. This prompt pops up during the creation of a Collection.
|
||||
|
||||
60
doc.go
60
doc.go
@ -43,13 +43,13 @@ SecretService Concepts
|
||||
|
||||
For reference:
|
||||
|
||||
- A Service allows one to operate on/with Session objects.
|
||||
- A Service allows one to retrieve and operate on/with Session and Collection objects.
|
||||
|
||||
- A Session allows one to operate on/with Collection objects.
|
||||
- A Session allows one to operate on/with Item objects (e.g. parsing/decoding/decrypting them).
|
||||
|
||||
- A Collection allows one to operate on/with Item objects.
|
||||
- A Collection allows one to retrieve and operate on/with Item objects.
|
||||
|
||||
- An Item allows one to operate on/with Secrets.
|
||||
- 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).
|
||||
|
||||
@ -59,44 +59,30 @@ 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"
|
||||
├─ 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 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).
|
||||
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.
|
||||
*/
|
||||
package libsecret
|
||||
package gosecret
|
||||
|
||||
Loading…
Reference in New Issue
Block a user