File: secrets.el.html

This package provides an implementation of the Secret Service API
<https://www.freedesktop.org/wiki/Specifications/secret-storage-spec>.
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.

Defined variables (20)

Defined functions (37)

Defined faces (0)