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. If
376       the duktape JavaScript backend is compiled in, instead of mozjs, no
377       exception will be thrown—the script will be killed right away (same
378       timeout).
379
380       The spawn() method spawns an external helper identified by the argument
381       vector argv and waits for it to terminate. If an error occurs or the
382       helper doesn't exit normally with exit code 0, an exception is thrown.
383       If the helper does not exit within 10 seconds, it is killed. Otherwise,
384       the program's standard output is returned as a string. The spawn()
385       method should be used sparingly as helpers may take a very long or
386       indeterminate amount of time to complete and no other authorization
387       check can be handled while the helper is running. Note that the spawned
388       programs will run as the unprivileged polkitd system user.
389
390       The log() method writes the given message to the system logger prefixed
391       with the JavaScript filename and line number. Log entries are emitted
392       using the LOG_AUTHPRIV flag meaning that the log entries usually ends
393       up in the file /var/log/secure. The log() method is usually only used
394       when debugging rules. The Action and Subject types has suitable
395       toString() methods defined for easy logging, for example,
396
397           polkit.addRule(function(action, subject) {
398               if (action.id == "org.freedesktop.policykit.exec") {
399                   polkit.log("action=" + action);
400                   polkit.log("subject=" + subject);
401               }
402           });
403
404       will produce the following when the user runs 'pkexec -u bateman bash
405       -i' from a shell:
406
407           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)']
408           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]
409
410   The Action type
411       The action parameter passed to user functions is an object with
412       information about the action being checked. It is of type Action and
413       has the following attribute:
414
415       string id
416           The action identifier, for example org.freedesktop.policykit.exec.
417
418       The following methods are available on the Action type:
419
420       string lookup(string key);
421
422       The lookup() method is used to lookup the polkit variables passed from
423       the mechanism. For example, the pkexec(1) mechanism sets the variable
424       program which can be obtained in JavaScript using the expression
425       action.lookup("program"). If there is no value for the given key, then
426       undefined is returned.
427
428       Consult the documentation for each mechanism for what variables are
429       available for each action.
430
431   The Subject type
432       The subject parameter passed to user functions is an object with
433       information about the process being checked. It is of type Subject and
434       has the following attributes
435
436       int pid
437           The process id.
438
439       string user
440           The user name.
441
442       string[] groups
443           Array of groups that user user belongs to.
444
445       string seat
446           The seat that the subject is associated with - blank if not on a
447           local seat.
448
449       string session
450           The session that the subject is associated with.
451
452       boolean local
453           Set to true only if seat is local.
454
455       boolean active
456           Set to true only if the session is active.
457
458       The following methods are available on the Subject type:
459
460       boolean isInGroup(string groupName);
461
462       boolean isInNetGroup(string netGroupName);
463
464       The isInGroup() method can be used to check if the subject is in a
465       given group and isInNetGroup() can be used to check if the subject is
466       in a given netgroup.
467
468   Authorization Rules Examples
469       Allow all users in the admin group to perform user administration
470       without changing policy for other users:
471
472           polkit.addRule(function(action, subject) {
473               if (action.id == "org.freedesktop.accounts.user-administration" &&
474                   subject.isInGroup("admin")) {
475                   return polkit.Result.YES;
476               }
477           });
478
479       Define administrative users to be the users in the wheel group:
480
481           polkit.addAdminRule(function(action, subject) {
482               return ["unix-group:wheel"];
483           });
484
485       Forbid users in group children to change hostname configuration (that
486       is, any action with an identifier starting with
487       org.freedesktop.hostname1.) and allow anyone else to do it after
488       authenticating as themselves:
489
490           polkit.addRule(function(action, subject) {
491               if (action.id.indexOf("org.freedesktop.hostname1.") == 0) {
492                   if (subject.isInGroup("children")) {
493                       return polkit.Result.NO;
494                   } else {
495                       return polkit.Result.AUTH_SELF_KEEP;
496                   }
497               }
498           });
499
500       Run an external helper to determine if the current user may reboot the
501       system:
502
503           polkit.addRule(function(action, subject) {
504               if (action.id.indexOf("org.freedesktop.login1.reboot") == 0) {
505                   try {
506                       // user-may-reboot exits with success (exit code 0)
507                       // only if the passed username is authorized
508                       polkit.spawn(["/opt/company/bin/user-may-reboot",
509                                     subject.user]);
510                       return polkit.Result.YES;
511                   } catch (error) {
512                       // Nope, but do allow admin authentication
513                       return polkit.Result.AUTH_ADMIN;
514                   }
515               }
516           });
517
518       The following example shows how the authorization decision can depend
519       on variables passed by the pkexec(1) mechanism:
520
521           polkit.addRule(function(action, subject) {
522               if (action.id == "org.freedesktop.policykit.exec" &&
523                   action.lookup("program") == "/usr/bin/cat") {
524                   return polkit.Result.AUTH_ADMIN;
525               }
526           });
527
528       The following example shows another use of variables passed from the
529       mechanism. In this case, the mechanism is UDisks[10] which defines a
530       set of actions and variables[11] that is used to match on:
531
532           // Allow users in group 'engineers' to perform any operation on
533           // some drives without having to authenticate
534           //
535           polkit.addRule(function(action, subject) {
536               if (action.id.indexOf("org.freedesktop.udisks2.") == 0 &&
537                   action.lookup("drive.vendor") == "SEAGATE" &&
538                   action.lookup("drive.model") == "ST3300657SS" &&
539                   subject.isInGroup("engineers")) {
540                       return polkit.Result.YES;
541                   }
542               }
543           });
544

AUTHOR

546       Written by David Zeuthen <davidz@redhat.com> with a lot of help from
547       many others.
548

BUGS

550       Please send bug reports to either the distribution or the polkit-devel
551       mailing list, see the link
552       https://gitlab.freedesktop.org/polkit/polkit/-/issues/ on how to
553       subscribe.
554

SEE ALSO

556       polkitd(8), pkaction(1), pkcheck(1), pkexec(1), pkttyagent(1)
557

NOTES

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