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).
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.
After loading secrets.el, a non-
nilvalue of this variable indicates the existence of a daemon providing the Secret Service API.
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
A collection can have an alias. The alias
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
only when you're sure it's appropriate.
Set alias as alias of collection labeled collection. Currently only the alias
Return the collection name alias is referencing to. Currently only the alias
Collections can be created and deleted by the functions
Usually, this is not done from within Emacs. Do not delete standard
collections such as
The special collection
"session" exists for the lifetime of the
corresponding client session (in our case, Emacs's lifetime). It is
created automatically when Emacs uses the Secret Service interface and
it is deleted when Emacs is killed. Therefore, it can be used to
store and retrieve secret items temporarily. The
collection is better than a persistent collection when the secret
items should not live longer than Emacs. The session collection can
be specified either by the string
"session", or by
whenever a collection parameter is needed in the following functions.
This function creates a new item in collection with label item and password password. attributes are key-value pairs set for the created item. The keys are keyword symbols, starting with a colon. Example:;;; The session "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")
Return the secret of item labeled item in collection. If there is no such item, return
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.
Returns the value of key attribute of item labeled item in collection. If there is no such item, or the item doesn't own this key, the function returns
Return the lookup attributes of item labeled item in collection. 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"))
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
"Login" collection. As a special case, you can use the
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"))