keyring

package module
v1.0.1 Latest Latest
Warning

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

 Go to latest Published: Feb 28, 2020 License: BSD-2-Clause Imports: 4 Imported by: 23

README

go-dbus-keyring

A GoLang module for querying a keyring application implementing the SecretService DBus specification defined here.

It is based on the awesome dbus library godbus/dbus (which is the only dependecy of the project).

Features

  • Full SecretService implementation
  • Manage collections
  • Manage items/secrets
  • Automatically handles user prompts

Missing Features

  • A server package to implement you own keyring manager
  • Support for encrypted secrets (currently only PLAIN is supported)
  • Support for signals emitted by various SecretService interfaces (only prompts are supported)
  • Unit tests :(

Usage

go-dbus-keyring is setup as a go1.12 module and can be added to any project like this:

go get -u github.com/ppacher/go-dbus-keyring@v1

This project follows Semantic Versioning as required by go-modules. Those, there will be now API changes in major releases!

The documentation for this project is available on godoc.org. In addition, there's a simple example inside the _examples directory.

package main

import (
    "github.com/godbus/dbus/v5"
    keyring "github.com/ppacher/go-dbus-keyring"
)

func main() {
    bus := dbus.SessionBus()
    
    // Get a SecretService client
    secrets, _ := keyring.GetSecretService(bus)

    // Search for the collection with name "my-collection".
    // You can also use secrets.GetDefaultCollection() or secrets.GetAllCollections()
    collection, _ := secrets.GetCollection("my-collection")
    
    // Search for the item with name "my-password"
    item, _ := collection.GetItem("my-password")
    
    // make sure it is unlocked
    // this also handles any prompt that may be required
    _ = item.Unlock()

    secret, _ := item.GetSecret()
    fmt.Println(string(secret.Value))
}

Contributions

Contributions to this project are welcome! Just fork the repository and create a pull request! If you need help to get started checkout the github documentation on creating pull requests.

License

go-dbus-keyring is available under a Simplified BSD License. See LICENSE file for the full text.

Documentation

Index

Constants

View Source 
const (
	SecretServiceDest   = "org.freedesktop.secrets"
	SecretServicePrefix = "org.freedesktop.Secret."
	SecretServicePath   = "/org/freedesktop/secrets"

	CollectionInterface = SecretServicePrefix + "Collection"
	SessionInterface    = SecretServicePrefix + "Session"
	ItemInterface       = SecretServicePrefix + "Item"
	ServiceInterface    = SecretServicePrefix + "Service"
	PromptInterface     = SecretServicePrefix + "Prompt"
	DefaultCollection   = SecretServicePath + "/aliases/default"
	SessionCollection   = SecretServicePath + "/collection/session"

	AlgPlain = "plain"
	// AlgDH is not yet supported only AlgPlain is supported
	AlgDH = "dh-ietf1024-sha256-aes128-cbc-pkcs7"
)

Variables

This section is empty.

Functions

func ErrInvalidType 

func ErrInvalidType(expected string, value interface{}) error

Types

type Collection 

type Collection interface {
	// Path returns the ObjectPath of the collection
	Path() dbus.ObjectPath

	// GetLabel returns the label of the collection
	GetLabel() (string, error)

	// SetLabel sets the label of the connection
	SetLabel(l string) error

	// Locked returns true if the collection is locked
	Locked() (bool, error)

	// Delete deletes the collection and handles any prompt required
	Delete() error

	// GetAllItems returns all items in the collection
	GetAllItems() ([]Item, error)

	// GetItem returns the first item with the given label
	GetItem(name string) (Item, error)

	// SearchItems searches for items in the collection
	SearchItems(attrs map[string]string) ([]Item, error)

	// CreateItem creates a new item inside the collection optionally overwritting an
	// existing one
	CreateItem(session dbus.ObjectPath, label string, attr map[string]string, secret []byte, contentType string, replace bool) (Item, error)
}

Collection provides access secret collections from org.freedesktop.secret The DBus specification for org.freedesktop.Secret.Collection can be found at https://specifications.freedesktop.org/secret-service/re02.html

func GetCollection 

func GetCollection(conn *dbus.Conn, path dbus.ObjectPath) (Collection, error)

GetCollection returns a collection object for the specified path

type Item 

type Item interface {
	// Locked returns true if the item is currently locked
	Locked() (bool, error)

	// Unlock unlocks the item and handles any prompt that might be required
	Unlock() (bool, error)

	// GetAttributes returns the items attributes
	GetAttributes() (map[string]string, error)

	// SetAttributes sets the items attributes
	SetAttributes(map[string]string) error

	// GetLabel returns the label of the item
	GetLabel() (string, error)

	// SetLabel sets the item's label
	SetLabel(string) error

	// Delete deletes the item any handles any prompt that might be required
	Delete() error

	// GetSecret returns the secret of the item
	GetSecret(session dbus.ObjectPath) (*Secret, error)

	// SetSecret sets the secret of the item
	SetSecret(dbus.ObjectPath, []byte, string) error

	// GetCreated returns the time the item has been created
	GetCreated() (time.Time, error)

	// GetModified returns the time the item has been last modified
	GetModified() (time.Time, error)
}

Item implements a wrapper for org.freedesktop.Secret.Item as defined here https://specifications.freedesktop.org/secret-service/re03.html

func GetItem 

func GetItem(conn *dbus.Conn, path dbus.ObjectPath) (Item, error)

GetItem returns a new item client for the specified path

type Prompt 

type Prompt interface {
	// Path returns the ObjectPath of the prompt
	Path() dbus.ObjectPath

	// Prompt performs the prompt
	Prompt(windowID string) (<-chan *dbus.Variant, error)

	// Dismiss dismisses the prompt. It is no longer valid after calling Dismiss()
	Dismiss() error
}

Prompt provides interaction with the Prompt interface from Freedesktop.org's Secret Service API it's defined at https://specifications.freedesktop.org/secret-service/re05.html

func GetPrompt 

func GetPrompt(conn *dbus.Conn, path dbus.ObjectPath) Prompt

GetPrompt returns a Prompt client for the given path

type Secret 

type Secret struct {
	Session     dbus.ObjectPath
	Parameters  []byte
	Value       []byte
	ContentType string
}

Secret defines the DBUS STRUCT for a secret

type SecretService 

type SecretService interface {
	// OpenSession opens a unique session for the calling application
	OpenSession() (Session, error)

	// GetCollection returns the collection with the given name
	GetCollection(name string) (Collection, error)

	// GetAllCollections returns all collections stored in the secret service
	GetAllCollections() ([]Collection, error)

	// GetDefaultCollection returns the default collection of the secret service
	// ( DBus path = /org/freedesktop/secrets/aliases/default )
	GetDefaultCollection() (Collection, error)

	// SearchItems finds all items in any collection and returns them either
	// in the unlocked or locked slice
	SearchItems(map[string]string) (unlocked []Item, locked []Item, err error)

	// GetSecrets returns multiple secrets from different items
	GetSecrets(paths []dbus.ObjectPath, session dbus.ObjectPath) (map[dbus.ObjectPath]*Secret, error)

	// ReadAlias resolves the alias (like 'default') to the object path of the
	// referenced collection
	ReadAlias(name string) (dbus.ObjectPath, error)

	// SetAlias creates a new alias for the given collection path
	// Note that if path is "/", the alias will be deleted
	// see https://specifications.freedesktop.org/secret-service/re01.html#org.freedesktop.Secret.Service.SetAlias
	SetAlias(name string, path dbus.ObjectPath) error

	// RemoveAlias removes the provided alias. This is a utility method for SetAlias(name, "/")
	RemoveAlias(name string) error

	// CreateCollection creates a new collection with the given properties and an optional alias (leave empty for no alias)
	// It also handles any prompt that may be required
	CreateCollection(label string, alias string) (Collection, error)

	// Lock locks items or collections and handles any prompt that may be required
	Lock(paths []dbus.ObjectPath) ([]dbus.ObjectPath, error)

	// Unlock unlocks items or collections and handles any prompt that may be required
	Unlock(paths []dbus.ObjectPath) ([]dbus.ObjectPath, error)
}

SecretService manages all the sessions and collections it's defined in org.freedesktop.Secret.Service https://specifications.freedesktop.org/secret-service/re01.html

func GetSecretService 

func GetSecretService(conn *dbus.Conn) (SecretService, error)

GetSecretService returns a client to the SecretService (org.freedesktop.secrets) on the provided DBus connection

type Session 

type Session interface {
	// Path returns the object path of the session
	// To get a new session use SecretService.OpenSession()
	Path() dbus.ObjectPath

	// Close closes the session
	Close() error
}

Session allows to interact with the Session interface of Freedesktop.org's Secret Service API The session interface is defined at https://specifications.freedesktop.org/secret-service/re01.html

func GetSession 

func GetSession(conn *dbus.Conn, path dbus.ObjectPath) (Session, error)

GetSession returns a new Session for the provided path. Note that session must be opened beforehand Use SecretService.OpenSession() to open a new session and return a Session client

Source Files

View all Source files

Directories

Path Synopsis

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.