diff options
| author | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2014-09-25 13:19:24 +0100 |
|---|---|---|
| committer | Lennart Poettering <lennart@poettering.net> | 2014-10-28 15:03:06 +0100 |
| commit | 66b15d177967fe8da5a830a4d6b3cb301df1d164 (patch) | |
| tree | 7bda65699e281924ca160d54dfeb34ba1fd51bff /doc | |
| parent | 8ad6a5575f5a904359e2331c711f94265d767e68 (diff) | |
| download | dbus-66b15d177967fe8da5a830a4d6b3cb301df1d164.tar.gz | |
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
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/dbus-specification.xml | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 71a8987d..37ff2ca0 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -1399,6 +1399,66 @@ for the destination name in response to this message. </entry> </row> + <row> + <entry><literal>ALLOW_INTERACTIVE_AUTHORIZATION</literal></entry> + <entry>0x4</entry> + <entry> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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 + <literal>org.freedesktop.DBus.Error.InteractiveAuthorizationRequired</literal> + error. + </para> + <para> + 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. + </para> + </entry> + </row> </tbody> </tgroup> </informaltable> |