secrets

Homepage: https://www.gnu.org/software/emacs

Author: Michael Albinus

Summary

Client interface to gnome-keyring and kwallet

Commentary

This package provides an implementation of the Secret Service API
.
This API is meant to make GNOME-Keyring- and KWallet-like daemons
available under a common D-BUS interface and thus increase
interoperability between GNOME, KDE and other applications having
the need to securely store passwords and other confidential
information.

In order to activate this package, you must add the following code
into your .emacs:

  (require 'secrets)

Afterwards, the variable `secrets-enabled' is non-nil when there is
a daemon providing this interface.

The atomic objects to be managed by the Secret Service API are
secret items, which are something an application wishes to store
securely.  A good example is a password that an application needs
to save and use at a later date.

Secret items are grouped in collections.  A collection is similar
in concept to the terms 'keyring' or 'wallet'.  A common collection
is called "login".  A collection is stored permanently under the
user's permissions, and can be accessed in a user session context.

A collection can have an alias name.  The use case for this is to
set the alias "default" for a given collection, making it
transparent for clients, which collection is used.  Other aliases
are not supported (yet).  Since an alias is visible to all
applications, this setting shall be performed with care.

A list of all available collections is available by

  (secrets-list-collections)
   => ("session" "login" "ssh keys")

The "default" alias could be set to the "login" collection by

  (secrets-set-alias "login" "default")

An alias can also be dereferenced

  (secrets-get-alias "default")
   => "login"

Collections can be created and deleted.  As already said,
collections are used by different applications.  Therefore, those
operations shall also be performed with care.  Common collections,
like "login", shall not be changed except adding or deleting secret
items.

  (secrets-delete-collection "my collection")
  (secrets-create-collection "my collection")

With GNOME Keyring, there exists a special collection called
"session", which has the lifetime of the user being logged in.  Its
data are not stored on disk and go away when the user logs out.
Therefore, it can be used to store and retrieve secret items
temporarily.  The "session" collection can be addressed either by
the string "session", or by nil, whenever a collection parameter is
needed.

However, other Secret Service provider don't create this temporary
"session" collection.  You shall check first that this collection
exists, before you use it.

As already said, a collection is a group of secret items.  A secret
item has a label, the "secret" (which is a string), and a set of
lookup attributes.  The attributes can be used to search and
retrieve a secret item at a later date.

A list of all available secret items of a collection is available by

  (secrets-list-items "my collection")
   => ("this item" "another item")

Secret items can be added or deleted to a collection.  In the
following examples, we use the special collection "session".

  (secrets-delete-item "session" "my item")
  (secrets-create-item "session" "my item" "geheim"
                       :user "joe" :host "remote-host")

The string "geheim" is the secret of the secret item "my item".
The secret string can be retrieved from items:

  (secrets-get-secret "session" "my item")
   => "geheim"

The lookup attributes, which are specified during creation of a
secret item, must be a key-value pair.  Keys are keyword symbols,
starting with a colon; values are strings.  They can be retrieved
from a given secret item:

  (secrets-get-attribute "session" "my item" :host)
   => "remote-host"

  (secrets-get-attributes "session" "my item")
   => ((:user . "joe") (:host ."remote-host"))

The lookup attributes can be used for searching of items.  If you,
for example, are looking for all secret items for the user "joe",
you would perform

  (secrets-search-items "session" :user "joe")
   => ("my item" "another item")

Interactively, collections, items and their attributes could be
inspected by the command `secrets-show-secrets'.

Dependencies

• cl-lib
• dbus

Reverse dependencies

• weechat
• auth-source
• totp-auth