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.

diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi
index 6602f9dc2e44b3626e1db2513f693d3d0c5f136c..b6823ea7791a9ab8627c89d8a1716b1e48a83749 100644 (file)
--- 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 8c5b5564e7e97c70d6c18068c07df4cb4c843163..1c58410f02963e8535105a22f4d0476217326a03 100644 (file)
--- 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 25802f2c463a9b06a31db15d1e82e6ad3ae64a4d..552638348c54a29c1259cfd935777792f7c33ec9 100644 (file)
--- 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.