4 Secret Service API

The Secret Service API is a standard from freedesktop.org to securely store passwords and other confidential information. This API is implemented by system daemons such as the GNOME Keyring and the KDE Wallet (these are GNOME and KDE packages respectively and should be available on most modern GNU/Linux systems). It has been tested also with KeePassXC.

The auth-source library uses the secrets.el library to connect through the Secret Service API. You can also use that library in other packages, it’s not exclusive to auth-source.

Variable: secrets-enabled ¶

After loading secrets.el, a non-nil value of this variable indicates the existence of a daemon providing the Secret Service API.

Command: secrets-show-secrets ¶

This command shows all collections, items, and their attributes.

The atomic objects managed by the Secret Service API are secret items, which contain things an application wishes to store securely, like a password. Secret items have a label (a name), the secret (which is the string we want, like a password), and a set of lookup attributes. The attributes can be used to search and retrieve a secret item at a later date.

Secret items are grouped in collections. A collection is sometimes called a ‘keyring’ or ‘wallet’ in GNOME Keyring and KDE Wallet but it’s the same thing, a group of secrets. Collections are personal and protected so only the owner can open them.

The most common collection is called "login".

A collection can have an alias. The alias "default" is commonly used so the clients don’t have to know the specific name of the collection they open. Other aliases are not supported yet. Since aliases are globally accessible, set the "default" alias only when you’re sure it’s appropriate.

Function: secrets-list-collections ¶

This function returns all the collection names as a list.

Function: secrets-set-alias collection alias ¶

Set alias as alias of collection labeled collection. Currently only the alias "default" is supported.

Function: secrets-get-alias alias ¶

Return the collection name alias is referencing to. Currently only the alias "default" is supported.

Collections can be created and deleted by the functions secrets-create-collection and secrets-delete-collection. Usually, this is not done from within Emacs. Do not delete standard collections such as "login".

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 is better than a persistent collection when the secret items should not live permanently. 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.

Function: secrets-list-items collection ¶

Returns all the item labels of collection as a list.

Function: secrets-create-item collection item password &rest attributes ¶

This function creates a new item in collection with label item and password password. The label item does not have to be unique in collection. attributes are key-value pairs set for the created item. The keys are keyword symbols, starting with a colon; values are strings. Example:

;;; The collection is "session", the label is "my item"
;;; and the secret (password) is "geheim".
(secrets-create-item "session" "my item" "geheim"
 :method "sudo" :user "joe" :host "remote-host")

The key :xdg:schema determines the scope of the item to be generated, i.e. for which applications the item is intended for. This is just a string like "org.freedesktop.NetworkManager.Mobile" or "org.gnome.OnlineAccounts", the other required keys are determined by this. If no :xdg:schema is given, "org.freedesktop.Secret.Generic" is used by default.

Function: secrets-get-secret collection item ¶

Return the secret of item labeled item in collection. If there are several items labeled item, it is undefined which one is returned. If there is no such item, return nil.

Function: secrets-delete-item collection item ¶

This function deletes item item in collection. If there are several items labeled item, it is undefined which one is deleted.

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 and they can be used for searching of items.

Function: secrets-get-attribute collection item attribute ¶

Returns the value of key attribute of item labeled item in collection. If there are several items labeled item, it is undefined which one is returned. If there is no such item, or the item doesn’t own this key, the function returns nil.

Function: secrets-get-attributes collection item ¶

Return the lookup attributes of item labeled item in collection. If there are several items labeled item, it is undefined which one is returned. If there is no such item, or the item has no attributes, it returns nil. Example:

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

Function: secrets-search-items collection &rest attributes ¶

Search for the items in collection with matching attributes. The attributes are key-value pairs, as used in secrets-create-item. Example:

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

The auth-source library uses the secrets.el library and thus the Secret Service API when you specify a source matching "secrets:COLLECTION". For instance, you could use "secrets:session" to use the "session" collection, open only for the lifetime of Emacs. Or you could use "secrets:Login" to open the "Login" collection. As a special case, you can use the symbol default in auth-sources (not a string, but a symbol) to specify the "default" alias. Here is a contrived example that sets auth-sources to search three collections and then fall back to ~/.authinfo.gpg.

(setq auth-sources '(default
                     "secrets:session"
                     "secrets:Login"
                     "~/.authinfo.gpg"))

Attribute values in the auth-source spec, which are not strings (like port numbers), are stringified prior calling the secrets.el functions.