[PATCH v2] dbus-spec: introduce new ALLOW_INTERACTIVE_AUTHENTICATION flag

[Lennart Poettering]

As discussed earlier on the dbus mailing list, let's add a new flag to
the message header, that allows clients to indicate whether they are OK
with possiably time-intensive interactive authentication.

This is useful for authentication frameworks such as polkit, but this
flag is supposed to be generic, and not be bound to any implementation
of such a framework.

The dbus specification already clarifies that unknown flags must be
ignored, the reference implementation and the other implementations i
checked indeed ignore any new flags, hence we should be fine with
compatibility here.

This patch simply updates the spec, it does not add new APIs for this to
the reference implementation.

This is version 2:
- rename from PERMIT to ALLOW (as suggested by Marcel)
- define a standardized error to return if interactive authentication is
  required (as suggested by Ted)
---
 doc/dbus-specification.xml | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 1b740fe..506fe78 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -1351,6 +1351,36 @@
                   for the destination name in response to this message.
                 </entry>
               </row>
+              <row>
+                <entry><literal>ALLOW_INTERACTIVE_AUTHENTICATION</literal></entry>
+                <entry>0x4</entry>
+                <entry>This is a hint that may be set on a method call
+                message that informs the receiving side that the
+                caller is OK if possibly time-intensive interactive
+                user authentication may take place before the method
+                call will complete. A client may set this flag if it
+                is prepared to wait for a longer time before the
+                method call returns, and if its UI may be interrupted
+                by interactively querying the user for passwords or
+                confirmation. This flag is only useful when
+                unprivileged code calls a more priviliged method call,
+                and an authentication framework is deployed that
+                allows possibly interactive authentication. If no such
+                framework is deployed it has no effect. This flag
+                should not be set by default by client
+                implementations. If it is set the caller also should
+                set a suitably long timeout on the method call to make
+                sure the user interaction may complete. This flag is
+                only valid for method call messages, and shall be
+                ignored otherwise. If a this flag is not set on a
+                method call, and a service determines that the
+                requested operation is not allowed without interactive
+                authentication, but could be after successful
+                interactive authentication it should return the
+                <literal>org.freedesktop.DBus.Error.InteractiveAuthenticationRequired</literal>
+                error.
+                </entry>
+              </row>
             </tbody>
           </tgroup>
         </informaltable>
--
1.9.3



Lennart

--
Lennart Poettering, Red Hat