PolicyKit: Branch 'master'
David Zeuthen
david at kemper.freedesktop.org
Tue Jun 19 21:49:19 PDT 2007
doc/spec/Makefile.am | 4
doc/spec/polkit-spec-configuration.xml | 197 +++++++++++++++++++++++++++
doc/spec/polkit-spec-introduction.xml | 119 ++++++++++++++++
doc/spec/polkit-spec-model.xml | 238 +++++++++++++++++++++++++++++++++
doc/spec/polkit-spec.xml.in.in | 2
5 files changed, 558 insertions(+), 2 deletions(-)
New commits:
diff-tree b74cc6ed8830200f38119ca0dfd1e5c26c557a89 (from 8afbda8b8ea35fa5992541d420c37c1d6ca98724)
Author: David Zeuthen <davidz at redhat.com>
Date: Wed Jun 20 00:49:13 2007 -0400
add the spec
diff --git a/doc/spec/Makefile.am b/doc/spec/Makefile.am
index 5d885de..86e37f6 100644
--- a/doc/spec/Makefile.am
+++ b/doc/spec/Makefile.am
@@ -2,7 +2,9 @@
FIGURE_FILES =
SPEC_XML_EXTRA_FILES = \
- polkit-spec-introduction.xml
+ polkit-spec-introduction.xml \
+ polkit-spec-model.xml \
+ polkit-spec-configuration.xml
if DOCBOOK_DOCS_ENABLED
diff --git a/doc/spec/polkit-spec-configuration.xml b/doc/spec/polkit-spec-configuration.xml
new file mode 100644
index 0000000..707425b
--- /dev/null
+++ b/doc/spec/polkit-spec-configuration.xml
@@ -0,0 +1,197 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+<chapter id="polkit-conf">
+ <title>PolicyKit configuration</title>
+
+ <sect1>
+ <title>Declaring Actions</title>
+
+ <para>
+ A Mechanism needs to declare what Actions it supports. This is
+ achieved by dropping one or more XML files with the suffix <literal>.policy</literal>
+ into the <literal>/usr/share/PolicyKit/policy</literal> directory. An example:
+ </para>
+ <programlisting>
+ <![CDATA[
+<policyconfig>
+ <group id="polkit-gnome-examples">
+ <description>PolicyKit examples for PolicyKit-gnome</description>
+
+ <policy id="polkit-gnome-examples-frobnicate">
+ <description>Let the example Frobnicate</description>
+ <defaults>
+ <allow_inactive>no</allow_inactive>
+ <allow_active>auth_self</allow_active>
+ </defaults>
+ </policy>
+
+ <policy id="polkit-gnome-examples-tweak">
+ <description>Let the example Tweak</description>
+ <defaults>
+ <allow_inactive>no</allow_inactive>
+ <allow_active>auth_root</allow_active>
+ </defaults>
+ </policy>
+
+ <policy id="polkit-gnome-examples-twiddle">
+ <description>Twiddle</description>
+ <defaults>
+ <allow_inactive>no</allow_inactive>
+ <allow_active>auth_root_keep_always</allow_active>
+ </defaults>
+ </policy>
+
+ <policy id="polkit-gnome-examples-punch">
+ <description>Punch</description>
+ <defaults>
+ <allow_inactive>no</allow_inactive>
+ <allow_active>auth_self_keep_session</allow_active>
+ </defaults>
+ </policy>
+
+ </group>
+</policyconfig>
+]]>
+ </programlisting>
+ <para>
+ Here's a more real-world example from HAL:
+ </para>
+ <programlisting>
+ <![CDATA[
+<policyconfig>
+ <group id="hal-storage">
+ <description>Storage Drives and Media</description>
+
+ <policy id="hal-storage-mount-fixed">
+ <description>Mount file systems from internal drives</description>
+ <defaults>
+ <allow_inactive>no</allow_inactive>
+ <allow_active>auth_root_keep_always</allow_active>
+ </defaults>
+ </policy>
+
+ <policy id="hal-storage-unmount-others">
+ <description>Unmount file systems mounted by other users</description>
+ <defaults>
+ <allow_inactive>no</allow_inactive>
+ <allow_active>auth_root_keep_always</allow_active>
+ </defaults>
+ </policy>
+
+ </group>
+</policyconfig>
+]]>
+ </programlisting>
+ <para>
+ The policy declaration includes:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Action Identifier:</emphasis> This identifies
+ the action - it needs to be namespaced accordingly using
+ some unique name of the mechanism. This could be
+ e.g. <literal>dialup-connect-trusted</literal>
+ or <literal>dialup-connect-untrusted</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Defaults:</emphasis>
+ The <literal>allow_inactive</literal>
+ and <literal>allow_active</literal> specify the default
+ answer that <literal>libpolkit</literal> will return for
+ respectively inactive and active sessions. See below for
+ valid values and their meaning.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Grouping:</emphasis> This is purely for
+ organizational purposes. The group identifier needs to be
+ properly namespaced as well.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Textual descriptions:</emphasis> Simply included
+ for convenience and organizational purposes (TODO: think
+ about i18n).
+ </para>
+ </listitem>
+ </itemizedlist>
+ The following values for the defaults are
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>no</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>auth_self</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>auth_self_keep_session</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>auth_self_keep_always</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>auth_root</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>auth_root_keep_session</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>auth_root_keep_always</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>yes</emphasis>
+ </para>
+ </listitem>
+ </itemizedlist>
+ 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 <literal>dialup-connect-trusted</literal> Action to
+ return <emphasis>yes</emphasis> for local active sessions and
+ the Action
+ <literal>dialup-connect-untrusted</literal> to perhaps
+ return <emphasis>auth_root_keep_session</emphasis>. See
+ <xref linkend="beyond-defaults"/> for how individual machines
+ and sites can customize this.
+ </para>
+
+ <para>
+ The <literal>polkit-list-actions</literal>(1) tool will list all
+ the Actions known to <literal>libpolkit</literal> in a
+ convenient format.
+ </para>
+ </sect1>
+
+ <sect1 id="beyond-defaults">
+ <title>Beyond the Defaults</title>
+
+ <para>
+ TODO: To be written. Will include how machines and sites can
+ tweak what answer <literal>libpolkit</literal> returns depending
+ on the Action and Subject. For example it includes 1) locking
+ down a guest account; 2) discriminating depending on uid, gid,
+ SELinux context, exec-path.
+ </para>
+ </sect1>
+
+</chapter>
diff --git a/doc/spec/polkit-spec-introduction.xml b/doc/spec/polkit-spec-introduction.xml
index 32a575e..ffb309b 100644
--- a/doc/spec/polkit-spec-introduction.xml
+++ b/doc/spec/polkit-spec-introduction.xml
@@ -8,8 +8,125 @@
<title>About</title>
<para>
- TODO; write me!
+ PolicyKit is a toolkit for defining and handling the policy that
+ allows unprivileged processes to speak to privileged processes:
+ It is a framework for centralizing the decision making process
+ with respect to granting access to privileged operations for
+ unprivileged applications. PolicyKit is specifically targeting
+ applications in rich desktop environments on multi-user
+ UNIX-like operating systems.
</para>
+ </sect1>
+
+ <sect1>
+ <title>History and Prior Art</title>
+ <para>
+ Traditionally UNIX-like operating systems have a clear
+ distinction between ordinary unprivileged users and the almight
+ and powerful super user 'root'. However, in order for a user to
+ access and configure hardware additional privileges and rights
+ are needed. Hitherto, this have been done in a number of often
+ OS-specific ways. For example, Red Hat based systems usually
+ grant access to devices to a user if, and only if, the user is
+ logged in at a local console. In contrast, Debian-based systems
+ often relies on group membership, e.g. users in the 'cdrom'
+ group can access optical drives, users in the 'plugdev' group
+ can mount removable media and so on.
+ </para>
+
+ <para>
+ In addition, access was not only granted to devices; Red
+ Hat-based systems, for example, provides a mechanism to allow a
+ user at a local system to run certain applications (such as the
+ system-config-* family) as the super user provided they could
+ authenticate as the super user (typically by entering the root
+ password using a graphical utility). Other distributions rely on
+ sudo (with various graphical frontends) to provide similar
+ functionality. Both the pam-console and sudo approaches doesn't
+ require applications to be modified.
+ </para>
+
+ <para>
+ Finally, some classes of software (such as HAL, NetworkManager
+ and gnome-system-tools) utilizes IPC mechanism (typically D-Bus)
+ to provide a very narrow and well-defined subset of privileged
+ operations to unprivileged desktop applications. It varies what
+ mechanism is used to deny users.
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Defining the Problem</title>
+
+ <para>
+ There's a couple of problems with the status quo
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Mechanisms are coarsely grained: either you're at the
+ console or you're not (pam_console). Either you're a
+ member of a group or you're not (Debian). There is no easy
+ way to specify that only a subset of privileged operations
+ should be available for a given user (e.g. it's hard to
+ express "it's fine to mount removable media; it's not fine
+ to mount fixed media; it's not fine to change the
+ timezone" in a coherent way).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The way most people use pam-console and sudo is
+ fundamentally broken. Full-fledged GTK+ or Qt applications
+ as the super user which means that millions of line of
+ code (including code such as image loaders that
+ historically have lots of security problems) runs
+ privileged. This is in direct violation of the well-known
+ "least privilege" principle. In addition, often
+ applications look out of place because settings in such
+ programs now read per-user settings from root's home
+ directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ UNIX group membership have always been problematic; if a
+ user is a member of a group once, he can always become
+ member of the group again
+ (copy <literal>/bin/bash</literal> to $HOME; chown to
+ group, set the setgid bit, done).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ It is difficult for upstream projects (such as GNOME or
+ KDE) to implement features that requires administrative
+ privileges because most downstream consumers
+ (e.g. operating systems) have different ways of
+ implementing access control. As a result most of these
+ features are punted to OS distributors who have their own
+ code for doing the same thing e.g. setting the
+ date/timezone etc.; there is no way for file sharing
+ applications (such as gnome-user-share, Banshee,
+ Rhythmbox) to punch a hole in the firewall.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Without a centralized framework, access control
+ configuration is often scattered throughout the system
+ which makes it hard for system administrators to grasp how
+ to configure the system.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
</sect1>
+
</chapter>
diff --git a/doc/spec/polkit-spec-model.xml b/doc/spec/polkit-spec-model.xml
new file mode 100644
index 0000000..1af809a
--- /dev/null
+++ b/doc/spec/polkit-spec-model.xml
@@ -0,0 +1,238 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+<chapter id="model">
+ <title>PolicyKit Model</title>
+
+ <sect1>
+ <title>Mechanims vs. Policy</title>
+
+ <para>
+ PolicyKit assumes a model where a program is split into two
+ parts. One part, the Mechanism, runs privileged (with no user
+ interface elements) and the other part, the policy agent, runs
+ unprivileged. The two parts of the program are in different
+ processes and communicate through some IPC mechanism such as
+ pipes or the system message bus (D-Bus). In some instances the
+ Mechanism can be considered part of the core OS and the policy
+ agent part of the desktop stack.
+ </para>
+
+ <para>
+ A Mechanism should never trust any application that tries to
+ use; it needs to carefully verify all data and requests passed
+ to it from the application. This is the model employed by HAL
+ and NetworkManager:
+ </para>
+
+ <para>
+ (TODO: diagram showing g-p-m, g-v-m, nm-applet, HAL and NM)
+ </para>
+
+ <para>
+ This model also applies to other security sensitive
+ applications:
+ </para>
+
+ <para>
+ (TODO: diagram showing 1) gnome-screensaver / PAM-stack +
+ /sbin/unix_chkpwd; and 2) gdm + gdm-greeter; 3) mount(8); 4)
+ other setuid examples)
+ </para>
+
+ <para>
+ In general, such an architecture is thought of as secure as long
+ as the Mechanism (and it's dependent libraries) have been
+ verified to be secure.
+ </para>
+
+ </sect1>
+
+ <sect1>
+ <title>Concepts</title>
+
+ <para>
+ Typically the entities that a Mechanism cares about can be split
+ into three groups:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Subject</emphasis>: the entity requesting the
+ Action; ie. an unprivileged application. To make a
+ decision about whether to carry out the Action, the
+ Mechanism needs to know as much about the Subject as
+ possible, e.g. UNIX user id, UNIX process id, possible
+ security attributes (such as SELinux security context) and
+ other data such as if the Subject is a participant in a
+ local or remote desktop session, whether said desktop
+ session is currently active and so forth.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Object</emphasis>: some canonical representation
+ of the Object; some Objects represent tangible things such
+ as a UNIX device file, other Objects can be more abstract
+ and represent e.g. a network connection to a specific
+ destination, a reference to the power management
+ subsystem, a reference to a piece of software tracked by
+ the native package manager.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Action:</emphasis> what the Subject is
+ attempting to do to the Object; this depends of the nature
+ of the Object and examples include mounting a block
+ device, formatting a block device with a file system,
+ establishing a dial-up connection to connect to private or
+ public networks, putting the system into a suspended
+ state, installing an unsigned piece of software, updating
+ the system with signed software, changing the timezone,
+ gaining access to a webcam and so forth.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ (TODO: mention that libpolkit represents the Subject as either a
+ Caller (e.g. a process) or a Session (e.g. a group of processes
+ in a desktop session) and what the implications are here;
+ e.g. for granting/removing ACL's on device
+ nodes. etc. etc. etc.)
+ </para>
+
+ <para>
+ One way to think about a Mechanism is that the Mechanism is
+ split into an enforcer and a decider component. When an
+ application attempts to access the Mechanism, the enforcer
+ component will only carry out the Action if the decider
+ component (supplied with the appropriate input parameters about
+ the Subject, Object and Action) says it's OK.
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Theory of Operation</title>
+
+ <para>
+ 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 <literal>libpolkit</literal> and the Mechanism to
+ describe the Subject and Action in question. The Mechanism
+ should think about <literal>libpolkit</literal> 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 <xref linkend="polkit-conf"/>
+ for details on PolicyKit configuration.
+ </para>
+
+ <para>
+ The answer from <literal>libpolkit</literal> is not limited to a
+ boolean value; essentially the following values can be returned
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Yes:</emphasis> It is ok for the Mechanism to
+ carry out the Action requsted by the given Subject.
+ </para>
+
+ <para>
+ <emphasis>No:</emphasis> The Mechanism should not carry
+ out the Action requested by the given Subject.
+ </para>
+
+ <para>
+ <emphasis>Require authentication:</emphasis> The Subject
+ (e.g. the UI application) needs to ask the user to
+ authenticate in order for the Mechanism to carry out this
+ Action.
+ </para>
+ </listitem>
+ </itemizedlist>
+ In addition,
+ <itemizedlist>
+ <listitem>
+ <para>
+ Authentication can be specified (in the return value
+ from <literal>libpolkit</literal>) 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).
+ </para>
+
+ <para>
+ The authorization can be kept (this is also specified in
+ the return value from <literal>libpolkit</literal>) 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.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ To facilitate the authentication step, there's a shared library
+ called <literal>libpolkit-grant</literal>. Given an Action, this
+ library uses a privileged helper (as in it's a <literal>setgid
+ polkit</literal> 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 <literal>libpolkit</literal> to
+ return <emphasis>Yes</emphasis> when the Subject asks the
+ Mechanism to carry out the Action again.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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 <literal>/var/lib/dialup-helper/trusted-dialup.d</literal>
+ 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 <literal>dialup-connect-trusted</literal>. If it's not in the
+ white-list, the Action will be
+ <literal>dialup-connect-untrusted</literal>. 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 <literal>dialup-connect-trusted</literal> for local
+ active sessions and always require authentication for the Action
+ <literal>dialup-connect-untrusted</literal>.
+ </para>
+
+ <para>
+ When authentication is involved, the interaction diagram for
+ having a Mechanism carry out an Action on behalf of a Subject
+ looks roughly like this
+ </para>
+ <para>
+ TODO: include diagram
+ </para>
+ </sect1>
+
+</chapter>
diff --git a/doc/spec/polkit-spec.xml.in.in b/doc/spec/polkit-spec.xml.in.in
index ff6ec40..5174747 100644
--- a/doc/spec/polkit-spec.xml.in.in
+++ b/doc/spec/polkit-spec.xml.in.in
@@ -20,5 +20,7 @@
</bookinfo>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="polkit-spec-introduction.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="polkit-spec-model.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="polkit-spec-configuration.xml" />
</book>
More information about the hal-commit
mailing list