1 files changed, 40 insertions, 14 deletions
diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi
index e467fc135f3..495d9f53e15 100644
--- a/doc/misc/auth.texi
+++ b/doc/misc/auth.texi
@@ -86,7 +86,7 @@ password (known as the secret).
 
 Similarly, the auth-source library supports multiple storage backend,
 currently either the classic ``netrc'' backend, examples of which you
-can see later in this document, the Secret Service API, and pass, the
+can see later in this document, JSON files, the Secret Service API, and pass, the
 standard unix password manager.  This is done with EIEIO-based
 backends and you can write your own if you want.
 
@@ -169,6 +169,9 @@ get fancy, the default and simplest configuration is:
 ;;; use pass (@file{~/.password-store})
 ;;; (@pxref{The Unix password store})
 (setq auth-sources '(password-store))
+;;; JSON data in format [@{ "machine": "SERVER",
+;;; "login": "USER", "password": "PASSWORD" @}...]
+(setq auth-sources '("~/.authinfo.json.gpg"))
 @end lisp
 
 By adding multiple entries to @code{auth-sources} with a particular
@@ -235,6 +238,16 @@ don't use a port entry, you match any Tramp method, as explained
 earlier.  Since Tramp has about 88 connection methods, this may be
 necessary if you have an unusual (see earlier comment on those) setup.
 
+The netrc format is directly translated into JSON, if you are into
+that sort of thing. Just point to a JSON file with entries like this:
+
+@example
+[
+ @{ "machine": "yourmachine.com", "port": "http",
+    "login": "testuser", "password": "testpass" @}
+]
+@end example
+
 @node Multiple GMail accounts with Gnus
 @chapter Multiple GMail accounts with Gnus
 
@@ -335,25 +348,36 @@ Returns all the item labels of @var{collection} as a list.
 
 @defun secrets-create-item collection item password &rest attributes
 This function creates a new item in @var{collection} with label
-@var{item} 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:
+@var{item} and password @var{password}.  The label @var{item} does not
+have to be unique in @var{collection}.  @var{attributes} are key-value
+pairs set for the created item.  The keys are keyword symbols,
+starting with a colon.  Example:
 
 @example
-;;; The session "session", the label is "my item"
-;;; and the secret (password) is "geheim"
+;;; The session is "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")
 @end example
+
+The key @code{:xdg:schema} determines the scope of the item to be
+generated, i.e.@: for which applications the item is intended for.
+This is just a string like "org.freedesktop.NetworkManager.Mobile" or
+"org.gnome.OnlineAccounts", the other required keys are determined by
+this.  If no @code{:xdg:schema} is given,
+"org.freedesktop.Secret.Generic" is used by default.
 @end defun
 
 @defun 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}.
+Return the secret of item labeled @var{item} in @var{collection}.  If
+there are several items labeled @var{item}, it is undefined which one
+is returned.  If there is no such item, return @code{nil}.
 @end defun
 
 @defun secrets-delete-item collection item
-This function deletes item @var{item} in @var{collection}.
+This function deletes item @var{item} in @var{collection}.  If there
+are several items labeled @var{item}, it is undefined which one is
+deleted.
 @end defun
 
 The lookup attributes, which are specified during creation of a
@@ -363,18 +387,20 @@ from a given secret item and they can be used for searching of items.
 
 @defun secrets-get-attribute collection item attribute
 Returns the value of key @var{attribute} of item labeled @var{item} in
-@var{collection}.  If there is no such item, or the item doesn't own
-this key, the function returns @code{nil}.
+@var{collection}.  If there are several items labeled @var{item}, it
+is undefined which one is returned.  If there is no such item, or the
+item doesn't own this key, the function returns @code{nil}.
 @end defun
 
 @defun secrets-get-attributes collection item
 Return the lookup attributes of item labeled @var{item} in
-@var{collection}.  If there is no such item, or the item has no
-attributes, it returns @code{nil}.  Example:
+@var{collection}.  If there are several items labeled @var{item}, it
+is undefined which one is returned.  If there is no such item, or the
+item has no attributes, it returns @code{nil}.  Example:
 
 @example
 (secrets-get-attributes "session" "my item")
-     @result{} ((:user . "joe") (:host ."remote-host"))
+     @result{} ((:user . "joe") (:host . "remote-host"))
 @end example
 @end defun