docs/man/polkit.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   4 <!ENTITY version SYSTEM "../version.xml">
   5 ]>
   6 <refentry id="polkit.8" xmlns:xi="http://www.w3.org/2003/XInclude">
   7   <refentryinfo>
   8     <title>polkit</title>
   9     <date>January 2009</date>
  10     <productname>polkit</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>polkit</refentrytitle>
  15     <manvolnum>8</manvolnum>
  16     <refmiscinfo class="version"></refmiscinfo>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>polkit</refname>
  21     <refpurpose>Authorization Manager</refpurpose>
  22   </refnamediv>
  23
  24   <refsect1 id="polkit-overview"><title>OVERVIEW</title>
  25     <para>
  26       polkit provides an authorization API intended to be used by
  27       privileged programs (<quote>MECHANISMS</quote>) offering service
  28       to unprivileged programs (<quote>SUBJECTS</quote>) often through
  29       some form of inter-process communication mechanism. In this
  30       scenario, the mechanism typically treats the subject as
  31       untrusted. For every request from a subject, the mechanism needs
  32       to determine if the request is authorized or if it should refuse
  33       to service the subject. Using the polkit APIs, a mechanism can
  34       offload this decision to a trusted party: The polkit authority.
  35     </para>
  36
  37     <para>
  38       The polkit authority is implemented as an system daemon,
  39       <link linkend="polkitd.8"><citerefentry><refentrytitle>polkitd</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
  40       which itself has little privilege as it is running as the
  41       <emphasis>polkitd</emphasis> system user. Mechanisms, subjects
  42       and authentication agents communicate with the authority using
  43       the system message bus.
  44     </para>
  45
  46     <para>
  47       In addition to acting as an authority, polkit allows users to
  48       obtain temporary authorization through authenticating either an
  49       administrative user or the owner of the session the client
  50       belongs to. This is useful for scenarios where a mechanism needs
  51       to verify that the operator of the system really is the user or
  52       really is an administrative user.
  53     </para>
  54
  55   </refsect1>
  56
  57   <refsect1 id="polkit-system-architecture"><title>SYSTEM ARCHITECTURE</title>
  58     <para>
  59       The system architecture of polkit is comprised of the
  60       <emphasis>Authority</emphasis> (implemented as a service on the
  61       system message bus) and an <emphasis>Authentication
  62       Agent</emphasis> per user session (provided and started by the
  63       user's graphical environment). <emphasis>Actions</emphasis> are
  64       defined by applications. Vendors, sites and system
  65       administrators can control authorization policy through
  66       <emphasis>Authorization Rules</emphasis>.
  67     </para>
  68     <mediaobject id="polkit-architecture">
  69       <imageobject>
  70         <imagedata fileref="polkit-architecture.png" format="PNG"/>
  71       </imageobject>
  72       <textobject>
  73         <programlisting><![CDATA[
  74  +-------------------+
  75  |   Authentication  |
  76  |       Agent       |
  77  +-------------------+
  78  | libpolkit-agent-1 |
  79  +-------------------+
  80         ^                                  +---------+
  81         |                                  | Subject |
  82         +--------------+                   +---------+
  83                        |                        ^
  84                        |                        |
  85 User Session           |                        |
  86 =======================|========================|=============
  87 System Context         |                        |
  88                        |                        |
  89                        |                    +---+
  90                        V                    |
  91                      /------------\         |
  92                      | System Bus |         |
  93                      \------------/         |
  94                        ^        ^           V
  95                        |        |      +---------------------+
  96         +--------------+        |      |      Mechanism      |
  97         |                       |      +---------------------+
  98         V                       +----> | libpolkit-gobject-1 |
  99 +------------------+                   +---------------------+
 100 |    polkitd(8)    |
 101 +------------------+
 102 | org.freedesktop. |
 103 |    PolicyKit1    |<---------+
 104 +------------------+          |
 105           ^                   |
 106           |            +--------------------------------------+
 107           |            | /usr/share/polkit-1/actions/*.policy |
 108           |            +--------------------------------------+
 109           |
 110    +--------------------------------------+
 111    | /etc/polkit-1/rules.d/*.rules        |
 112    | /usr/share/polkit-1/rules.d/*.rules  |
 113    +--------------------------------------+
 114 ]]></programlisting>
 115       </textobject>
 116     </mediaobject>
 117     <para>
 118       For convenience, the <literal>libpolkit-gobject-1</literal>
 119       library wraps the polkit D-Bus API and is usable from any C/C++
 120       program as well as higher-level languages supporting <ulink
 121       url="https://live.gnome.org/GObjectIntrospection">GObjectIntrospection</ulink>
 122       such as Javascript and Python.  A mechanism can also use the
 123       D-Bus API or the <link
 124       linkend="pkcheck.1"><citerefentry><refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>
 125       command to check authorizations. The
 126       <literal>libpolkit-agent-1</literal> library provides an
 127       abstraction of the native authentication system, e.g.
 128       <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 129       and also facilities registration and communication with the
 130       polkit D-Bus service.
 131     </para>
 132
 133     <para>
 134       See the <ulink
 135       url="http://www.freedesktop.org/software/polkit/docs/latest/">developer
 136       documentation</ulink> for more information about writing polkit
 137       applications.
 138     </para>
 139   </refsect1>
 140
 141   <refsect1 id="polkit-authentication-agents"><title>AUTHENTICATION AGENTS</title>
 142     <para>
 143       An authentication agent is used to make the user of a session
 144       prove that the user of the session really is the user (by
 145       authenticating as the user) or an administrative user (by
 146       authenticating as a administrator). In order to integrate well
 147       with the rest of the user session (e.g. match the look and
 148       feel), authentication agents are meant to be provided by the
 149       user session that the user uses. For example, an authentication
 150       agent may look like this:
 151     </para>
 152     <mediaobject id="polkit-authentication-agent-example">
 153       <imageobject>
 154         <imagedata fileref="polkit-authentication-agent-example.png" format="PNG"/>
 155       </imageobject>
 156       <textobject>
 157         <programlisting><![CDATA[
 158 +----------------------------------------------------------+
 159 |                                                          |
 160 |  [Icon]  Authentication required                         |
 161 |                                                          |
 162 |          Authentication is required to format INTEL      |
 163 |          SSDSA2MH080G1GC (/dev/sda)                      |
 164 |                                                          |
 165 |          Administrator                                   |
 166 |                                                          |
 167 |          Password: [__________________________________]  |
 168 |                                                          |
 169 | [Cancel]                                  [Authenticate] |
 170 +----------------------------------------------------------+
 171 ]]></programlisting>
 172       </textobject>
 173     </mediaobject>
 174     <para>
 175       If the system is configured without a <emphasis>root</emphasis>
 176       account it may prompt for a specific user designated as the
 177       administrative user:
 178     </para>
 179     <mediaobject id="polkit-authentication-agent-example-wheel">
 180       <imageobject>
 181         <imagedata fileref="polkit-authentication-agent-example-wheel.png" format="PNG"/>
 182       </imageobject>
 183       <textobject>
 184         <programlisting><![CDATA[
 185 +----------------------------------------------------------+
 186 |                                                          |
 187 |  [Icon]  Authentication required                         |
 188 |                                                          |
 189 |          Authentication is required to format INTEL      |
 190 |          SSDSA2MH080G1GC (/dev/sda)                      |
 191 |                                                          |
 192 |          [Icon] David Zeuthen                            |
 193 |                                                          |
 194 |          Password: [__________________________________]  |
 195 |                                                          |
 196 | [Cancel]                                  [Authenticate] |
 197 +----------------------------------------------------------+
 198 ]]></programlisting>
 199       </textobject>
 200     </mediaobject>
 201     <para>
 202       Applications that do not run under a desktop environment (for
 203       example, if launched from a
 204       <citerefentry><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 205       login) may not have have an authentication agent associated with
 206       them. Such applications may use the <link
 207       linkend="PolkitAgentTextListener-struct">PolkitAgentTextListener</link>
 208       type or the
 209       <link linkend="pkttyagent.1"><citerefentry><refentrytitle>pkttyagent</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>
 210       helper so the user can authenticate using a textual interface.
 211     </para>
 212   </refsect1>
 213
 214   <refsect1 id="polkit-declaring-actions"><title>DECLARING ACTIONS</title>
 215     <para>
 216       A mechanism need to declare a set of <emphasis>actions</emphasis> in
 217       order to use polkit. Actions correspond to operations that
 218       clients can request the mechanism to carry out and are defined
 219       in XML files that the mechanism installs into the <filename
 220       class='directory'>/usr/share/polkit-1/actions</filename>
 221       directory.
 222     </para>
 223
 224     <para>
 225       polkit actions are namespaced and can only contain the
 226       characters <literal>[A-Z][a-z][0-9].-</literal> e.g. ASCII,
 227       digits, period and hyphen. Each XML file can contain more than
 228       one action but all actions need to be in the same namespace and
 229       the file needs to be named after the namespace and have the
 230       extension <filename class='extension'>.policy</filename>.
 231     </para>
 232
 233     <para>
 234       The XML file must have the following doctype declaration
 235     </para>
 236     <programlisting><![CDATA[
 237 <?xml version="1.0" encoding="UTF-8"?>
 238 <!DOCTYPE policyconfig PUBLIC "-//freedesktop//DTD polkit Policy Configuration 1.0//EN"
 239 "http://www.freedesktop.org/software/polkit/policyconfig-1.dtd">
 240 ]]></programlisting>
 241     <para>
 242       The <emphasis>policyconfig</emphasis> element must be present
 243       exactly once. Elements that can be used
 244       inside <emphasis>policyconfig</emphasis> includes:
 245     </para>
 246     <variablelist>
 247       <varlistentry>
 248         <term><emphasis>vendor</emphasis></term>
 249         <listitem>
 250           <para>
 251             The name of the project or vendor that is supplying the
 252             actions in the XML document. Optional.
 253           </para>
 254         </listitem>
 255       </varlistentry>
 256       <varlistentry>
 257         <term><emphasis>vendor_url</emphasis></term>
 258         <listitem>
 259           <para>
 260             A URL to the project or vendor that is supplying the
 261             actions in the XML document.  Optional.
 262           </para>
 263         </listitem>
 264       </varlistentry>
 265       <varlistentry>
 266         <term><emphasis>icon_name</emphasis></term>
 267         <listitem>
 268           <para>
 269             An icon representing the project or vendor that is
 270             supplying the actions in the XML document. The icon name
 271             must adhere to the <ulink
 272             url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Freedesktop.org
 273             Icon Naming Specification</ulink>. Optional.
 274           </para>
 275         </listitem>
 276       </varlistentry>
 277       <varlistentry>
 278         <term><emphasis>action</emphasis></term>
 279         <listitem>
 280           <para>
 281             Declares an action. The action name is specified using the
 282             <literal>id</literal> attribute and can only contain the
 283             characters <literal>[A-Z][a-z][0-9].-</literal>
 284             e.g. ASCII, digits, period and hyphen.
 285           </para>
 286         </listitem>
 287       </varlistentry>
 288     </variablelist>
 289     <para>
 290       Elements that can be used inside <emphasis>action</emphasis> include:
 291     </para>
 292     <variablelist>
 293       <varlistentry>
 294         <term><emphasis>description</emphasis></term>
 295         <listitem>
 296           <para>
 297             A human readable description of the action,
 298             e.g. <quote>Install unsigned software</quote>.
 299           </para>
 300         </listitem>
 301       </varlistentry>
 302       <varlistentry>
 303         <term><emphasis>message</emphasis></term>
 304         <listitem>
 305           <para>
 306             A human readable message displayed to the user when asking
 307             for credentials when authentication is needed,
 308             e.g. <quote>Installing unsigned software requires
 309             authentication</quote>.
 310           </para>
 311         </listitem>
 312       </varlistentry>
 313       <varlistentry>
 314         <term><emphasis>defaults</emphasis></term>
 315         <listitem>
 316           <para>
 317             This element is used to specify implicit authorizations
 318             for clients. Elements that can be used inside
 319             <emphasis>defaults</emphasis> include:
 320           </para>
 321           <variablelist>
 322             <varlistentry>
 323               <term><emphasis>allow_any</emphasis></term>
 324               <listitem><para>Implicit authorizations that apply to
 325               any client. Optional.</para></listitem>
 326             </varlistentry>
 327             <varlistentry>
 328               <term><emphasis>allow_inactive</emphasis></term>
 329               <listitem><para>Implicit authorizations that apply to
 330               clients in inactive sessions on local
 331               consoles. Optional.</para></listitem>
 332             </varlistentry>
 333             <varlistentry>
 334               <term><emphasis>allow_active</emphasis></term>
 335               <listitem><para>Implicit authorizations that apply to
 336               clients in active sessions on local
 337               consoles. Optional.</para></listitem>
 338             </varlistentry>
 339           </variablelist>
 340           <para>
 341             Each of
 342             the <emphasis>allow_any</emphasis>, <emphasis>allow_inactive</emphasis>
 343             and <emphasis>allow_active</emphasis> elements can contain
 344             the following values:
 345           </para>
 346           <variablelist>
 347             <varlistentry>
 348               <term><literal>no</literal></term>
 349               <listitem><para>Not authorized.</para></listitem>
 350             </varlistentry>
 351             <varlistentry>
 352               <term><literal>yes</literal></term>
 353               <listitem><para>Authorized.</para></listitem>
 354             </varlistentry>
 355             <varlistentry>
 356               <term><literal>auth_self</literal></term>
 357               <listitem><para>Authentication by the owner of the
 358               session that the client originates from is
 359               required.</para></listitem>
 360             </varlistentry>
 361             <varlistentry>
 362               <term><literal>auth_admin</literal></term>
 363               <listitem><para>Authentication by an administrative user
 364               is required.</para></listitem>
 365             </varlistentry>
 366             <varlistentry>
 367               <term><literal>auth_self_keep</literal></term>
 368               <listitem><para>Like <literal>auth_self</literal> but
 369               the authorization is kept for a brief
 370               period (e.g. five minutes).</para></listitem>
 371             </varlistentry>
 372             <varlistentry>
 373               <term><literal>auth_admin_keep</literal></term>
 374               <listitem><para>Like <literal>auth_admin</literal> but the authorization is kept for a brief period  (e.g. five minutes).</para></listitem>
 375             </varlistentry>
 376           </variablelist>
 377         </listitem>
 378       </varlistentry>
 379       <varlistentry>
 380         <term><emphasis>annotate</emphasis></term>
 381         <listitem>
 382           <para>
 383             Used for annotating an action with a key/value pair. The
 384             key is specified using the the <literal>key</literal>
 385             attribute and the value is specified using the
 386             <literal>value</literal> attribute. This element may
 387             appear zero or more times. See below for known
 388             annotations.
 389           </para>
 390         </listitem>
 391       </varlistentry>
 392       <varlistentry>
 393         <term><emphasis>vendor</emphasis></term>
 394         <listitem>
 395           <para>
 396             Used for overriding the vendor on a per-action
 397             basis. Optional.
 398           </para>
 399         </listitem>
 400       </varlistentry>
 401       <varlistentry>
 402         <term><emphasis>vendor_url</emphasis></term>
 403         <listitem>
 404           <para>
 405             Used for overriding the vendor URL on a per-action
 406             basis. Optional.
 407           </para>
 408         </listitem>
 409       </varlistentry>
 410       <varlistentry>
 411         <term><emphasis>icon_name</emphasis></term>
 412         <listitem>
 413           <para>
 414             Used for overriding the icon name on a per-action
 415             basis. Optional.
 416           </para>
 417         </listitem>
 418       </varlistentry>
 419     </variablelist>
 420     <para>
 421       For localization, <emphasis>description</emphasis> and
 422       <emphasis>message</emphasis> elements may occur multiple times
 423       with different <literal>xml:lang</literal> attributes.
 424     </para>
 425     <para>
 426       To list installed polkit actions, use the
 427       <link linkend="pkaction.1"><citerefentry><refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>
 428       command.
 429     </para>
 430
 431     <refsect2>
 432       <title>Known annotations</title>
 433       <para>
 434         The <literal>org.freedesktop.policykit.exec.path</literal>
 435         annotation is used by the <command>pkexec</command> program
 436         shipped with polkit - see the
 437         <link linkend="pkexec.1"><citerefentry><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>
 438         man page for details.
 439       </para>
 440       <para>
 441         The <literal>org.freedesktop.policykit.imply</literal>
 442         annotation (its value is a string containing a space separated
 443         list of action identifiers) can be used to define
 444         <emphasis>meta actions</emphasis>. The way it works is that if
 445         a subject is authorized for an action with this annotation,
 446         then it is also authorized for any action specified by the
 447         annotation. A typical use of this annotation is when defining
 448         an UI shell with a single lock button that should unlock
 449         multiple actions from distinct mechanisms.
 450       </para>
 451       <para>
 452         The <literal>org.freedesktop.policykit.owner</literal>
 453         annotation can be used to define a set of users who can query
 454         whether a client is authorized to perform this action.  If
 455         this annotation is not specified then only root can query
 456         whether a client running as a different user is authorized for
 457         an action.  The value of this annotation is a string
 458         containing a space separated list of <link
 459         linkend="PolkitIdentity-struct">PolkitIdentity</link> entries,
 460         for example <literal>"unix-user:42
 461         unix-user:colord"</literal>.  A typical use of this annotation
 462         is for a daemon process that runs as a system user rather than
 463         root.
 464       </para>
 465     </refsect2>
 466   </refsect1>
 467
 468   <refsect1 id="polkit-rules"><title>AUTHORIZATION RULES</title>
 469     <para>
 470       <command>polkitd</command> reads
 471       <filename class='extension'>.rules</filename> files from the
 472       <filename class='directory'>/etc/polkit-1/rules.d</filename> and
 473       <filename class='directory'>/usr/share/polkit-1/rules.d</filename>
 474       directories by sorting the files in lexical order based on the
 475       basename on each file (if there's a tie, files in
 476       <filename class='directory'>/etc</filename>
 477       are processed before files in
 478       <filename class='directory'>/usr</filename>).
 479       For example, for the following four
 480       files, the order is
 481     </para>
 482     <itemizedlist mark='opencircle' spacing='compact'>
 483       <listitem><para><filename>/etc/polkit-1/rules.d/10-auth.rules</filename></para></listitem>
 484       <listitem><para><filename>/usr/share/polkit-1/rules.d/10-auth.rules</filename></para></listitem>
 485       <listitem><para><filename>/etc/polkit-1/rules.d/15-auth.rules</filename></para></listitem>
 486       <listitem><para><filename>/usr/share/polkit-1/rules.d/20-auth.rules</filename></para></listitem>
 487     </itemizedlist>
 488     <para>
 489       Both directories are monitored so if a rules file is changed,
 490       added or removed, existing rules are purged and all files are
 491       read and processed again.  Rules files are written in the
 492       <ulink url="http://en.wikipedia.org/wiki/JavaScript">JavaScript</ulink>
 493       programming language and interface with <command>polkitd</command>
 494       through the global
 495       <literal>polkit</literal> object (of type <type>Polkit</type>).
 496     </para>
 497     <para>
 498       While the JavaScript interpreter used in particular versions of
 499       polkit may support non-standard features (such as the
 500       <emphasis>let</emphasis> keyword), authorization rules must
 501       conform to
 502       <ulink url="http://en.wikipedia.org/wiki/ECMAScript#ECMAScript.2C_5th_Edition">ECMA-262 edition 5</ulink>
 503       (in other words, the JavaScript interpreter used may change in future versions of polkit).
 504     </para>
 505
 506     <para>
 507       Authorization rules are intended for two specific audiences
 508     </para>
 509     <itemizedlist mark='opencircle' spacing='compact'>
 510       <listitem><para>System Administrators</para></listitem>
 511       <listitem><para>Special-purpose Operating Systems / Environments</para></listitem>
 512     </itemizedlist>
 513     <para>
 514       and those audiences only. In particular, applications,
 515       mechanisms and general-purpose operating systems must never
 516       include any authorization rules.
 517     </para>
 518
 519     <refsect2 id="polkit-rules-polkit">
 520       <title>The <type>Polkit</type> type</title>
 521
 522       <para>
 523         The following methods are available on the <literal>polkit</literal> object:
 524       </para>
 525
 526       <funcsynopsis>
 527         <funcprototype>
 528           <?dbhtml funcsynopsis-style='ansi'?>
 529           <funcdef>void <function>addRule</function></funcdef>
 530           <paramdef><type>polkit.Result</type> <function>function</function>(<parameter>action</parameter>, <parameter>subject</parameter>) {...}</paramdef>
 531         </funcprototype>
 532       </funcsynopsis>
 533
 534       <funcsynopsis>
 535         <funcprototype>
 536           <?dbhtml funcsynopsis-style='ansi'?>
 537           <funcdef>void <function>addAdminRule</function></funcdef>
 538           <paramdef>string[] <function>function</function>(<parameter>action</parameter>, <parameter>subject</parameter>) {...}</paramdef>
 539         </funcprototype>
 540       </funcsynopsis>
 541
 542       <funcsynopsis>
 543         <funcprototype>
 544           <?dbhtml funcsynopsis-style='ansi'?>
 545           <funcdef>void <function>log</function></funcdef>
 546           <paramdef>string <parameter>message</parameter></paramdef>
 547         </funcprototype>
 548       </funcsynopsis>
 549
 550       <funcsynopsis>
 551         <funcprototype>
 552           <?dbhtml funcsynopsis-style='ansi'?>
 553           <funcdef>string <function>spawn</function></funcdef>
 554           <paramdef>string[] <parameter>argv</parameter></paramdef>
 555         </funcprototype>
 556       </funcsynopsis>
 557
 558       <para>
 559         The <function>addRule()</function> method is used for adding a
 560         function that may be called whenever an authorization check for
 561         <parameter>action</parameter> and <parameter>subject</parameter>
 562         is performed. Functions are
 563         called in the order they have been added until one of the
 564         functions returns a value. Hence, to add an authorization rule
 565         that is processed before other rules, put it in a file in
 566         <filename class='directory'>/etc/polkit-1/rules.d</filename>
 567         with a name that sorts before other rules files, for example
 568         <filename>00-early-checks.rules</filename>. Each function should
 569         return a value from <literal>polkit.Result</literal>
 570       </para>
 571       <programlisting><![CDATA[
 572 polkit.Result = {
 573     NO              : "no",
 574     YES             : "yes",
 575     AUTH_SELF       : "auth_self",
 576     AUTH_SELF_KEEP  : "auth_self_keep",
 577     AUTH_ADMIN      : "auth_admin",
 578     AUTH_ADMIN_KEEP : "auth_admin_keep",
 579     NOT_HANDLED     : null
 580 };
 581 ]]></programlisting>
 582       <para>
 583         corresponding to the values that can be used as defaults. If
 584         the function returns
 585         <constant>polkit.Result.NOT_HANDLED</constant>,
 586         <constant>null</constant>, <constant>undefined</constant> or
 587         does not return a value at all, the next user function is
 588         tried.
 589       </para>
 590
 591       <para>
 592         Keep in mind that if <constant>polkit.Result.AUTH_SELF_KEEP</constant>
 593         or <constant>polkit.Result.AUTH_ADMIN_KEEP</constant> is returned,
 594         authorization checks for the same action identifier and
 595         subject will succeed (that is, return <constant>polkit.Result.YES</constant>) for the next
 596         brief period (e.g. five minutes) <emphasis>even</emphasis> if
 597         the variables passed along with the check are
 598         different. Therefore, if the result of an authorization rule
 599         depend on such variables, it should not use the
 600         <constant>"*_KEEP"</constant> constants (if similar functionality
 601         is required, the authorization rule can easily implement
 602         temporary authorizations using the
 603         <ulink url="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date"><type>Date</type></ulink>
 604         type for timestamps).
 605       </para>
 606
 607       <para>
 608         The <function>addAdminRule()</function> method is used for
 609         adding a function may be called whenever administrator
 610         authentication is required. The function is used to specify what
 611         identies may be used for administrator authentication for the
 612         authorization check identified by <parameter>action</parameter>
 613         and <parameter>subject</parameter>. Functions added are called in
 614         the order they have been added until one of the functions
 615         returns a value. Each function should return an array of strings
 616         where each string is of the form
 617         <literal>"unix-group:&lt;group&gt;"</literal>,
 618         <literal>"unix-netgroup:&lt;netgroup&gt;"</literal> or
 619         <literal>"unix-user:&lt;user&gt;"</literal>.  If the function
 620         returns <constant>null</constant>,
 621         <constant>undefined</constant> or does not return a value at
 622         all, the next function is tried.
 623       </para>
 624
 625       <para>
 626         There is no guarantee that a function registered with
 627         <function>addRule()</function> or
 628         <function>addAdminRule()</function> is ever called - for example
 629         an early rules file could register a function that always return
 630         a value, hence ensuring that functions added later are never
 631         called.
 632       </para>
 633
 634       <para>
 635         If user-provided code takes a long time to execute an exception
 636         will be thrown which normally results in the function being
 637         terminated (the current limit is 15 seconds). This is used to
 638         catch runaway scripts.
 639       </para>
 640
 641       <para>
 642         The <function>spawn()</function> method spawns an external
 643         helper identified by the argument vector
 644         <parameter>argv</parameter> and waits for it to terminate. If an
 645         error occurs or the helper doesn't exit normally with exit code
 646         0, an exception is thrown. If the helper does not exit within 10
 647         seconds it is killed. Otherwise, the program's
 648         <emphasis>standard output</emphasis> is returned as a string.
 649         The <function>spawn()</function> method should be used sparingly
 650         as helpers may take a very long or indeterminate amount of time
 651         to complete and no other authorization check can be handled
 652         while the helper is running. Note that the spawned programs
 653         will run as the unprivileged <emphasis>polkitd</emphasis> system
 654         user.
 655       </para>
 656
 657       <para>
 658         The <function>log()</function> method writes the given
 659         <parameter>message</parameter> to the system logger prefixed
 660         with the JavaScript filename and line number. Log entries are
 661         emitted using the <constant>LOG_AUTHPRIV</constant> flag meaning
 662         that the log entries usually ends up in the file
 663         <filename>/var/log/secure</filename>. The
 664         <function>log()</function> method is usually only used when
 665         debugging rules. The <type>Action</type> and
 666         <type>Subject</type> types has suitable
 667         <function>toString()</function> methods defined for easy
 668         logging, for example,
 669       </para>
 670       <programlisting><![CDATA[
 671 polkit.addRule(function(action, subject) {
 672     if (action.id == "org.freedesktop.policykit.exec") {
 673         polkit.log("action=" + action);
 674         polkit.log("subject=" + subject);
 675     }
 676 });
 677 ]]></programlisting>
 678       <para>
 679         will produce the following when the user runs 'pkexec -u bateman bash -i' from a shell:
 680       </para>
 681       <programlisting><![CDATA[
 682 May 24 14:28:50 thinkpad polkitd[32217]: /etc/polkit-1/rules.d/10-test.rules:3: action=[Action id='org.freedesktop.policykit.exec' command_line='/usr/bin/bash -i' program='/usr/bin/bash' user='bateman' user.gecos='Patrick Bateman' user.display='Patrick Bateman (bateman)']
 683 May 24 14:28:50 thinkpad polkitd[32217]: /etc/polkit-1/rules.d/10-test.rules:4: subject=[Subject pid=1352 user='davidz' groups=davidz,wheel, seat='seat0' session='1' local=true active=true]
 684 ]]></programlisting>
 685
 686     </refsect2>
 687
 688     <refsect2 id="polkit-rules-actions">
 689       <title>The <type>Action</type> type</title>
 690
 691       <para>
 692         The <parameter>action</parameter> parameter passed to user
 693         functions is an object with information about the action
 694         being checked. It is of type <type>Action</type> and has
 695         the following attribute:
 696       </para>
 697
 698       <variablelist id="polkit-js-action-attributes">
 699         <varlistentry>
 700           <term><type>string</type> id</term>
 701           <listitem>
 702             <para>
 703               The action identifier, for example
 704               <emphasis>org.freedesktop.policykit.exec</emphasis>.
 705             </para>
 706           </listitem>
 707         </varlistentry>
 708       </variablelist>
 709
 710       <para>
 711         The following methods are available on the <type>Action</type> type:
 712       </para>
 713
 714       <funcsynopsis>
 715         <funcprototype>
 716           <?dbhtml funcsynopsis-style='ansi'?>
 717           <funcdef>string <function>lookup</function></funcdef>
 718           <paramdef>string <parameter>key</parameter></paramdef>
 719         </funcprototype>
 720       </funcsynopsis>
 721
 722       <para>
 723         The <function>lookup()</function> method is used to lookup the
 724         polkit variables passed from the mechanism. For example, the
 725         <link linkend="pkexec.1"><citerefentry><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>
 726         mechanism sets the variable <parameter>program</parameter>
 727         which can be obtained in Javascript using the expression
 728         <literal>action.lookup("program")</literal>. If there is
 729         no value for the given <parameter>key</parameter>,
 730         then <constant>undefined</constant> is returned.
 731       </para>
 732       <para>
 733         Consult the documentation for each mechanism for what
 734         variables are available for each action.
 735       </para>
 736     </refsect2>
 737
 738     <refsect2 id="polkit-rules-subject">
 739       <title>The <type>Subject</type> type</title>
 740
 741       <para>
 742         The <parameter>subject</parameter> parameter passed to user
 743         functions is an object with information about the process
 744         being checked. It is of type <type>Subject</type> and has the
 745         following attributes
 746       </para>
 747
 748       <variablelist id="polkit-js-subject-attributes">
 749         <varlistentry>
 750           <term><type>int</type> pid</term>
 751           <listitem>
 752             <para>
 753               The process id.
 754             </para>
 755           </listitem>
 756         </varlistentry>
 757
 758         <varlistentry>
 759           <term><type>string</type> user</term>
 760           <listitem>
 761             <para>
 762               The user name.
 763             </para>
 764           </listitem>
 765         </varlistentry>
 766
 767         <varlistentry>
 768           <term><type>string[]</type> groups</term>
 769           <listitem>
 770             <para>
 771               Array of groups that <parameter>user</parameter> user belongs to.
 772             </para>
 773           </listitem>
 774         </varlistentry>
 775
 776         <varlistentry>
 777           <term><type>string</type> seat</term>
 778           <listitem>
 779             <para>
 780               The seat that the subject is associated with - blank if not on a local seat.
 781             </para>
 782           </listitem>
 783         </varlistentry>
 784
 785         <varlistentry>
 786           <term><type>string</type> session</term>
 787           <listitem>
 788             <para>
 789               The session that the subject is associated with.
 790             </para>
 791           </listitem>
 792         </varlistentry>
 793
 794         <varlistentry>
 795           <term><type>boolean</type> local</term>
 796           <listitem>
 797             <para>
 798               Set to <constant>true</constant> only if seat is local.
 799             </para>
 800           </listitem>
 801         </varlistentry>
 802
 803         <varlistentry>
 804           <term><type>boolean</type> active</term>
 805           <listitem>
 806             <para>
 807               Set to <constant>true</constant> only if the session is active.
 808             </para>
 809           </listitem>
 810         </varlistentry>
 811       </variablelist>
 812
 813       <para>
 814         The following methods are available on the <type>Subject</type> type:
 815       </para>
 816
 817       <funcsynopsis>
 818         <funcprototype>
 819           <?dbhtml funcsynopsis-style='ansi'?>
 820           <funcdef>boolean <function>isInGroup</function></funcdef>
 821           <paramdef>string <parameter>groupName</parameter></paramdef>
 822         </funcprototype>
 823       </funcsynopsis>
 824
 825       <funcsynopsis>
 826         <funcprototype>
 827           <?dbhtml funcsynopsis-style='ansi'?>
 828           <funcdef>boolean <function>isInNetGroup</function></funcdef>
 829           <paramdef>string <parameter>netGroupName</parameter></paramdef>
 830         </funcprototype>
 831       </funcsynopsis>
 832
 833       <para>
 834         The <function>isInGroup()</function> method can be used to
 835         check if the subject is in a given group and
 836         <function>isInNetGroup()</function> can be used to check if
 837         the subject is in a given netgroup.
 838       </para>
 839     </refsect2>
 840
 841     <refsect2 id="polkit-rules-examples">
 842       <title>Authorization Rules Examples</title>
 843
 844       <para>
 845         Allow all users in the <literal>admin</literal> group to
 846         perform user administration without changing policy for other
 847         users:
 848       </para>
 849       <programlisting><![CDATA[
 850 polkit.addRule(function(action, subject) {
 851     if (action.id == "org.freedesktop.accounts.user-administration" &&
 852         subject.isInGroup("admin")) {
 853         return polkit.Result.YES;
 854     }
 855 });
 856 ]]></programlisting>
 857
 858       <para>
 859         Define administrative users to be the users in the <literal>wheel</literal> group:
 860       </para>
 861       <programlisting><![CDATA[
 862 polkit.addAdminRule(function(action, subject) {
 863     return ["unix-group:wheel"];
 864 });
 865 ]]></programlisting>
 866
 867       <para>
 868         Forbid users in group <literal>children</literal> to change
 869         hostname configuration (that is, any action with an identifier
 870         starting with <literal>org.freedesktop.hostname1.</literal>)
 871         and allow anyone else to do it after authenticating as
 872         themselves:
 873       </para>
 874       <programlisting><![CDATA[
 875 polkit.addRule(function(action, subject) {
 876     if (action.id.indexOf("org.freedesktop.hostname1.") == 0) {
 877         if (subject.isInGroup("children")) {
 878             return polkit.Result.NO;
 879         } else {
 880             return polkit.Result.AUTH_SELF_KEEP;
 881         }
 882     }
 883 });
 884 ]]></programlisting>
 885
 886       <para>
 887         Run an external helper to determine if the current user may reboot the system:
 888       </para>
 889       <programlisting><![CDATA[
 890 polkit.addRule(function(action, subject) {
 891     if (action.id.indexOf("org.freedesktop.login1.reboot") == 0) {
 892         try {
 893             // user-may-reboot exits with succeess (exit code 0)
 894             // only if the passed username is authorized
 895             polkit.spawn(["/opt/company/bin/user-may-reboot",
 896                           subject.user]);
 897             return polkit.Result.YES;
 898         } catch (error) {
 899             // Nope, but do allow admin authentication
 900             return polkit.Result.AUTH_ADMIN;
 901         }
 902     }
 903 });
 904 ]]></programlisting>
 905
 906       <para>
 907         The following example shows how the authorization decision
 908         can depend on variables passed by the
 909         <link linkend="pkexec.1"><citerefentry><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>
 910         mechanism:
 911       </para>
 912       <programlisting><![CDATA[
 913 polkit.addRule(function(action, subject) {
 914     if (action.id == "org.freedesktop.policykit.exec" &&
 915         action.lookup("program") == "/usr/bin/cat") {
 916         return polkit.Result.AUTH_SELF;
 917     }
 918 });
 919 ]]></programlisting>
 920
 921       <para>
 922         The following example shows another use of variables passed from the
 923         mechanism. In this case, the mechanism is
 924         <ulink url="http://udisks.freedesktop.org/docs/latest/udisks.8.html">UDisks</ulink>
 925         which defines a set of
 926         <ulink url="http://udisks.freedesktop.org/docs/latest/udisks-polkit-actions.html">actions and variables</ulink>
 927         that is used to match on:
 928       </para>
 929       <programlisting><![CDATA[
 930 // Allow users in group 'engineers' to perform any operation on
 931 // some drives without having to authenticate
 932 //
 933 polkit.addRule(function(action, subject) {
 934     if (action.id.indexOf("org.freedesktop.udisks2.") == 0 &&
 935         action.lookup("drive.vendor") == "SEAGATE" &&
 936         action.lookup("drive.model") == "ST3300657SS" &&
 937         subject.isInGroup("engineers")) {
 938             return polkit.Result.YES;
 939         }
 940     }
 941 });
 942 ]]></programlisting>
 943     </refsect2>
 944   </refsect1>
 945
 946   <refsect1 id="polkit-author"><title>AUTHOR</title>
 947     <para>
 948       Written by David Zeuthen <email>davidz@redhat.com</email> with
 949       a lot of help from many others.
 950     </para>
 951   </refsect1>
 952
 953   <refsect1 id="polkit-bugs">
 954     <title>BUGS</title>
 955     <para>
 956       Please send bug reports to either the distribution or the
 957       polkit-devel mailing list,
 958       see the link <ulink url="http://lists.freedesktop.org/mailman/listinfo/polkit-devel"/>
 959       on how to subscribe.
 960     </para>
 961   </refsect1>
 962
 963   <refsect1 id="polkit-see-also">
 964     <title>SEE ALSO</title>
 965     <para>
 966       <link linkend="polkitd.8"><citerefentry><refentrytitle>polkitd</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
 967       <link linkend="pkaction.1"><citerefentry><refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
 968       <link linkend="pkcheck.1"><citerefentry><refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
 969       <link linkend="pkexec.1"><citerefentry><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
 970       <link linkend="pkttyagent.1"><citerefentry><refentrytitle>pkttyagent</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>
 971     </para>
 972   </refsect1>
 973 </refentry>