1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
|
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "../version.xml">
]>
<refentry id="polkit.8" xmlns:xi="http://www.w3.org/2003/XInclude">
<refentryinfo>
<title>polkit</title>
<date>January 2009</date>
<productname>polkit</productname>
</refentryinfo>
<refmeta>
<refentrytitle>polkit</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo class="version"></refmiscinfo>
</refmeta>
<refnamediv>
<refname>polkit</refname>
<refpurpose>Authorization Framework</refpurpose>
</refnamediv>
<refsect1 id="polkit-overview"><title>OVERVIEW</title>
<para>
PolicyKit provides an authorization API intended to be used by
privileged programs (<quote>MECHANISMS</quote>) offering service
to unprivileged programs (<quote>CLIENTS</quote>) through some
form of IPC mechanism such as D-Bus or Unix pipes. In this
scenario, the mechanism typically treats the client as
untrusted. For every request from a client, the mechanism needs
to determine if the request is authorized or if it should refuse
to service the client. Using the PolicyKit API, a mechanism can
offload this decision to a trusted party: The PolicyKit
Authority.
</para>
<para>
In addition to acting as an authority, PolicyKit allows users to
obtain temporary authorization through authenticating either an
administrative user or the owner of the session the client
belongs to. This is useful for scenarios where a mechanism needs
to verify that the operator of the system really is the user or
really is an administrative user.
</para>
</refsect1>
<refsect1 id="polkit-system-architecture"><title>SYSTEM ARCHITECTURE</title>
<para>
The system architecture of PolicyKit is comprised of
the <emphasis>Authority</emphasis> (implemented as a service on
the system message bus) and a
<emphasis>Authentication Agent</emphasis> per user session
(provided and started by the user session e.g. GNOME or KDE).
Additionally, PolicyKit supports a number of extension points –
specifically, vendors and/or sites can write extensions to
completely control authorization policy. In a block diagram, the
architecture looks like this:
</para>
<mediaobject id="polkit-architecture">
<imageobject>
<imagedata fileref="polkit-architecture.png" format="PNG"/>
</imageobject>
<textobject>
<programlisting><![CDATA[
+-------------------+
| Authentication |
| Agent |
+-------------------+
| libpolkit-agent-1 |
+-------------------+
^ +--------+
| | Client |
+--------------+ +--------+
| ^
| |
User Session | |
=======================|========================|=============
System Context | |
| |
| +---+
V |
/------------\ |
| System Bus | |
\------------/ |
^ ^ V
| | +---------------------+
+--------------+ | | Mechanism |
| | +---------------------+
V +----> | libpolkit-gobject-1 |
+------------------+ +---------------------+
| org.freedesktop. |
| PolicyKit1 |
+------------------+
| Backends and |
| Extensions |
+------------------+
]]></programlisting>
</textobject>
</mediaobject>
<para>
For convenience, the <literal>libpolkit-gobject-1</literal>
library wraps the PolicyKit D-Bus API using GObject. However, a
mechanism can also use the D-Bus API or the
<citerefentry><refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum></citerefentry>
command to check authorizations.
</para>
<para>
The <literal>libpolkit-agent-1</literal> library provides an
abstraction of the native authentication system, e.g.
<citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>
and also facilities registration and communication with the
PolicyKit D-Bus service.
</para>
<para>
PolicyKit extensions and authority backends are implemented
using the
<literal>libpolkit-backend-1</literal> library.
</para>
<para>
See the
<ulink url="file:///usr/share/gtk-doc/html/polkit-1/index.html">developer
documentation</ulink> for more information about using and
extending PolicyKit.
</para>
<para>
See
<citerefentry><refentrytitle>pklocalauthority</refentrytitle><manvolnum>8</manvolnum></citerefentry>
for information about the Local Authority - the default
authority implementation shipped with PolicyKit.
</para>
</refsect1>
<refsect1 id="polkit-authentication-agents"><title>AUTHENTICATION AGENTS</title>
<para>
An authentication agent is used to make the user of a session
prove that the user of the session really is the user (by
authenticating as the user) or an administrative user (by
authenticating as a administrator). In order to integrate well
with the rest of the user session (e.g. match the look and
feel), authentication agents are meant to be provided by the
user session that the user uses. For example, an authentication
agent may look like this:
</para>
<mediaobject id="polkit-authentication-agent-example">
<imageobject>
<imagedata fileref="polkit-authentication-agent-example.png" format="PNG"/>
</imageobject>
<textobject>
<programlisting><![CDATA[
+----------------------------------------------------------+
| Authenticate [X] |
+----------------------------------------------------------+
| |
| [Icon] Authentication is required to run ATA SMART |
| self tests |
| |
| An application is attempting to perform an |
| action that requires privileges. Authentication |
| as the super user is required to perform this |
| action. |
| |
| Password for root: [_________________________] |
| |
| [V] Details: |
| Drive: ATA INTEL SSDSA2MH08 (045C) |
| Device: /dev/sda |
| Action: org.fd.devicekit.disks.drive-ata-smart-selftest |
| Vendor: The DeviceKit Project |
| |
| [Cancel] [Authenticate] |
+----------------------------------------------------------+
]]></programlisting>
</textobject>
</mediaobject>
<para>
If the system is configured without a <emphasis>root</emphasis>
account it may allow you to select the administrative user who
is authenticating:
</para>
<mediaobject id="polkit-authentication-agent-example-wheel">
<imageobject>
<imagedata fileref="polkit-authentication-agent-example-wheel.png" format="PNG"/>
</imageobject>
<textobject>
<programlisting><![CDATA[
+----------------------------------------------------------+
| Authenticate [X] |
+----------------------------------------------------------+
| |
| [Icon] Authentication is required to run ATA SMART |
| self tests |
| |
| An application is attempting to perform an |
| action that requires privileges. Authentication |
| as one of the users below is required to |
| perform this action. |
| |
| [[Face] Patrick Bateman (bateman) [V]] |
| |
| Password for bateman: [______________________] |
| |
| [V] Details: |
| Drive: ATA INTEL SSDSA2MH08 (045C) |
| Device: /dev/sda |
| Action: org.fd.devicekit.disks.drive-ata-smart-selftest |
| Vendor: The DeviceKit Project |
| |
| [Cancel] [Authenticate] |
+----------------------------------------------------------+
]]></programlisting>
</textobject>
</mediaobject>
<para>
See
<citerefentry><refentrytitle>pklocalauthority</refentrytitle><manvolnum>8</manvolnum></citerefentry>
on how to set up the local authority
implemention for systems without a <literal>root</literal>
account.
</para>
</refsect1>
<refsect1 id="polkit-declaring-actions"><title>DECLARING ACTIONS</title>
<para>
A mechanism need to declare a set of <quote>ACTIONS</quote> in
order to use PolicyKit. Actions correspond to operations that
clients can request the mechanism to carry out and are defined
in XML files that the mechanism installs into
the <filename>/usr/share/polkit-1/actions</filename> directory.
</para>
<para>
PolicyKit actions are namespaced and can only contain the
characters <literal>[a-z][0-9].-</literal> e.g. lower-case
ASCII, digits, period and hyphen. Each XML file can contain more
than one action but all actions need to be in the same namespace
and the file needs to be named after the namespace and have the
extension <literal>.policy</literal>.
</para>
<para>
The XML file must have the following doctype declaration
</para>
<programlisting><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE policyconfig PUBLIC "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
"http://www.freedesktop.org/standards/PolicyKit/1.0/policyconfig.dtd">
]]></programlisting>
<para>
The <emphasis>policyconfig</emphasis> element must be present
exactly once. Elements that can be used
inside <emphasis>policyconfig</emphasis> includes:
</para>
<variablelist>
<varlistentry>
<term><emphasis>vendor</emphasis></term>
<listitem><para>The name of the project or vendor that is
supplying the actions in the XML
document. Optional.</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>vendor_url</emphasis></term>
<listitem><para>A URL to the project or vendor that is
supplying the actions in the XML document.
Optional.</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>icon_name</emphasis></term>
<listitem><para>An icon representing the project or vendor
that is supplying the actions in the XML document. The icon
name must adhere to
the <ulink url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Freedesktop.org
Icon Naming Specification</ulink>. Optional.</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>action</emphasis></term>
<listitem><para>Declares an action. The action name is
specified using the <literal>id</literal> attribute and can
only contain the characters <literal>[a-z][0-9].-</literal>
e.g. lower-case ASCII, digits, period and
hyphen.</para></listitem>
</varlistentry>
</variablelist>
<para>
Elements that can be used inside <emphasis>action</emphasis> includes:
</para>
<variablelist>
<varlistentry>
<term><emphasis>description</emphasis></term>
<listitem><para>A human readable description of the action, e.g. <quote>Install unsigned software</quote>.</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>message</emphasis></term>
<listitem><para>A human readable message displayed to the user when asking for credentials when authentication is needed, e.g. <quote>Installing unsigned software requires authentication</quote>.</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>defaults</emphasis></term>
<listitem><para>This element is used to specify implicit authorizations for clients.</para>
<para>
Elements that can be used inside <emphasis>defaults</emphasis> includes:
</para>
<variablelist>
<varlistentry>
<term><emphasis>allow_any</emphasis></term>
<listitem><para>Implicit authorizations that apply to
any client. Optional.</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>allow_inactive</emphasis></term>
<listitem><para>Implicit authorizations that apply to
clients in inactive sessions on local
consoles. Optional.</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>allow_active</emphasis></term>
<listitem><para>Implicit authorizations that apply to
clients in active sessions on local
consoles. Optional.</para></listitem>
</varlistentry>
</variablelist>
<para>
Each of
the <emphasis>allow_any</emphasis>, <emphasis>allow_inactive</emphasis>
and <emphasis>allow_active</emphasis> elements can contain
the following values:
</para>
<variablelist>
<varlistentry>
<term><literal>no</literal></term>
<listitem><para>Not authorized.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>yes</literal></term>
<listitem><para>Authorized.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>auth_self</literal></term>
<listitem><para>Authentication by the owner of the
session that the client originates from is
required.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>auth_admin</literal></term>
<listitem><para>Authentication by an administrative user
is required.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>auth_self_keep</literal></term>
<listitem><para>Like <literal>auth_self</literal> but
the authorization is kept for a brief
period.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>auth_admin_keep</literal></term>
<listitem><para>Like <literal>auth_admin</literal> but the authorization is kept for a brief period.</para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis>annotate</emphasis></term>
<listitem><para>Used for annotating an action with a key/value
pair. The key is specified using the
the <literal>key</literal> attribute and the value is
specified using the <literal>value</literal> attribute. This
element may appear zero or more times. See
below for known annotations. </para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>vendor</emphasis></term>
<listitem><para>Used for overriding the vendor on a per-action
basis. Optional.</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>vendor_url</emphasis></term>
<listitem><para>Used for overriding the vendor URL on a
per-action basis. Optional.</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>icon_name</emphasis></term>
<listitem><para>Used for overriding the icon name on a
per-action basis. Optional.</para></listitem>
</varlistentry>
</variablelist>
<para>
For localization, <emphasis>description</emphasis>
and <emphasis>message</emphasis> elements may occur multiple
times with different <literal>xml:lang</literal> attributes.
</para>
<para>
To list installed PolicyKit actions, use the
<citerefentry><refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum></citerefentry>
command.
</para>
<refsect2><title>Known annotations</title>
<para>
The <literal>org.freedesktop.policykit.exec.path</literal>
annotation is used by the <command>pkexec</command> program
shipped with PolicyKit - see the
<citerefentry><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry>
man page for details.
</para>
<para>
The <literal>org.freedesktop.policykit.imply</literal>
annotation (its value is a string containing a space separated
list of action identifiers) can be used to define <emphasis>meta
actions</emphasis>. The way it works is that if a subject is
authorized for an action with this annotation, then it is also
authorized for any action specified by the annotation. A typical
use of this annotation is when defining an UI shell with a
single lock button that should unlock multiple actions from
distinct mechanisms.
</para>
</refsect2>
</refsect1>
<refsect1 id="polkit-author"><title>AUTHOR</title>
<para>
Written by David Zeuthen <email>davidz@redhat.com</email> with
a lot of help from many others.
</para>
</refsect1>
<refsect1 id="polkit-bugs">
<title>BUGS</title>
<para>
Please send bug reports to either the distribution or the
polkit-devel mailing list,
see the link <ulink url="http://lists.freedesktop.org/mailman/listinfo/polkit-devel"/>
on how to subscribe.
</para>
</refsect1>
<refsect1 id="polkit-see-also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pklocalauthority</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
<citerefentry>
<refentrytitle>polkitd</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
<citerefentry>
<refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>,
</para>
</refsect1>
</refentry>
|