Theory of Operation

The core of PolicyKit is implemented as a shared library that Mechanisms can link to and use as the decider component. There's a small set of (extensible) data structures that establish a vocabulary for libpolkit and the Mechanism to describe the Subject and Action in question. The Mechanism should think about libpolkit as a black box; it's sole purpose is to answer whether a given Subject is permitted to do a specific Action. The answer, obviously, comes from a configuration source read by the library and maintained by the system administrator; see PolicyKit configuration for details on PolicyKit configuration.

The answer from libpolkit is not limited to a boolean value; essentially the following values can be returned

In addition,

To facilitate the authentication step, there's a shared library called libpolkit-grant. Given an Action, this library uses a privileged helper (as in it's a setgid polkit application) to authenticate the user (using PAM) and upon successful authentication leave a cookie specifying that the given Action can be carried out. It is the presence and contents of this cookie that will allow libpolkit to return Yes when the Subject asks the Mechanism to carry out the Action again.

In order to keep the PolicyKit model reasonably simple, there is no representation of the Object. Instead, a Mechanism that cares about Objects (and many don't; for example, Mechanisms to change the timezone, punch a hole in the firewall or add a user all operate on a singleton Object: the system as a whole) must instead divide a given Action into multiple sub-Actions depending on the nature of the Object.

For example, consider a Mechanism for dial-up networking. Here, the Subject is a UI applet running in a desktop session, the Object is the phone number to dial and the Action is to establish the connection (another Action could be to hang-up an existing connection). Suppose that the Mechanism has a white-list of phone numbers that are trusted; this could simply be a directory /var/lib/dialup-helper/trusted-dialup.d where the system administrator can drop simple text or XML files with phone numbers that are considered safe to dial. If the phone number given by the client matches this white-list, the Mechanism chooses the Action to be dialup-connect-trusted. If it's not in the white-list, the Action will be dialup-connect-untrusted. Hence, depending on how PolicyKit is configured it may return different answers since these are different Actions; one sensible thing in a default desktop rollout would be to always allow the Action dialup-connect-trusted for local active sessions and always require authentication for the Action dialup-connect-untrusted.

When authentication is involved, the interaction diagram for having a Mechanism carry out an Action on behalf of a Subject looks roughly like this

TODO: include diagram