PolicyKit: Branch 'master'
David Zeuthen
david at kemper.freedesktop.org
Wed Jul 15 15:59:25 PDT 2009
docs/man/Makefile.am | 2
docs/man/pklocalauthority.xml | 317 +++++++++++++++++++++++++++++++
docs/man/polkit.xml | 30 +-
docs/polkit/Makefile.am | 1
docs/polkit/polkit-1-docs.xml | 1
src/polkitbackend/50-localauthority.conf | 22 --
6 files changed, 340 insertions(+), 33 deletions(-)
New commits:
commit ae8ea087928b7a1bc34b2380872da8867563bec1
Author: David Zeuthen <davidz at redhat.com>
Date: Wed Jul 15 18:56:18 2009 -0400
Add docs detailing how the Local Authority works
diff --git a/docs/man/Makefile.am b/docs/man/Makefile.am
index 6a2cf2b..076608b 100644
--- a/docs/man/Makefile.am
+++ b/docs/man/Makefile.am
@@ -6,6 +6,7 @@ if MAN_PAGES_ENABLED
man_MANS = \
polkit.8 \
polkitd.8 \
+ pklocalauthority.8 \
pkexec.1 \
pkcheck.1 \
pkaction.1 \
@@ -19,6 +20,7 @@ endif # MAN_PAGES_ENABLED
EXTRA_DIST = \
polkit.xml \
polkitd.xml \
+ pklocalauthority.xml \
pkexec.xml \
pkcheck.xml \
pkaction.xml \
diff --git a/docs/man/pklocalauthority.xml b/docs/man/pklocalauthority.xml
new file mode 100644
index 0000000..52dded2
--- /dev/null
+++ b/docs/man/pklocalauthority.xml
@@ -0,0 +1,317 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<refentry id="pklocalauthority.8">
+ <refentryinfo>
+ <title>pklocalauthority</title>
+ <date>May 2009</date>
+ <productname>polkit</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>pklocalauthority</refentrytitle>
+ <manvolnum>8</manvolnum>
+ <refmiscinfo class="version"></refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>pklocalauthority</refname>
+ <refpurpose>PolicyKit Local Authority</refpurpose>
+ </refnamediv>
+
+ <refsect1 id="pklocalauthority-description">
+ <title>DESCRIPTION</title>
+ <para>
+ The Local Authority is the default PolicyKit authority
+ implementation. Configuration for the Local Authority and
+ information pertaining to authorization decisions are read from
+ local files on the disk. One design goal of the Local Authority
+ is to split configuration items into separate files such that
+ 3rd party packages and users won't conflict trying to edit the
+ same files. This policy also ensures smooth upgrades when
+ distributing PolicyKit using a package management system.
+ </para>
+ </refsect1>
+
+ <refsect1 id="pklocalauthority-admin-authentication">
+ <title>ADMINISTRATOR AUTHENTICATION</title>
+ <para>
+ PolicyKit makes a distinction between <emphasis>user
+ authentication</emphasis> (to make the user in front of the
+ system prove he really is the user) and <emphasis>administrator
+ authentication</emphasis> (to make the user in front of the
+ system prove he really is an administrator). Since various
+ operating systems (or even flavors of the same operating system)
+ has different ways of defining "administrator", the Local
+ Authority provides a way to specify what "administrator
+ authentication" means.
+ </para>
+ <para>
+ By default, "administrator authentication" is defined as asking
+ for the root password. Since some systems, for usability
+ reasons, don't have a root password and instead rely on a group
+ of users being member of an administrative group that gives them
+ super-user privileges, the Local Authority can be configured to
+ support this use-case as well.
+ </para>
+ <para>
+ Configuration for the Local Authority are read from files in
+ the <filename>/etc/polkit-1/localauthority.conf.d</filename>
+ directory. The file <filename>50-localauthority.conf</filename>
+ contains the settings provided by the OS vendor. Users and 3rd
+ party packages can drop configuration files with a priority
+ higher than 60 to change the defaults. The configuration file
+ format is simple. Each configuration file is a <emphasis>key
+ file</emphasis> with a single <literal>Configuration</literal>
+ group. Only a single key, <literal>AdminIdentities</literal> is
+ read. The value of this key is a semi-colon separated list of
+ identities that can be used when administrator authentication is
+ required. Users are specified by prefixing the user name with
+ <literal>unix-user:</literal> and groups of users are specified
+ by prefixing with <literal>unix-group:</literal>.
+ </para>
+ </refsect1>
+
+ <refsect1 id="pklocalauthority-directory-structure">
+ <title>DIRECTORY STRUCTURE</title>
+ <para>
+ The Local Authority reads files with <filename>.pkla</filename>
+ from the following directories
+ </para>
+ <programlisting>
+/var/lib/polkit-1/
+`-- localauthority
+ |-- 10-vendor.d
+ |-- 20-org.d
+ |-- 30-site.d
+ |-- 50-local.d
+ `-- 90-mandatory.d
+ </programlisting>
+ <para>
+ Each <filename>.pkla</filename> contains one or more
+ authorization entries. If the underlying filesystem supports
+ file monitoring, the Local Authority will reload information
+ whenever changes occur.
+ </para>
+ <para>
+ Each directory is intended for a specific audience
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>10-vendor.d</emphasis></term>
+ <listitem>
+ <para>
+ Reserved for the Operating System vendor.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>20-org.d</emphasis></term>
+ <listitem>
+ <para>
+ Reserved for the organization deploying the system.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>30-site.d</emphasis></term>
+ <listitem>
+ <para>
+ Reserved for site deploying the system.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>50-local.d</emphasis></term>
+ <listitem>
+ <para>
+ Reserved for local usage.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>90-mandatory.d</emphasis></term>
+ <listitem>
+ <para>
+ Reserved for the organization deploying the system.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Each <filename>.pkla</filename> file is a standard <emphasis>key
+ file</emphasis> and contains key/value pairs in one or more
+ groups with each group representing an authorization entry.
+ A <filename>.pkla</filename> file MUST be named by using a
+ scheme to ensure that the name is unique, e.g. reverse DNS
+ notation or similar.
+ </para>
+ </refsect1>
+
+ <refsect1 id="pklocalauthority-authorization-entry">
+ <title>AUTHORIZATION ENTRY</title>
+ <para>
+ Each group in a <filename>.pkla</filename> must have a name that
+ is unique within the file it belongs to. The following keys are
+ required in each group
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Identity</emphasis></term>
+ <listitem>
+ <para>
+ A semi-colon separated list of globs to match identities. Each glob
+ should start with <literal>unix-user:</literal> or
+ <literal>unix-group:</literal> to specify whether to match on a
+ UNIX user name or a UNIX group name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Action</emphasis></term>
+ <listitem>
+ <para>
+ A semi-colon separated list of globs to match action identifiers.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>ResultActive</emphasis></term>
+ <listitem>
+ <para>
+ The result to return for subjects in an active local
+ session that matches one or more of the given identities.
+ Allowed values are similar to what can be used in
+ the <emphasis>defaults</emphasis> section
+ of <filename>.policy</filename> files used to define
+ actions, e.g.
+ <literal>yes</literal>,
+ <literal>no</literal>,
+ <literal>auth_self</literal>,
+ <literal>auth_self_keep</literal>,
+ <literal>auth_admin</literal> and
+ <literal>auth_admin_keep</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>ResultInactive</emphasis></term>
+ <listitem>
+ <para>
+ Like <emphasis>ResultActive</emphasis> but instead applies
+ to subjects in inactive local sessions.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>ResultAny</emphasis></term>
+ <listitem>
+ <para>
+ Like <emphasis>ResultActive</emphasis> but instead applies
+ to any subject.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ All keys specified above are required except that only at least
+ one
+ of <emphasis>RequireAny</emphasis>, <emphasis>RequireInactive</emphasis>
+ and <emphasis>RequireActive</emphasis> is present.
+ </para>
+ </refsect1>
+
+ <refsect1 id="pklocalauthority-evaluation-order">
+ <title>EVALUATION ORDER</title>
+ <para>
+ Whenever a Mechanism does an authorization check to check if a
+ given Subject is authorized for a given action, the
+ authorization entries discussed above are consulted in the
+ following order. First, the user of the Subject is determined
+ and the groups that the user belongs are looked up.
+ </para>
+ <para>
+ For each group identity, the authorization entries are consulted
+ in the standard lexigraphical order (using standard
+ lexicographical sorting (using the standard C locale) of file
+ names and appearance of each group in each file). If the
+ authorization check matches the data from the authorization
+ check, then the authorization result
+ from <emphasis>RequireAny</emphasis>, <emphasis>RequireInactive</emphasis>
+ or <emphasis>RequireActive</emphasis> is used. Finally, the
+ authorization entries are consulted using the user identity.
+ </para>
+ <para>
+ Note that processing continues even after a match. This allows
+ for socalled <quote>negative authorizations</quote>, see
+ <xref linkend="pklocalauthority-examples"/> for further
+ discussion.
+ </para>
+ </refsect1>
+
+ <refsect1 id="pklocalauthority-examples">
+ <title>EXAMPLES</title>
+ <para>
+ The following <filename>.pkla</filename> file grants
+ authorization to all users in the <literal>staff</literal> group
+ for actions matching the
+ glob <literal>com.example.awesomeproduct.*</literal> provided
+ they are in an active session on the local console:
+ </para>
+ <programlisting>
+[Normal Staff Permissions]
+Identity=unix-group:staff
+Action=com.example.awesomeproduct.*
+ResultAny=no
+ResultInactive=no
+ResultActive=yes
+ </programlisting>
+ <para>
+ If the users <literal>homer</literal> and <literal>grimes</literal> are member of
+ the <literal>staff</literal> group but policy requires that an
+ administrator needs to authenticate every time authorization for
+ any action
+ matching <literal>com.example.awesomeproduct.*</literal> is
+ required, one would add
+ </para>
+ <programlisting>
+[Exclude Some Problematic Users]
+Identity=unix-user:homer;unix-user:grimes
+Action=com.example.awesomeproduct.*
+ResultAny=no
+ResultInactive=no
+ResultActive=auth_admin
+ </programlisting>
+ <para>
+ and make sure this authorization entry is after the first one.
+ </para>
+ </refsect1>
+
+ <refsect1 id="pklocalauthority-author"><title>AUTHOR</title>
+ <para>
+ Written by David Zeuthen <email>davidz at redhat.com</email> with
+ a lot of help from many others.
+ </para>
+ </refsect1>
+
+ <refsect1 id="pklocalauthority-bugs">
+ <title>BUGS</title>
+ <para>
+ Please send bug reports to either the distribution or the
+ polkit-devel mailing list,
+ see the link <ulink url="http://lists.freedesktop.org/mailman/listinfo/polkit-devel"/>
+ on how to subscribe.
+ </para>
+ </refsect1>
+
+ <refsect1 id="pklocalauthority-see-also">
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/docs/man/polkit.xml b/docs/man/polkit.xml
index 27382e0..bcb276b 100644
--- a/docs/man/polkit.xml
+++ b/docs/man/polkit.xml
@@ -127,6 +127,13 @@ System Context | |
documentation</ulink> for more information about using and
extending PolicyKit.
</para>
+
+ <para>
+ See
+ <citerefentry><refentrytitle>pklocalauthority</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ for information about the Local Authority - the default
+ authority implementation shipped with PolicyKit.
+ </para>
</refsect1>
<refsect1 id="polkit-authentication-agents"><title>AUTHENTICATION AGENTS</title>
@@ -210,7 +217,9 @@ System Context | |
</textobject>
</mediaobject>
<para>
- See <xref linkend="pkla"/> for how to set up the local authority
+ See
+ <citerefentry><refentrytitle>pklocalauthority</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ on how to set up the local authority
implemention for systems without a <literal>root</literal>
account.
</para>
@@ -391,16 +400,6 @@ System Context | |
</para>
</refsect1>
- <refsect1 id="pkla"><title>LOCAL AUTHORITY IMPLEMENTATION</title>
- <para>
- The default authority implementation in PolicyKit is using the
- local filesystem to store authorizations. TODO: write some more
- here including a link to a
- <citerefentry><refentrytitle>pklamanage</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- command.
- </para>
- </refsect1>
-
<refsect1 id="polkit-author"><title>AUTHOR</title>
<para>
Written by David Zeuthen <email>davidz at redhat.com</email> with
@@ -422,6 +421,12 @@ System Context | |
<title>SEE ALSO</title>
<para>
<citerefentry>
+ <refentrytitle>pklocalauthority</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>
+ <citerefentry>
+ <refentrytitle>polkitd</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>
+ <citerefentry>
<refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
@@ -430,9 +435,6 @@ System Context | |
<citerefentry>
<refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>,
- <citerefentry>
- <refentrytitle>polkitd</refentrytitle><manvolnum>8</manvolnum>
- </citerefentry>
</para>
</refsect1>
</refentry>
diff --git a/docs/polkit/Makefile.am b/docs/polkit/Makefile.am
index bd94167..bf05b92 100644
--- a/docs/polkit/Makefile.am
+++ b/docs/polkit/Makefile.am
@@ -61,6 +61,7 @@ content_files = \
../../src/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml \
../man/polkit.xml \
../man/polkitd.xml \
+ ../man/pklocalauthority.xml \
../man/pkcheck.xml \
../man/pkaction.xml \
../man/pkexec.xml \
diff --git a/docs/polkit/polkit-1-docs.xml b/docs/polkit/polkit-1-docs.xml
index eeab10b..aa3aa16 100644
--- a/docs/polkit/polkit-1-docs.xml
+++ b/docs/polkit/polkit-1-docs.xml
@@ -109,6 +109,7 @@
<title>Manual Pages</title>
<xi:include href="../man/polkit.xml"/>
<xi:include href="../man/polkitd.xml"/>
+ <xi:include href="../man/pklocalauthority.xml"/>
<xi:include href="../man/pkcheck.xml"/>
<xi:include href="../man/pkaction.xml"/>
<xi:include href="../man/pkexec.xml"/>
diff --git a/src/polkitbackend/50-localauthority.conf b/src/polkitbackend/50-localauthority.conf
index 4514828..20e0ba3 100644
--- a/src/polkitbackend/50-localauthority.conf
+++ b/src/polkitbackend/50-localauthority.conf
@@ -1,25 +1,9 @@
-#
-# Configuration file for the PolicyKit local authority backend.
+# Configuration file for the PolicyKit Local Authority.
#
# DO NOT EDIT THIS FILE, it will be overwritten on update.
#
-# To change configuration, create another file in this directory with
-# a filename that is sorted after the 50-localauthority.conf and make
-# sure it has the .conf extension.
-#
-# Only a single configuration item, AdminIdentities, is supported. It
-# specifies what set of identities to use for administrator authentication.
-# The value is a semicolon-separated list of identities. An identity can
-# be specified as
-#
-# unix-user:<user>
-# unix-group:<group>
-#
-# where <user> is username/uid and <group> is a groupname/gid. When
-# using the group directive, any user in the given group can chosen
-# for authentication.
-#
-# See the PolicyKit documentation for more information about PolicyKit.
+# See the pklocalauthority(8) man page for more information
+# about configuring the Local Authority.
#
[Configuration]
More information about the hal-commit
mailing list