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.

2 files changed, 16 insertions, 14 deletions

diff --git a/lisp/auth-source.el b/lisp/auth-source.el
index 8c5b5564e7e..1c58410f029 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 25802f2c463..552638348c5 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.