spec: Update recommendations for DBUS_COOKIE_SHA1 timeouts

This had two issues that could damage interoperability.

First, the spec wording suggested that any cookie that had not been
deleted was suitable for use in authentication. However, this introduces
a race condition, which is called out in comments in both the reference
implementation and GDBus: the newest cookie might be less old than the
arbitrary lifetime when authentication *begins*, but older than the
lifetime at the time authentication *ends*. As a result, we need a grace
period during which an old cookie will still be accepted, but a newer
cookie exists and will be used for new authentication operations.

Second, the spec wording implied that the arbitrary timeouts were
completely up to the implementor. However, GLib bug
https://gitlab.gnome.org/GNOME/glib/-/issues/2164 indicates that they
need to be reasonably compatible: in particular, GDBus servers
historically didn't allocate new cookies until 10 minutes had passed,
but libdbus clients would decline to use a cookie older than 5 minutes,
causing authentication to fail if the gdbus-server test-case (in which
GDBus and libdbus clients connect to a GDBus server) happened to take
longer than 5 minutes to run.

While I'm here, also be consistent about calling the secrets "cookies"
(consistent with the name of the mechanism) rather than "keys" (which
is what they are called in libdbus' dbus-keyring.c).

Signed-off-by: Simon McVittie <smcv@collabora.com>

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 3f84df23bd94efc474ef7596e80dc63ea654d5ce..16bbc2ca2fc1581d9484ce0cdd4833cb40bca74a 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -3403,8 +3403,27 @@
                 timeout can be fairly short), or more than a reasonable
                 time in the future (so that cookies never accidentally
                 become permanent, if the clock was set far into the future
-                at some point). If no recent keys remain, the
-                server may generate a new key.
+                at some point). The reference implementation deletes cookies
+                that are more than 5 minutes into the future, or more than
+                7 minutes in the past. For interoperability, using the
+                same arbitrary times in other implementations is suggested.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                If no sufficiently recent cookies remain, the server
+                generates a new cookie. To avoid spurious authentication
+                failures, cookies that are close to their deletion time
+                should not be used for new authentication operations.
+                For example, this avoids a client starting to use a cookie
+                whose age is 6m59s, and having authentication subsequently
+                fail because it takes 2 seconds, during which time the
+                cookie's age became 7m01s, greater than 7 minutes, causing
+                the server to delete it. The reference implementation
+                generates a new cookie whenever the most recent cookie is
+                older than 5 minutes, giving clients at least 2 minutes
+                to finish authentication. For interoperability, using the
+                same arbitrary time in other implementations is suggested.
               </para>
             </listitem>
             <listitem>