→ ↺

Secret service CL API

Table of Contents

• 1 Find secrets
• 2 Manage secrets
• 3 Collections

[in package SECRET-SERVICE]

This is a partial interface to the Secret Service API in Common Lisp. Secret service is an API to store keys and passwords in a dedicated service; both Gnome and KDE provide such service (gnome-keyring).

It allows one to offload caring about how to safely store passwords and keys for CL projects to someone else.

Simple usage:

  (find-the-secret '(("machine" "example.com")))

would return password for the secret with parameter machine having provided value, if there is only one, prompting for password if necessary.

(create-item (default-collection) "My shop" nil "password")
=> "/org/freedesktop/secrets/collection/login/148"
=> "/"

would create an item with just a label and a secret and return the path to it; note that there is no property there that can be used to find the item by search, but it shows (e.g., in Seahorse or emacs) properly.

(get-secret-of-item *)
=> "password"

would again reveal the password.

← ↑ → ↺

1 Find secrets

• [function] FIND-ALL-SECRETS PARS

  Find all secrets with attributes in PARS. Returns a list of match pairs (path secret). See secret structure for the second item format.

  E.g., (find-all-secrets '(("machine" "example.com")))

• [function] GET-SECRET-OF-ITEM PATH

  Get secret from secret item on PATH.

  Provide restart that tries to unlock and read again. This should not be standard situation, but, as API standard says, The inherent race conditions present due to this are unavoidable, and must be handled gracefully.

• [function] STRINGIFY-SECRET SECRET

  Turn secret structure returned by D-Bus to a secret string

• [function] GET-SECRET-ITEM-ATTRIBUTES ITEM-PATH

  An alist of all item attributes. The cars of each item is a keyword.

• [function] GET-SECRET-ITEM-ATTRIBUTE ITEM LABEL

  Get attribute of a secret item

• [function] GET-SECRET-ITEM-PROPERTY ITEM-PATH LABEL

  Get attribute LABEL of secret item with path ITEM-PATH.

• [condition] SECRET-ITEM-SEARCH-ERROR ERROR

• [function] FIND-THE-SECRET PARS

  Make sure that there is just one secret matching pars, and return it. Raise error otherwise, or when the secret needs to be unlocked.

← ↑ → ↺

2 Manage secrets

• [function] CREATE-ITEM COLLECTION-PATH LABEL DICT SECRET &KEY REPLACE (CONTENT-TYPE "text/plain")

  Create an item.

  Collection-path is a path to the COLLECTION that should store the secret LABEL is name of the secret, DICT alist of attributes (all atoms strings), and SECRET the secret to store.

• [function] DELETE-SECRET PATH

← ↑ ↺

3 Collections

• [glossary-term] COLLECTION

  Collection is a group of secret service items (keyring, wallet). Each secret is part of a collection.

  They are identified by the path. There are two commonly used collections - session and login.

  Collection can be accessed by an alias. Alias DEFAULT should be always present.

• [function] DEFAULT-COLLECTION

  Default collection, that is, collection with alias default.

• [variable] *LOGIN-COLLECTION* "/org/freedesktop/secrets/collection/login"

  Path to the collection named login. This is a commonly used collection.

• [variable] *SESSION-COLLECTION* "/org/freedesktop/secrets/collection/session"

  Path to the collection named session. Gnome keyring provides this collection; it has lifetime of the logged in user session.

  It may or may not exist with other Service Providers.

• [function] GET-COLLECTIONS-LIST

  List of available collections.

• [function] FIND-COLLECTION-BY-NAME NAME

  Find path to collection with label or alias NAME.

• [function] GET-COLLECTION-BY-ALIAS NAME

  Get collection path by alias name, or nil. There is one predefined alias, "session".

• [function] GET-COLLECTION-ATTRIBUTES COLLECTION-PATH