1POLKIT(8)                           polkit                           POLKIT(8)
2
3
4

NAME

6       polkit - Authorization Manager
7

OVERVIEW

9       polkit provides an authorization API intended to be used by privileged
10       programs (“MECHANISMS”) offering service to unprivileged programs
11       (“SUBJECTS”) often through some form of inter-process communication
12       mechanism. In this scenario, the mechanism typically treats the subject
13       as untrusted. For every request from a subject, the mechanism needs to
14       determine if the request is authorized or if it should refuse to
15       service the subject. Using the polkit APIs, a mechanism can offload
16       this decision to a trusted party: The polkit authority.
17
18       The polkit authority is implemented as an system daemon, polkitd(8),
19       which itself has little privilege as it is running as the polkitd
20       system user. Mechanisms, subjects and authentication agents communicate
21       with the authority using the system message bus.
22
23       In addition to acting as an authority, polkit allows users to obtain
24       temporary authorization through authenticating either an administrative
25       user or the owner of the session the client belongs to. This is useful
26       for scenarios where a mechanism needs to verify that the operator of
27       the system really is the user or really is an administrative user.
28

SYSTEM ARCHITECTURE

30       The system architecture of polkit is comprised of the Authority
31       (implemented as a service on the system message bus) and an
32       Authentication Agent per user session (provided and started by the
33       user's graphical environment).  Actions are defined by applications.
34       Vendors, sites and system administrators can control authorization
35       policy through Authorization Rules.
36
37           [IMAGE][1]
38
39                +-------------------+
40                |   Authentication  |
41                |       Agent       |
42                +-------------------+
43                | libpolkit-agent-1 |
44                +-------------------+
45                       ^                                  +---------+
46                       |                                  | Subject |
47                       +--------------+                   +---------+
48                                      |                        ^
49                                      |                        |
50               User Session           |                        |
51               =======================|========================|=============
52               System Context         |                        |
53                                      |                        |
54                                      |                    +---+
55                                      V                    |
56                                    /------------\         |
57                                    | System Bus |         |
58                                    \------------/         |
59                                      ^        ^           V
60                                      |        |      +---------------------+
61                       +--------------+        |      |      Mechanism      |
62                       |                       |      +---------------------+
63                       V                       +----> | libpolkit-gobject-1 |
64               +------------------+                   +---------------------+
65               |    polkitd(8)    |
66               +------------------+
67               | org.freedesktop. |
68               |    PolicyKit1    |<---------+
69               +------------------+          |
70                         ^                   |
71                         |            +--------------------------------------+
72                         |            | /usr/share/polkit-1/actions/*.policy |
73                         |            +--------------------------------------+
74                         |
75                  +--------------------------------------+
76                  | /etc/polkit-1/rules.d/*.rules        |
77                  | /usr/share/polkit-1/rules.d/*.rules  |
78                  +--------------------------------------+
79
80       For convenience, the libpolkit-gobject-1 library wraps the polkit D-Bus
81       API and is usable from any C/C++ program as well as higher-level
82       languages supporting GObjectIntrospection[2] such as JavaScript and
83       Python. A mechanism can also use the D-Bus API or the pkcheck(1)
84       command to check authorizations. The libpolkit-agent-1 library provides
85       an abstraction of the native authentication system, e.g.  pam(8) and
86       also facilities for registration and communication with the polkit
87       D-Bus service.
88
89       See the developer documentation[3] for more information about writing
90       polkit applications.
91

AUTHENTICATION AGENTS

93       An authentication agent is used to make the user of a session prove
94       that the user of the session really is the user (by authenticating as
95       the user) or an administrative user (by authenticating as an
96       administrator). In order to integrate well with the rest of the user
97       session (e.g. match the look and feel), authentication agents are meant
98       to be provided by the user session that the user uses. For example, an
99       authentication agent may look like this:
100
101           [IMAGE][4]
102
103               +----------------------------------------------------------+
104               |                                                          |
105               |  [Icon]  Authentication required                         |
106               |                                                          |
107               |          Authentication is required to format INTEL      |
108               |          SSDSA2MH080G1GC (/dev/sda)                      |
109               |                                                          |
110               |          Administrator                                   |
111               |                                                          |
112               |          Password: [__________________________________]  |
113               |                                                          |
114               | [Cancel]                                  [Authenticate] |
115               +----------------------------------------------------------+
116
117       If the system is configured without a root account, it may prompt for a
118       specific user designated as the administrative user:
119
120           [IMAGE][5]
121
122               +----------------------------------------------------------+
123               |                                                          |
124               |  [Icon]  Authentication required                         |
125               |                                                          |
126               |          Authentication is required to format INTEL      |
127               |          SSDSA2MH080G1GC (/dev/sda)                      |
128               |                                                          |
129               |          [Icon] David Zeuthen                            |
130               |                                                          |
131               |          Password: [__________________________________]  |
132               |                                                          |
133               | [Cancel]                                  [Authenticate] |
134               +----------------------------------------------------------+
135
136       Applications that do not run under a desktop environment (for example,
137       if launched from an ssh(1) login) may not have an authentication agent
138       associated with them. Such applications may use the
139       PolkitAgentTextListener type or the pkttyagent(1) helper so the user
140       can authenticate using a textual interface.
141

DECLARING ACTIONS

143       A mechanism needs to declare a set of actions in order to use polkit.
144       Actions correspond to operations that clients can request the mechanism
145       to carry out and are defined in XML files that the mechanism installs
146       into the /usr/share/polkit-1/actions directory.
147
148       polkit actions are namespaced and can only contain the characters
149       "[A-Z][a-z][0-9].-", e.g. ASCII, digits, period and hyphen. Each XML
150       file can contain more than one action but all actions need to be in the
151       same namespace and the file needs to be named after the namespace and
152       have the extension .policy.
153
154       The XML file must have the following doctype declaration
155
156           <?xml version="1.0" encoding="UTF-8"?>
157           <!DOCTYPE policyconfig PUBLIC "-//freedesktop//DTD polkit Policy Configuration 1.0//EN"
158           "http://www.freedesktop.org/software/polkit/policyconfig-1.dtd">
159
160       The policyconfig element must be present exactly once. Elements that
161       can be used inside policyconfig includes:
162
163       vendor
164           The name of the project or vendor that is supplying the actions in
165           the XML document. Optional.
166
167       vendor_url
168           A URL to the project or vendor that is supplying the actions in the
169           XML document. Optional.
170
171       icon_name
172           An icon representing the project or vendor that is supplying the
173           actions in the XML document. The icon name must adhere to the
174           Freedesktop.org Icon Naming Specification[6]. Optional.
175
176       action
177           Declares an action. The action name is specified using the id
178           attribute and can only contain the characters "[A-Z][a-z][0-9].- ",
179           e.g. ASCII, digits, period and hyphen.
180
181       Elements that can be used inside action include:
182
183       description
184           A human readable description of the action, e.g.  “Install unsigned
185           software”.
186
187       message
188           A human readable message displayed to the user when asking for
189           credentials when authentication is needed, e.g.  “Installing
190           unsigned software requires authentication”.
191
192       defaults
193           This element is used to specify implicit authorizations for
194           clients. Elements that can be used inside defaults include:
195
196           allow_any
197               Implicit authorizations that apply to any client. Optional.
198
199           allow_inactive
200               Implicit authorizations that apply to clients in inactive
201               sessions on local consoles. Optional.
202
203           allow_active
204               Implicit authorizations that apply to clients in active
205               sessions on local consoles. Optional.
206
207           Each of the allow_any, allow_inactive and allow_active elements can
208           contain the following values:
209
210           no
211               Not authorized.
212
213           yes
214               Authorized.
215
216           auth_self
217               Authentication by the owner of the session that the client
218               originates from is required. Note that this is not restrictive
219               enough for most uses on multi-user systems; auth_admin* is
220               generally recommended.
221
222           auth_admin
223               Authentication by an administrative user is required.
224
225           auth_self_keep
226               Like auth_self but the authorization is kept for a brief period
227               (e.g. five minutes). The warning about auth_self above applies
228               likewise.
229
230           auth_admin_keep
231               Like auth_admin but the authorization is kept for a brief
232               period (e.g. five minutes).
233
234       annotate
235           Used for annotating an action with a key/value pair. The key is
236           specified using the key attribute and the value is specified using
237           the value attribute. This element may appear zero or more times.
238           See below for known annotations.
239
240       vendor
241           Used for overriding the vendor on a per-action basis. Optional.
242
243       vendor_url
244           Used for overriding the vendor URL on a per-action basis. Optional.
245
246       icon_name
247           Used for overriding the icon name on a per-action basis. Optional.
248
249       For localization, description and message elements may occur multiple
250       times with different xml:lang attributes.
251
252       To list installed polkit actions, use the pkaction(1) command.
253
254   Known annotations
255       The org.freedesktop.policykit.exec.path annotation is used by the
256       pkexec program shipped with polkit - see the pkexec(1) man page for
257       details.
258
259       The org.freedesktop.policykit.imply annotation (its value is a string
260       containing a space-separated list of action identifiers) can be used to
261       define meta actions. The way it works is that if a subject is
262       authorized for an action with this annotation, then it is also
263       authorized for any action specified by the annotation. A typical use of
264       this annotation is when defining an UI shell with a single lock button
265       that should unlock multiple actions from distinct mechanisms.
266
267       The org.freedesktop.policykit.owner annotation can be used to define a
268       set of users who can query whether a client is authorized to perform
269       this action. If this annotation is not specified, then only root can
270       query whether a client running as a different user is authorized for an
271       action. The value of this annotation is a string containing a
272       space-separated list of PolkitIdentity entries, for example
273       "unix-user:42 unix-user:colord". A typical use of this annotation is
274       for a daemon process that runs as a system user rather than root.
275

AUTHORIZATION RULES

277       polkitd reads .rules files from the /etc/polkit-1/rules.d and
278       /usr/share/polkit-1/rules.d directories by sorting the files in lexical
279       order based on the basename on each file (if there's a tie, files in
280       /etc are processed before files in /usr). For example, for the
281       following four files, the order is
282
283       •   /etc/polkit-1/rules.d/10-auth.rules
284
285       •   /usr/share/polkit-1/rules.d/10-auth.rules
286
287       •   /etc/polkit-1/rules.d/15-auth.rules
288
289       •   /usr/share/polkit-1/rules.d/20-auth.rules
290
291       Both directories are monitored so if a rules file is changed, added or
292       removed, existing rules are purged and all files are read and processed
293       again. Rules files are written in the JavaScript[7] programming
294       language and interface with polkitd through the global polkit object
295       (of type Polkit).
296
297       While the JavaScript interpreter used in particular versions of polkit
298       may support non-standard features (such as the let keyword),
299       authorization rules must conform to ECMA-262 edition 5[8] (in other
300       words, the JavaScript interpreter used may change in future versions of
301       polkit).
302
303       Authorization rules are intended for two specific audiences
304
305       •   System Administrators
306
307       •   Special-purpose Operating Systems / Environments
308
309       and those audiences only. In particular, applications, mechanisms and
310       general-purpose operating systems must never include any authorization
311       rules.
312
313   The Polkit type
314       The following methods are available on the polkit object:
315
316       void addRule(polkit.Result function(action, subject) {...});
317
318       void addAdminRule(string[] function(action, subject) {...});
319
320       void log(string message);
321
322       string spawn(string[] argv);
323
324       The addRule() method is used for adding a function that may be called
325       whenever an authorization check for action and subject is performed.
326       Functions are called in the order they have been added until one of the
327       functions returns a value. Hence, to add an authorization rule that is
328       processed before other rules, put it in a file in /etc/polkit-1/rules.d
329       with a name that sorts before other rules files, for example
330       00-early-checks.rules. Each function should return a value from
331       polkit.Result
332
333           polkit.Result = {
334               NO              : "no",
335               YES             : "yes",
336               AUTH_SELF       : "auth_self",
337               AUTH_SELF_KEEP  : "auth_self_keep",
338               AUTH_ADMIN      : "auth_admin",
339               AUTH_ADMIN_KEEP : "auth_admin_keep",
340               NOT_HANDLED     : null
341           };
342
343       corresponding to the values that can be used as defaults. If the
344       function returns polkit.Result.NOT_HANDLED, null, undefined or does not
345       return a value at all, the next user function is tried.
346
347       Keep in mind that if polkit.Result.AUTH_SELF_KEEP or
348       polkit.Result.AUTH_ADMIN_KEEP is returned, authorization checks for the
349       same action identifier and subject will succeed (that is, return
350       polkit.Result.YES) for the next brief period (e.g. five minutes) even
351       if the variables passed along with the check are different. Therefore,
352       if the result of an authorization rule depend on such variables, it
353       should not use the "*_KEEP" constants (if similar functionality is
354       required, the authorization rule can easily implement temporary
355       authorizations using the Date[9] type for timestamps).
356
357       The addAdminRule() method is used for adding a function that may be
358       called whenever administrator authentication is required. The function
359       is used to specify what identities may be used for administrator
360       authentication for the authorization check identified by action and
361       subject. Functions added are called in the order they have been added
362       until one of the functions returns a value. Each function should return
363       an array of strings where each string is of the form
364       "unix-group:<group>", "unix-netgroup:<netgroup>" or "unix-user:<user>".
365       If the function returns null, undefined or does not return a value at
366       all, the next function is tried.
367
368       There is no guarantee that a function registered with addRule() or
369       addAdminRule() is ever called - for example an early rules file could
370       register a function that always returns a value, hence ensuring that
371       functions added later are never called.
372
373       If user-provided code takes a long time to execute, an exception will
374       be thrown which normally results in the function being terminated (the
375       current limit is 15 seconds). This is used to catch runaway scripts.
376
377       The spawn() method spawns an external helper identified by the argument
378       vector argv and waits for it to terminate. If an error occurs or the
379       helper doesn't exit normally with exit code 0, an exception is thrown.
380       If the helper does not exit within 10 seconds, it is killed. Otherwise,
381       the program's standard output is returned as a string. The spawn()
382       method should be used sparingly as helpers may take a very long or
383       indeterminate amount of time to complete and no other authorization
384       check can be handled while the helper is running. Note that the spawned
385       programs will run as the unprivileged polkitd system user.
386
387       The log() method writes the given message to the system logger prefixed
388       with the JavaScript filename and line number. Log entries are emitted
389       using the LOG_AUTHPRIV flag meaning that the log entries usually ends
390       up in the file /var/log/secure. The log() method is usually only used
391       when debugging rules. The Action and Subject types has suitable
392       toString() methods defined for easy logging, for example,
393
394           polkit.addRule(function(action, subject) {
395               if (action.id == "org.freedesktop.policykit.exec") {
396                   polkit.log("action=" + action);
397                   polkit.log("subject=" + subject);
398               }
399           });
400
401       will produce the following when the user runs 'pkexec -u bateman bash
402       -i' from a shell:
403
404           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)']
405           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]
406
407   The Action type
408       The action parameter passed to user functions is an object with
409       information about the action being checked. It is of type Action and
410       has the following attribute:
411
412       string id
413           The action identifier, for example org.freedesktop.policykit.exec.
414
415       The following methods are available on the Action type:
416
417       string lookup(string key);
418
419       The lookup() method is used to lookup the polkit variables passed from
420       the mechanism. For example, the pkexec(1) mechanism sets the variable
421       program which can be obtained in JavaScript using the expression
422       action.lookup("program"). If there is no value for the given key, then
423       undefined is returned.
424
425       Consult the documentation for each mechanism for what variables are
426       available for each action.
427
428   The Subject type
429       The subject parameter passed to user functions is an object with
430       information about the process being checked. It is of type Subject and
431       has the following attributes
432
433       int pid
434           The process id.
435
436       string user
437           The user name.
438
439       string[] groups
440           Array of groups that user user belongs to.
441
442       string seat
443           The seat that the subject is associated with - blank if not on a
444           local seat.
445
446       string session
447           The session that the subject is associated with.
448
449       boolean local
450           Set to true only if seat is local.
451
452       boolean active
453           Set to true only if the session is active.
454
455       The following methods are available on the Subject type:
456
457       boolean isInGroup(string groupName);
458
459       boolean isInNetGroup(string netGroupName);
460
461       The isInGroup() method can be used to check if the subject is in a
462       given group and isInNetGroup() can be used to check if the subject is
463       in a given netgroup.
464
465   Authorization Rules Examples
466       Allow all users in the admin group to perform user administration
467       without changing policy for other users:
468
469           polkit.addRule(function(action, subject) {
470               if (action.id == "org.freedesktop.accounts.user-administration" &&
471                   subject.isInGroup("admin")) {
472                   return polkit.Result.YES;
473               }
474           });
475
476       Define administrative users to be the users in the wheel group:
477
478           polkit.addAdminRule(function(action, subject) {
479               return ["unix-group:wheel"];
480           });
481
482       Forbid users in group children to change hostname configuration (that
483       is, any action with an identifier starting with
484       org.freedesktop.hostname1.) and allow anyone else to do it after
485       authenticating as themselves:
486
487           polkit.addRule(function(action, subject) {
488               if (action.id.indexOf("org.freedesktop.hostname1.") == 0) {
489                   if (subject.isInGroup("children")) {
490                       return polkit.Result.NO;
491                   } else {
492                       return polkit.Result.AUTH_SELF_KEEP;
493                   }
494               }
495           });
496
497       Run an external helper to determine if the current user may reboot the
498       system:
499
500           polkit.addRule(function(action, subject) {
501               if (action.id.indexOf("org.freedesktop.login1.reboot") == 0) {
502                   try {
503                       // user-may-reboot exits with success (exit code 0)
504                       // only if the passed username is authorized
505                       polkit.spawn(["/opt/company/bin/user-may-reboot",
506                                     subject.user]);
507                       return polkit.Result.YES;
508                   } catch (error) {
509                       // Nope, but do allow admin authentication
510                       return polkit.Result.AUTH_ADMIN;
511                   }
512               }
513           });
514
515       The following example shows how the authorization decision can depend
516       on variables passed by the pkexec(1) mechanism:
517
518           polkit.addRule(function(action, subject) {
519               if (action.id == "org.freedesktop.policykit.exec" &&
520                   action.lookup("program") == "/usr/bin/cat") {
521                   return polkit.Result.AUTH_ADMIN;
522               }
523           });
524
525       The following example shows another use of variables passed from the
526       mechanism. In this case, the mechanism is UDisks[10] which defines a
527       set of actions and variables[11] that is used to match on:
528
529           // Allow users in group 'engineers' to perform any operation on
530           // some drives without having to authenticate
531           //
532           polkit.addRule(function(action, subject) {
533               if (action.id.indexOf("org.freedesktop.udisks2.") == 0 &&
534                   action.lookup("drive.vendor") == "SEAGATE" &&
535                   action.lookup("drive.model") == "ST3300657SS" &&
536                   subject.isInGroup("engineers")) {
537                       return polkit.Result.YES;
538                   }
539               }
540           });
541

AUTHOR

543       Written by David Zeuthen <davidz@redhat.com> with a lot of help from
544       many others.
545

BUGS

547       Please send bug reports to either the distribution or the polkit-devel
548       mailing list, see the link
549       http://lists.freedesktop.org/mailman/listinfo/polkit-devel on how to
550       subscribe.
551

SEE ALSO

553       polkitd(8), pkaction(1), pkcheck(1), pkexec(1), pkttyagent(1)
554

NOTES

556        1. /usr/share/gtk-doc/html/polkit-1/polkit-architecture.png
557
558        2. GObjectIntrospection
559           https://live.gnome.org/GObjectIntrospection
560
561        3. developer documentation
562           http://www.freedesktop.org/software/polkit/docs/latest/
563
564        4. /usr/share/gtk-doc/html/polkit-1/polkit-authentication-agent-
565           example.png
566
567        5. /usr/share/gtk-doc/html/polkit-1/polkit-authentication-agent-
568           example-wheel.png
569
570        6. Freedesktop.org Icon Naming Specification
571           http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
572
573        7. JavaScript
574           http://en.wikipedia.org/wiki/JavaScript
575
576        8. ECMA-262 edition 5
577           http://en.wikipedia.org/wiki/ECMAScript#ECMAScript.2C_5th_Edition
578
579        9. Date
580           https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
581
582       10. UDisks
583           http://udisks.freedesktop.org/docs/latest/udisks.8.html
584
585       11. actions and variables
586           http://udisks.freedesktop.org/docs/latest/udisks-polkit-actions.html
587
588
589
590polkit                           February 2021                       POLKIT(8)
Impressum