[Emacs-diffs] /srv/bzr/emacs/trunk r107762: * auth.texi (Secret Service API): Add the missing text.

[Michael Albinus]

------------------------------------------------------------
revno: 107762
committer: Michael Albinus <address@hidden>
branch nick: trunk
timestamp: Wed 2012-04-04 17:28:57 +0200
message:
  * auth.texi (Secret Service API): Add the missing text.
modified:
  doc/misc/ChangeLog
  doc/misc/auth.texi

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-04-04 07:54:02 +0000
+++ b/doc/misc/ChangeLog        2012-04-04 15:28:57 +0000
@@ -1,3 +1,7 @@
+2012-04-04  Michael Albinus  <address@hidden>
+
+       * auth.texi (Secret Service API): Add the missing text.
+
 2012-04-04  Chong Yidong  <address@hidden>
 
        * message.texi (Using PGP/MIME): Note that epg is now the default.

=== modified file 'doc/misc/auth.texi'
--- a/doc/misc/auth.texi        2012-01-19 07:21:25 +0000
+++ b/doc/misc/auth.texi        2012-04-04 15:28:57 +0000
@@ -227,7 +227,135 @@
 @node Secret Service API
 @chapter Secret Service API
 
-TODO: how does it work generally, how does secrets.el work, some examples.
+The @dfn{Secret Service API} is a standard from
address@hidden://www.freedesktop.org/wiki/Specifications/secret-storage-spec,,freedesktop.org}
+to securely store passwords and other confidential information.
+Implementations of compliant daemons are the GNOME Keyring and the KDE
+Wallet.
+
+Although the usage of the client library secrets.el is hidden in Emacs
+via the auth-source library, its functionality can be used also
+directly in other packages.
+
address@hidden secrets-enabled
+After loading @file{secrets.el}, a address@hidden value of this
+variable indicates the existence of a daemon providing the Secret
+Service API.
address@hidden defvar
+
address@hidden Command secrets-show-secrets
+All collections, items, and their attributes are inspected by this command.
address@hidden deffn
+
+The atomic objects to be managed by the Secret Service API are
address@hidden items}, which are something an application wishes to store
+securely.  A good example is a password that an application needs to
+save and use at a later date.
+
+Secret items are grouped in @dfn{collections}.  A collection is
+similar in concept to the terms @samp{keyring} or @samp{wallet}.  A
+common collection is called @samp{"login"}.  A collection is stored
+permanently under the user's permissions, and can be accessed in a
+user session context.
+
+A collection can have an alias name.  The use case for this is to
+set the alias @samp{"default"} for a given collection, making it
+transparent for clients, which collection is used.  Other aliases
+are not supported (yet).  Since an alias is visible to all
+applications, this setting shall be performed with care.
+
address@hidden secrets-list-collections
+This function returns a list of collection names.
address@hidden defun
+
address@hidden secrets-set-alias collection alias
+Set @var{alias} as alias of collection labeled @var{collection}.
+For the time being, only the alias @samp{"default"} is supported.
address@hidden defun
+
address@hidden secrets-get-alias alias
+Return the collection name @var{alias} is referencing to.
+For the time being, only the alias @samp{"default"} is supported.
address@hidden defun
+
+Collections can be created and deleted by the functions
address@hidden and @code{secrets-delete-collection}.
+Usually, this is not applied from within Emacs.  Common collections,
+like @samp{"login"}, shall never be deleted.
+
+There exists a special collection called @samp{"session"}, which has
+the lifetime of the corresponding client session (aka 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.  This
+shall be preferred over creation of a persistent collection, when the
+information shall not live longer than Emacs.  The session collection
+can be addressed either by the string @samp{"session"}, or by
address@hidden, whenever a collection parameter is needed in the following
+functions.
+
+As already said, a collection is a group of secret items.  A secret
+item has a label, the @dfn{secret} (which is a string), and a set of
+lookup attributes.  The attributes can be used to search and retrieve
+a secret item at a later date.
+
address@hidden secrets-list-items collection
+Returns a list of all item labels of @var{collection}.
address@hidden defun
+
address@hidden secrets-create-item collection item password &rest attributes
+This function creates a new item in @var{collection} with label
address@hidden and password @var{PASSWORD}.  @var{attributes} are
+key-value pairs set for the created item.  The keys are keyword
+symbols, starting with a colon.  Example:
+
address@hidden
+(secrets-create-item "session" "my item" "geheim"
+ :method "sudo" :user "joe" :host "remote-host")
address@hidden example
address@hidden defun
+
address@hidden secrets-get-secret collection item
+Return the secret of item labeled @var{item} in @var{collection}.
+If there is no such item, return @code{nil}.
address@hidden defun
+
address@hidden secrets-delete-item collection item
+This function deletes item @var{item} in @var{collection}.
address@hidden defun
+
+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.
+
address@hidden secrets-get-attribute collection item attribute
+Returns the value of key @var{attribute} of item labeled @var{item} in
address@hidden  If there is no such item, or the item doesn't own
+this key, the function returns @code{nil}.
address@hidden defun
+
address@hidden secrets-get-attributes collection item
+Return the lookup attributes of item labeled @var{item} in
address@hidden  If there is no such item, or the item has no
+attributes, it returns @code{nil}.  Example:
+
address@hidden
+(secrets-get-attributes "session" "my item")
+     @result{} ((:user . "joe") (:host ."remote-host"))
address@hidden example
address@hidden defun
+
address@hidden secrets-search-items collection &rest attributes
+Searchs items in @var{collection} with @var{attributes}.
address@hidden are key-value pairs, as used in
address@hidden  Example:
+
address@hidden
+(secrets-search-items "session" :user "joe")
+     @result{} ("my item" "another item")
address@hidden example
address@hidden defun
 
 @node Help for developers
 @chapter Help for developers