pklocalauthority.xml 11.8 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
<?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
158
      are processed.
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216
    </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>
217 218 219 220 221 222 223 224 225 226
      <varlistentry>
        <term><emphasis>ReturnValue</emphasis></term>
        <listitem>
          <para>
            A semi-colon separated list of key/value pairs (of the
            form key=value) that are add to the details of
            authorization result on positive matches.
          </para>
        </listitem>
      </varlistentry>
227 228 229 230 231
    </variablelist>
    <para>
      All keys specified above are required except that only at least
      one
      of <emphasis>RequireAny</emphasis>, <emphasis>RequireInactive</emphasis>
232 233
      and <emphasis>RequireActive</emphasis> is
      present. The <emphasis>ReturnValue</emphasis> key is optional.
234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253
    </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>
254 255 256 257
      or <emphasis>RequireActive</emphasis> is used
      and <emphasis>ReturnValue</emphasis> is added to the
      authorization result. Finally, the authorization entries are
      consulted using the user identity in the same manner.
258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330
    </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@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>