Policy Kit Configuration - Declaring Actions/Annotations

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.