From ae8ea087928b7a1bc34b2380872da8867563bec1 Mon Sep 17 00:00:00 2001 From: David Zeuthen Date: Wed, 15 Jul 2009 18:56:18 -0400 Subject: Add docs detailing how the Local Authority works --- 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(-) create mode 100644 docs/man/pklocalauthority.xml 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 @@ + + +]> + + + pklocalauthority + May 2009 + polkit + + + + pklocalauthority + 8 + + + + + pklocalauthority + PolicyKit Local Authority + + + + DESCRIPTION + + 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. + + + + + ADMINISTRATOR AUTHENTICATION + + PolicyKit makes a distinction between user + authentication (to make the user in front of the + system prove he really is the user) and administrator + authentication (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. + + + 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. + + + Configuration for the Local Authority are read from files in + the /etc/polkit-1/localauthority.conf.d + directory. The file 50-localauthority.conf + 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 key + file with a single Configuration + group. Only a single key, AdminIdentities 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 + unix-user: and groups of users are specified + by prefixing with unix-group:. + + + + + DIRECTORY STRUCTURE + + The Local Authority reads files with .pkla + from the following directories + + +/var/lib/polkit-1/ +`-- localauthority + |-- 10-vendor.d + |-- 20-org.d + |-- 30-site.d + |-- 50-local.d + `-- 90-mandatory.d + + + Each .pkla contains one or more + authorization entries. If the underlying filesystem supports + file monitoring, the Local Authority will reload information + whenever changes occur. + + + Each directory is intended for a specific audience + + + + 10-vendor.d + + + Reserved for the Operating System vendor. + + + + + 20-org.d + + + Reserved for the organization deploying the system. + + + + + 30-site.d + + + Reserved for site deploying the system. + + + + + 50-local.d + + + Reserved for local usage. + + + + + 90-mandatory.d + + + Reserved for the organization deploying the system. + + + + + + Each .pkla file is a standard key + file and contains key/value pairs in one or more + groups with each group representing an authorization entry. + A .pkla file MUST be named by using a + scheme to ensure that the name is unique, e.g. reverse DNS + notation or similar. + + + + + AUTHORIZATION ENTRY + + Each group in a .pkla must have a name that + is unique within the file it belongs to. The following keys are + required in each group + + + + Identity + + + A semi-colon separated list of globs to match identities. Each glob + should start with unix-user: or + unix-group: to specify whether to match on a + UNIX user name or a UNIX group name. + + + + + Action + + + A semi-colon separated list of globs to match action identifiers. + + + + + ResultActive + + + 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 defaults section + of .policy files used to define + actions, e.g. + yes, + no, + auth_self, + auth_self_keep, + auth_admin and + auth_admin_keep. + + + + + ResultInactive + + + Like ResultActive but instead applies + to subjects in inactive local sessions. + + + + + ResultAny + + + Like ResultActive but instead applies + to any subject. + + + + + + All keys specified above are required except that only at least + one + of RequireAny, RequireInactive + and RequireActive is present. + + + + + EVALUATION ORDER + + 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. + + + 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 RequireAny, RequireInactive + or RequireActive is used. Finally, the + authorization entries are consulted using the user identity. + + + Note that processing continues even after a match. This allows + for socalled negative authorizations, see + for further + discussion. + + + + + EXAMPLES + + The following .pkla file grants + authorization to all users in the staff group + for actions matching the + glob com.example.awesomeproduct.* provided + they are in an active session on the local console: + + +[Normal Staff Permissions] +Identity=unix-group:staff +Action=com.example.awesomeproduct.* +ResultAny=no +ResultInactive=no +ResultActive=yes + + + If the users homer and grimes are member of + the staff group but policy requires that an + administrator needs to authenticate every time authorization for + any action + matching com.example.awesomeproduct.* is + required, one would add + + +[Exclude Some Problematic Users] +Identity=unix-user:homer;unix-user:grimes +Action=com.example.awesomeproduct.* +ResultAny=no +ResultInactive=no +ResultActive=auth_admin + + + and make sure this authorization entry is after the first one. + + + + AUTHOR + + Written by David Zeuthen davidz@redhat.com with + a lot of help from many others. + + + + + BUGS + + Please send bug reports to either the distribution or the + polkit-devel mailing list, + see the link + on how to subscribe. + + + + + SEE ALSO + + + polkit8 + + + + 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 for more information about using and extending PolicyKit. + + + See + pklocalauthority8 + for information about the Local Authority - the default + authority implementation shipped with PolicyKit. + AUTHENTICATION AGENTS @@ -210,7 +217,9 @@ System Context | | - See for how to set up the local authority + See + pklocalauthority8 + on how to set up the local authority implemention for systems without a root account. @@ -391,16 +400,6 @@ System Context | | - LOCAL AUTHORITY IMPLEMENTATION - - The default authority implementation in PolicyKit is using the - local filesystem to store authorizations. TODO: write some more - here including a link to a - pklamanage1 - command. - - - AUTHOR Written by David Zeuthen davidz@redhat.com with @@ -421,6 +420,12 @@ System Context | | SEE ALSO + + pklocalauthority8 + + + polkitd8 + pkaction1 , @@ -430,9 +435,6 @@ System Context | | pkexec1 , - - polkitd8 - 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 @@ Manual Pages + 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: -# unix-group: -# -# where is username/uid and 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] -- cgit v1.2.1