master db0cab990c: Documentation update for Secret Service

[Michael Albinus]

branch: master
commit db0cab990c64d1b5808ed94e72f665305b60f5d9
Author: Michael Albinus <michael.albinus@gmx.de>
Commit: Michael Albinus <michael.albinus@gmx.de>

    Documentation update for Secret Service
    
    * doc/misc/auth.texi (Secret Service API): Precise "session" collection.
    
    * lisp/auth-source.el (auth-sources): Adapt custom label.
    
    * lisp/net/secrets.el: Adjust comments.
---
 doc/misc/auth.texi  | 29 +++++++++++++++--------------
 lisp/auth-source.el |  2 +-
 lisp/net/secrets.el | 28 +++++++++++++++-------------
 3 files changed, 31 insertions(+), 28 deletions(-)

diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi
index 6602f9dc2e..b6823ea779 100644
--- a/doc/misc/auth.texi
+++ b/doc/misc/auth.texi
@@ -305,7 +305,8 @@ The @dfn{Secret Service API} is a standard from
 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).
+be available on most modern GNU/Linux systems).  It has been tested
+also with KeePassXC.
 
 The auth-source library uses the @file{secrets.el} library to connect
 through the Secret Service API@.  You can also use that library in
@@ -360,19 +361,19 @@ Collections can be created and deleted by the functions
 Usually, this is not done from within Emacs.  Do not delete standard
 collections such as @code{"login"}.
 
-The special collection @code{"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 @code{"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 @code{"session"}, or by @code{nil},
-whenever a collection parameter is needed in the following functions.
-
-However, not all Secret Service provider create this temporary
-@code{"session"} collection, like KeePassXC.  You shall check first
-that this collection exists, before you use it.
+With GNOME Keyring, there exists a special collection called
+@code{"session"}, which has the lifetime of the user being logged in.
+Its data are not stored on disk and go away when the user logs out.
+Therefore, it can be used to store and retrieve secret items
+temporarily.  The @code{"session"} collection is better than a
+persistent collection when the secret items should not live
+permanently.  The @code{"session"} collection can be addressed either
+by the string @code{"session"}, or by @code{nil}, whenever a
+collection parameter is needed.
+
+However, other Secret Service provider don't create this temporary
+@code{"session"} collection.  You shall check first that this
+collection exists, before you use it.
 
 @defun secrets-list-items collection
 Returns all the item labels of @var{collection} as a list.
diff --git a/lisp/auth-source.el b/lisp/auth-source.el
index 8c5b5564e7..1c58410f02 100644
--- a/lisp/auth-source.el
+++ b/lisp/auth-source.el
@@ -256,7 +256,7 @@ can get pretty complex."
                         (choice :tag "Authentication backend choice"
                                 (string :tag "Authentication Source (file)")
                                 (list
-                                 :tag "Secret Service API/KWallet/GNOME 
Keyring"
+                                 :tag "Secret Service API/KWallet/GNOME 
Keyring/KeyPassXC"
                                  (const :format "" :value :secrets)
                                  (choice :tag "Collection to use"
                                          (string :tag "Collection name")
diff --git a/lisp/net/secrets.el b/lisp/net/secrets.el
index 25802f2c46..552638348c 100644
--- a/lisp/net/secrets.el
+++ b/lisp/net/secrets.el
@@ -77,15 +77,17 @@
 ;;   (secrets-delete-collection "my collection")
 ;;   (secrets-create-collection "my collection")
 
-;; There exists a special collection called "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.
+;; With GNOME Keyring, there exists a special collection called
+;; "session", which has the lifetime of the user being logged in.  Its
+;; data are not stored on disk and go away when the user logs out.
 ;; 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
-;; "session", or by nil, whenever a collection parameter is needed.
+;; temporarily.  The "session" collection can be addressed either by
+;; the string "session", or by nil, whenever a collection parameter is
+;; needed.
+
+;; However, other Secret Service provider don't create this temporary
+;; "session" collection.  You shall check first that this collection
+;; exists, before you use it.
 
 ;; As already said, a collection is a group of secret items.  A secret
 ;; item has a label, the "secret" (which is a string), and a set of
@@ -98,8 +100,7 @@
 ;;    => ("this item" "another item")
 
 ;; Secret items can be added or deleted to a collection.  In the
-;; following examples, we use the special collection "session", which
-;; is bound to Emacs's lifetime.
+;; following examples, we use the special collection "session".
 ;;
 ;;   (secrets-delete-item "session" "my item")
 ;;   (secrets-create-item "session" "my item" "geheim"
@@ -137,7 +138,7 @@
 ;; It has been tested with GNOME Keyring 2.29.92.  An implementation
 ;; for KWallet will be available at
 ;; svn://anonsvn.kde.org/home/kde/trunk/playground/base/ksecretservice;
-;; not tested yet.
+;; not tested yet.  This package has also been tested with KeePassXC 2.6.6.
 
 ;; Pacify byte-compiler.  D-Bus support in the Emacs core can be
 ;; disabled with configuration option "--without-dbus".  Declare used
@@ -263,7 +264,7 @@ It returns t if not."
 ;;   </signal>
 ;; </interface>
 
-;; This is not guaranteed to exist.  For example, KeePassXC does not offer 
this.
+;; This exist only for GNOME Keyring.
 (defconst secrets-session-collection-path
   "/org/freedesktop/secrets/collection/session"
   "The D-Bus temporary session collection object path.")
@@ -906,7 +907,7 @@ to their attributes."
    secrets-interface-service "CollectionDeleted"
    'secrets-collection-handler)
 
-  ;; We shall inform, whether the secret service is enabled on this
+  ;; We shall inform, that the secret service is enabled on this
   ;; machine.
   (setq secrets-enabled t))
 
@@ -917,6 +918,7 @@ to their attributes."
 ;; * secrets-debug should be structured like auth-source-debug to
 ;;   prevent leaking sensitive information.  Right now I don't see
 ;;   anything sensitive though.
+
 ;; * Check, whether the dh-ietf1024-aes128-cbc-pkcs7 algorithm can be
 ;;   used for the transfer of the secrets.  Currently, we use the
 ;;   plain algorithm.