Next: Help for developers, Previous: Multiple GMail accounts with Gnus, Up: Top [Contents][Index]
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-nil
value of this
variable indicates the existence of a daemon providing the Secret
Service API.
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.
This function returns all the collection names as a list.
Set alias as alias of collection labeled collection.
Currently only the alias "default"
is supported.
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.
Returns all the item labels of collection as a list.
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 nil
.
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.
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
.
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 "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"))
Next: Help for developers, Previous: Multiple GMail accounts with Gnus, Up: Top [Contents][Index]