3 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).

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".

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 "session"
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 nil,
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:

Return the secret of item labeled item in collection.
If there is no such item, return nil.

— Function: secrets-delete-item collection item

This function deletes item item in collection.

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 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 is no such item, or the item has no
attributes, it returns nil. Example:

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.