From 66b15d177967fe8da5a830a4d6b3cb301df1d164 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Thu, 25 Sep 2014 13:19:24 +0100 Subject: [PATCH] dbus-spec, dbus-protocol: add ALLOW_INTERACTIVE_AUTHORIZATION flag Heavily based on a patch from Lennart Poettering. 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 we checked indeed ignore any new flags, hence we should be fine with compatibility here. Bug: https://bugs.freedesktop.org/show_bug.cgi?id=83449 --- dbus/dbus-protocol.h | 9 +++++++ doc/dbus-specification.xml | 60 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+) diff --git a/dbus/dbus-protocol.h b/dbus/dbus-protocol.h index 60605ab..933c365 100644 --- a/dbus/dbus-protocol.h +++ b/dbus/dbus-protocol.h @@ -254,6 +254,11 @@ extern "C" { * message. */ #define DBUS_HEADER_FLAG_NO_AUTO_START 0x2 +/** + * If set on a method call, this flag means that the caller is prepared to + * wait for interactive authorization. + */ +#define DBUS_HEADER_FLAG_ALLOW_INTERACTIVE_AUTHORIZATION 0x4 /* Header fields */ @@ -446,6 +451,10 @@ extern "C" { /** The message meta data does not match the payload. e.g. expected number of file descriptors were not sent over the socket this message was received on. */ #define DBUS_ERROR_INCONSISTENT_MESSAGE "org.freedesktop.DBus.Error.InconsistentMessage" +/** The message is not allowed without performing interactive authorization, + * but could have succeeded if an interactive authorization step was + * allowed. */ +#define DBUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED "org.freedesktop.DBus.Error.InteractiveAuthorizationRequired" /* XML introspection format */ diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 71a8987..37ff2ca 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -1399,6 +1399,66 @@ for the destination name in response to this message. + + ALLOW_INTERACTIVE_AUTHORIZATION + 0x4 + + + This flag may be set on a method call message to + inform the receiving side that the caller is prepared + to wait for interactive authorization, which might + take a considerable time to complete. For instance, + if this flag is set, it would be appropriate to + query the user for passwords or confirmation via + Polkit or a similar framework. + + + This flag is only useful when + unprivileged code calls a more privileged method call, + and an authorization framework is deployed that allows + possibly interactive authorization. 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 should also 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. + + + Interaction that takes place as a part of the + effect of the method being called is outside the scope + of this flag, even if it could also be characterized + as authentication or authorization. For instance, in + a method call that directs a network management service + to attempt to connect to a virtual private network, + this flag should control how the network management + service makes the decision "is this user allowed to + change system network configuration?", but it should + not affect how or whether the network management + service interacts with the user to obtain the credentials + that are required for access to the VPN. + + + If a this flag is not set on a method call, and a + service determines that the requested operation is + not allowed without interactive authorization, but + could be allowed after successful interactive + authorization, it may return the + org.freedesktop.DBus.Error.InteractiveAuthorizationRequired + error. + + + The absence of this flag does not guarantee that + interactive authorization will not be applied, since + existing services that pre-date this flag might + already use interactive authorization. However, + existing D-Bus APIs that will use interactive + authorization should document that the call may take + longer than usual, and new D-Bus APIs should avoid + interactive authorization in the absence of this flag. + + + -- 2.7.4