![]() |
![]() |
![]() |
PolicyKit Library Reference Manual | ![]() |
---|
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
Yes: It is ok for the Mechanism to carry out the Action requsted by the given Subject.
No: The Mechanism should not carry out the Action requested by the given Subject.
Require authentication: The Subject (e.g. the UI application) needs to ask the user to authenticate in order for the Mechanism to carry out this Action.
In addition,
Authentication can be specified (in the return value
from libpolkit
) as either user
authentication (user puts in his own password) or super
user authentication (user puts in the root password or a
user in an administrator group authenticates).
The authorization can be kept (this is also specified in
the return value from libpolkit
) either
1) indefinitely (e.g. it persists across reboots and
different desktop sessions); 2) for the remainer of the
desktop session the Subject is part of; or 3) confined to
the process life-time of the Subject.
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