![]() |
![]() |
![]() |
PolicyKit Library Reference Manual | ![]() |
---|
A Mechanism needs to declare what Actions it supports. This is
achieved by dropping one or more XML files with the suffix .policy
into the /usr/share/PolicyKit/policy
directory.
The name of the XML file is significant. Each XML file can only
declare actions from the namespace of it's own name; for example
actions org.foobar.action-a
, org.foobar.action-b
and org.foobar.action-c
would all go into the
file org.foobar.policy
while
actions com.my-company.product-awesome.action-a
, com.mycompany.product-awesome.action-b
would go into the
file com.mycompany.product-awesome.policy
.
An example of a .policy
file would be the following:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE policyconfig PUBLIC "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN" "http://www.freedesktop.org/standards/PolicyKit/1.0/policyconfig.dtd"> <policyconfig> <vendor>The PolicyKit Project</vendor> <vendor_url>http://hal.freedesktop.org/docs/PolicyKit/</vendor_url> <icon_name>polkit-icon</icon_name> <action id="org.gnome.policykit.examples.frobnicate"> <description>Frobnicate</description> <description xml:lang="da">Frobniker</description> <description xml:lang="en_CA">Frobnicate, Aye!</description> <message>System policy prevents the PolicyKit-gnome example helper from Frobnicating</message> <message xml:lang="da">System indstillinger forhindrer PolicyKit-gnome eksempel hjælper i at Frobnikere!</message> <message xml:lang="en_CA">System policy prevents the PolicyKit-gnome example helper from Frobnicating, Aye!</message> <icon_name>polkit-icon-frobnicate</icon_name> <vendor_url>http://hal.freedesktop.org/docs/PolicyKit/about-frobnicating</vendor_url> <defaults> <allow_any>no</allow_any> <allow_inactive>no</allow_inactive> <allow_active>auth_self</allow_active> </defaults> </action> <action id="org.gnome.policykit.examples.tweak"> <description>Tweak</description> <description xml:lang="da">Tvæk</description> <description xml:lang="en_CA">Tweak, Aye!</description> <message>System policy prevents the PolicyKit-gnome example helper from Tweaking</message> <message xml:lang="da">System indstillinger forhindrer PolicyKit-gnome eksempel hjælper i at Tvække!</message> <message xml:lang="en_CA">System policy prevents the PolicyKit-gnome example helper from Tweaking, Aye!</message> <!-- just inherit icon_name and vendor_url --> <defaults> <allow_any>no</allow_any> <allow_inactive>no</allow_inactive> <allow_active>auth_admin</allow_active> </defaults> </action> </policyconfig>
The policy declaration includes:
Action Identifier: This identifies
the action and can only contain the
characters [a-z][0-9].-
,
e.g. lower-case ASCII, digits, period and hyphen. In
addition the identifier needs to start with a lower-case
ASCII character. The rationale for having everything is
lower case is to make it easy to make a distinction
between PolicyKit actions and D-Bus methods / interfaces
as the latter is normally using CamelCase.
In order for the identifier to be unique, it is
recommended that a revser domain name is chosen, for
example if the company Acme Inc. has a product called
Frakker that exports two Actions Blit and Blop the action
names should be chosen
as com.acme.frakker.blit
and com.acme.frakker.blop
.
Defaults:
The allow_any
, allow_inactive
and allow_active
tags specify the
default answer that libpolkit
will
return for respectively any, inactive and active
sessions. See below for valid values and their
meaning. Any of these elements, including the
enclosing defaults
elements may be
omitted.
Textual descriptions: Simply included
for convenience and organizational purposes. Useful for
graphical editors for
authorizations. Standard xml:lang
mechnanisms are used to convey localized strings (note
that intltool 0.36 or greater includes native support for
handling .policy
files).
Vendor: The vendor
and vendor_url
describes who is
supplying the action. Both can be set at the top-level of
the .policy
file and each Action can
further override it. These tags are optional.
Icon:
The icon_name
tag can be used to
specify an icon name for the action or group of
actions. The name must adhere to the freedesktop.org Icon
Naming spec (for theming purposes) and cannot include
directory separators and must not include filename
extensions like .png
. Like with vendor
tags, this tag can be set at the top level and also be
specialized for each individual action. This tag is
optional.
The following values for the defaults are
no
auth_self_one_shot
auth_self
auth_self_keep_session
auth_self_keep_always
auth_admin_one_shot
auth_admin
auth_admin_keep_session
auth_admin_keep_always
yes
The main point here is that individual upstream software
projects can provide sensible defaults, e.g. it's sensible for
the example with a dial-up mechanism to configure
the org.freedesktop.networkmanager.dialup-trusted
Action to
return yes for local active sessions and
the Action
org.freedesktop.networkmanager.dialup-untrusted
to perhaps
return auth_admin_keep_session. See
the section called “Beyond the Defaults” for how individual machines
and sites can customize this.
The polkit-list-actions
(1) tool will list all
the Actions known to libpolkit
in a
convenient
format. The polkit-policy-file-validate
(1)
tool can be used to check policy files as part of the software
release and installation process.
When declaring an Action, one can also annotate it with one or more key/value pairs:
<action id="com.example.blahblaster.run-as-root"> <description>Run the graphical BlahBlaster application as the super user</description> <message>System policy prevents the BlahBlaster application</message> <defaults> <allow_inactive>no</allow_inactive> <allow_active>auth_admin</allow_active> </defaults> <annotate key="org.freedesktop.PolicyKit.run-as-superuser.path">/usr/bin/BlahBlaster</annotate> </action>
This is useful when writing an extensible Mechanism that other
applications wants to use. The example declaration above is
dealing with an (hypothetical and setuid root) mechanism,
let's call it
run-as-superuser
, that can start graphical
applications as uid 0. Suppose the user invokes it like this
run-as-superuser /usr/bin/BlahBlaster
Now, the run-as-superuser
mechanism is only
passed a path to the application to start. In order to
determine if the calling user is allowed to run the given
application as root, we need to determine the PolicyKit Action
and then use libpolkit as usual to get an answer (and possibly
make the user authenticate to gain the privilege to run the
application). By using annotations,
the run-as-superuser
mechanism can query
what the action is simply by searching for the Action that has
an annotation
where org.freedesktop.PolicyKit.run-as-superuser.path
equals the given path,
e.g. /usr/bin/BlahBlaster
. It then becomes
part of the documentation for
the run-as-superuser
program to specify
that applications wanting to use it, simply just needs to
provide a PolicyKit .policy
file that
declares an Action with an
annotation org.freedesktop.PolicyKit.run-as-superuser.path
whose value is the path to the binary.