- Table of Contents
- 1. Introduction
- 1.1. About
- 2. Theory of operation
- 2.1. Privileges
- 2.2. Architecture
- 2.3. Example
- 3. Resources
- 3.1. Resource Identifiers
- 4. Privileges
Chapter 1. Introduction
1.1. About
PolicyKit is a system for enabling unprivileged desktop +=======
Table of Contents
Table of Contents
Chapter 2. Theory of operation
2.1. Privileges
One major concept of the PolicyKit system is the notion of + privileges; a PolicyKit privilege +=======
Table of Contents
One major concept of the PolicyKit system is the notion of privileges; a PolicyKit privilege +>>>>>>> 1.7 (referred to simply as +<<<<<<< polkit-spec.html + privilege in the following) is something +======= privilege in the following) is something +>>>>>>> 1.7 that a given user may or may not possess. The thinking behind PolicyKit is that privileged system level components offer functionality to unprivileged desktop applications as D-BUS @@ -16,9 +257,31 @@ a flexible security policy defining the set of users that are allowed to invoke a method, the system level component defines a set of +<<<<<<< polkit-spec.html + privileges. +
The PolicyKit system is basically client/server and is
+>>>>>>> 1.7
implemented as the
system-wide org.freedesktop.PolicyKit D-BUS
service. This D-BUS service serves two purposes
@@ -33,19 +296,103 @@
In addition, the PolicyKit system includes client side libraries and command-line utilities wrapping the D-BUS API of +<<<<<<< polkit-spec.html + the org.freedesktop.PolicyKit service. +
2.3. Example
As an example, HAL exports the method Mount
+=======
the org.freedesktop.PolicyKit service.
As an example, HAL exports the method Mount
+>>>>>>> 1.7
on the
org.freedesktop.Hal.Device.Volume interface
for each hal device object of
+<<<<<<< polkit-spec.html
+ capability volume. HAL defines a number
+=======
capability volume. HAL defines a number
+>>>>>>> 1.7
of privileges for mounting
+<<<<<<< polkit-spec.html
+ including hal-storage-fixed-mount
+ and hal-storage-removable-mount. Depending
+=======
including hal-storage-fixed-mount
and hal-storage-removable-mount. Depending
+>>>>>>> 1.7
on the whether the volume stems from a fixed hard disk or a
hotpluggable/removable drive, HAL requires the calling user to
possess either
+<<<<<<< polkit-spec.html
+ the hal-storage-fixed-mount
+ or hal-storage-removable-mount privilege
+ in order to carry out the Mount method.
+
Upon a user invoking the Mount method, HAL
+ simply asks the org.freedesktop.PolicyKit
+ D-BUS service if the calling user posses this privilege and if
+ this is not the case the Mount method
+=======
the hal-storage-fixed-mount
or hal-storage-removable-mount privilege
in order to carry out the Mount method.
@@ -54,15 +401,43 @@
simply asks the org.freedesktop.PolicyKit
D-BUS service if the calling user possess this privilege and if
this is not the case the Mount method
+>>>>>>> 1.7
throws
the org.freedesktop.Hal.Device.PermissionDeniedByPolicy
exception. Notably, this exception will tell the caller what
privilege the calling user needs to possess,
+<<<<<<< polkit-spec.html
+ e.g. either hal-storage-fixed-mount
+ or hal-storage-removable-mount.
+
Should the Mount method fail with the + exception PermissionDeniedByPolicy the +======= e.g. either hal-storage-fixed-mount or hal-storage-removable-mount.
Should the Mount method fail with the
exception PermissionDeniedByPolicy the
+>>>>>>> 1.7
caller now knows what privilege is required. The caller can
now initiate a dialogue with the PolicyKit
service to obtain this privilege. This conversation is
@@ -77,12 +452,48 @@
process crash while holding a privilege,
the PolicyKit service will be notifed and
the privilege will automatically be revoked.
+<<<<<<< polkit-spec.html
+
Hence, PolicyKit has the notion of + both permament + and temporary privileges. The latter may +=======
Hence, PolicyKit has the notion of
both permament
and temporary privileges. The latter may
+>>>>>>> 1.7
even be restricted such that only callers from the D-BUS
connection (remember, D-BUS connections has unique names)
+<<<<<<< polkit-spec.html
+ obtaining the privilege may use the obtained privilege.
+
In addition, privileges may be restricted to + certain resources; this is discussed in +======= obtaining the privilege may use the obtained privilege. Consequently, if a temporary privilege is restricted to a certain D-BUS connection, it is revoked when @@ -91,7 +502,36 @@
In addition, privileges may be restricted to certain resources; this is discussed in +>>>>>>> 1.7 more detail in XXX. +<<<<<<< polkit-spec.html +
+
The whole example is outlined in the diagram above. +
Table of Contents
PolicyKit allows granting privileges only on certain resources. For example, for HAL, it +>>>>>>> 1.7 is possible to grant the +<<<<<<< polkit-spec.html + privilege hal-storage-fixed-mount to the +======= privilege hal-storage-fixed-mount to the +>>>>>>> 1.7 user with uid 500 but only for the HAL device object +<<<<<<< polkit-spec.html + representing e.g. the /dev/hda3 partition. +
3.1. Resource Identifiers
Resource identifers are prefixed with a name identifying
+=======
representing e.g. the /dev/hda3 partition.
Resource identifers are prefixed with a name identifying +>>>>>>> 1.7 what service they belong to. The following resource identifiers are defined +<<<<<<< polkit-spec.html +
hal:// + HAL Unique Device Identifiers also known as HAL UID's. Example: hal:///org/freedesktop/Hal/devices/volume_uuid_1a28b356_9955_44f9_b268_6ed6639978f5 +
Chapter 4. Privileges
4.1. Privilege Descriptors
+ Applications, such as HAL, installs privilege descriptors using the polkit-policy-descriptor-install commandline utility. The descriptor contains the following information +
Criteria for determining if a given user possess the privilege on a given resource. +
What other privileges a given user must also possess. +
Information on whether the user can obtain the privilege, and if he can, whether only temporarily or permanently. +
Whether a user with the privilege may permanently grant it to other users. +
4.2. File Format
A developer of a system-wide application wanting to define a +=======
hal://HAL Unique Device Identifiers also known as HAL UID's. Example:hal:///org/freedesktop/Hal/devices/volume_uuid_1a28b356_9955_44f9_b268_6ed6639978f5@@ -130,11 +683,19 @@ Whether a user with the privilege may permanently grant it to other users.
A developer of a system-wide application wanting to define a
+>>>>>>> 1.7
privilege must create a privilege descriptor. This is a a
simple .ini-like config file. Here is what
the skeleton looks like:
+<<<<<<< polkit-spec.html
+
[Policy]
+=======
[Policy]
+>>>>>>> 1.7
RequiredPrivileges=
SufficientPrivileges=
Allow=
@@ -142,10 +703,52 @@
CanObtain=
CanGrant=
ObtainRequireRoot=
+<<<<<<< polkit-spec.html
+ ObtainPAMService=
+
4.2.1. RequiredPrivileges: Required Privileges
This is a list of privileges the user must possess in order
+=======
This is a list of privileges the user must possess in order
+>>>>>>> 1.7
to possess the given privilege. If the user doesn't possess
all of these privileges he is not considered to possess the
+<<<<<<< polkit-spec.html
+ given privilege. The list may be empty.
+
4.2.2. Allow, Deny: Criteria for Possesing a Privilege
Both Allow and Deny
+=======
given privilege. The list may be empty. A privilege in this
list is considered being possessed if the user is privileged
for one or more resources. E.g., if foo
@@ -161,6 +764,7 @@
just having this privilege on one resource is sufficient.
Both Allow and Deny
+>>>>>>> 1.7
contains lists describing what users are allowed
respectively denied the privilege. The elements of in each
list are of the form
@@ -230,6 +834,34 @@
All users expect those in
the normalstaff group posseses this
privilege.
+<<<<<<< polkit-spec.html
+
4.2.3. CanObtain: Obtaining Privileges
This property denotes whether an user can obtain the
+ privilege by authentication. It can assume the values
+ True (the user can obtain the privilege
+ permanently), Temporary (the user can
+=======
This property denotes whether an user can obtain the
privilege by authentication. This is useful when either
@@ -240,7 +872,141 @@
The property can assume the values
True (the user can obtain the privilege
permanently), Temporary (the user can
+>>>>>>> 1.7
only obtain the privilege temporarily) and
+<<<<<<< polkit-spec.html
+ False (the user can never obtain the
+ privilege through authentication).
+
The authentication required are specified in
+ the ObtainRequireRoot
+ and ObtainPAMService properties.
+
4.2.4. CanGrant: Granting Privileges
This property (it can assume the
+ values True and False)
+ describes whether an user with the given privilege can grant
+ it to other users, e.g. modify the Allow
+ and Deny properties.
+
The property CanObtain needs to have the
+ value True if this property assumes the
+ value True.
+
4.2.5. ObtainRequireRoot, ObtainPAMService: Authentication Requirements
If the property CanObtain assumes the
+ value True
+ or Temporary it means the user can
+ authenticate to gain a privilege.
+
The ObtainRequireRoot property specifies
+ whether authentication requires the super user password
+ (True) or the users own password
+ (False). In addition, it can be specified
+ what PAM service (for example pam_rps) is
+ to be used for authentication through the
+ property ObtainPAMService.
+
False (the user can never obtain the
privilege through authentication).
@@ -382,3 +1148,4 @@ ObtainRequireRoot=False display ":0") and one cannot assign meaning to it. In the future, it may be possible to assign meaning to it.