Debian Codegraph @

docs/man/polkit.xml

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