![]() |
![]() |
PolicyKit-gnome Library Reference Manual | ![]() |
---|
This part discusses the GNOME/GTK+ specific Authentication Agent.
The PolicyKit model provides letting an user authenticate in order to gain the privilege to let a Mechanism carry work out related to a specific Action on the users behalf. In the PolicyKit libraries, this functionality is programmatically exposed in the PolKitGrant class. As it's tedious to use this low-level functionality from a GTK+ or GNOME application, the high-level functionality is wrapped in a D-Bus service available on the session message bus. The way it works is that when an application needs privileges, it can call into this D-Bus service and an authentication dialog will appear. When the user is done with the authentication dialog, the application recieves a reply from the D-Bus containing a boolean indicating whether the user gained the privilege or not.
The D-Bus service is available on the session message bus with
the
name org.freedesktop.PolicyKit.AuthenticationAgent
and exports a single object /
that
implements the
interface org.freedesktop.PolicyKit.AuthenticationAgent
. The
D-Bus introspection XML looks like this
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> <node name="/"> <!-- this interface is deprecated and will be removed in a future release --> <interface name="org.gnome.PolicyKit.Manager"> <method name="ShowDialog"> <annotation name="org.freedesktop.DBus.GLib.Async" value=""/> <!-- IN: PolicyKit action identifier; see PolKitAction --> <arg name="action_id" direction="in" type="s"/> <!-- IN: X11 window ID for the top-level X11 window the dialog will be transient for. --> <arg name="xid" direction="in" type="u"/> <!-- OUT: whether the user gained the authorization --> <arg name="gained_authorization" direction="out" type="b"/> </method> </interface> <interface name="org.freedesktop.PolicyKit.AuthenticationAgent"> <method name="ObtainAuthorization"> <annotation name="org.freedesktop.DBus.GLib.Async" value=""/> <!-- IN: PolicyKit action identifier; see PolKitAction --> <arg name="action_id" direction="in" type="s"/> <!-- IN: X11 window ID for the top-level X11 window the dialog will be transient for. --> <arg name="xid" direction="in" type="u"/> <!-- IN: Process ID to grant authorization to --> <arg name="pid" direction="in" type="u"/> <!-- OUT: whether the user gained the authorization --> <arg name="gained_authorization" direction="out" type="b"/> </method> </interface> </node>
The ObtainAuthorization()
method may throw
an exception if another client is currently using the service
to show an authentication dialog. In practice this should
never happen because the authentication daemon grabs the X11
keyboard and pointer thus preventing the user from activating
widgets in other applications that would lead to calling into
the ObtainAuthorization
method.
The authentication daemon uses
libpolkit-grant
which in turn uses PAM for
authentication services (however, other authentication
back-ends can be plugged in as required). As such, a wide
range of authentication mechanisms are available.
The authentication daemon is using D-Bus activation and exits after 30 seconds of inactivity. Thus the code implementing this dialog only runs when necessary.
The appearance of the authentication dialog depends on the
result from PolicyKit and also whether administrator
authentication is defined as "authenticate as the root user"
or "authenticate as one of the users from UNIX group wheel" or
however the PolicyKit library is configured (see
the PolicyKit.conf(5)
manual page for
details). Note that some of the screenshots below were made on
a system set up to use
the ThinkFinger
PAM module.
The text shown in the authentication dialogs stems from the
PolicyKit .policy
XML files residing
in /usr/share/PolicyKit/policy
and is read
by the authentication daemon when an applications uses
the ShowDialog()
method. Thus, what the
user sees is not under application control (e.g. it's not
passed from the application) which rules out a class of
attacks where applications are trying to fool the user into
gaining a privilege.
Authentication dialog where the user is asked to authenticate as herself:
Authentication dialog where the user is asked to authenticate as an administrative user and PolicyKit is configured to use the root password for this:
Authentication dialog where the user is asked to authenticate as an administrative user and PolicyKit is configured to use the UNIX wheel group for this:
Same authentication dialog, showing drop down box where the user can be selected:
Authentication dialog showing an Action where the privilege can be retained indefinitely:
Authentication dialog showing an Action where the privilege can be retained only for the remainer of the desktop session:
The details view detailing what Action is being asked for as well as what application is requesting the authentication: