1POLKIT(8) polkit POLKIT(8)
2
6 polkit - Authorization Framework
7
9 PolicyKit provides an authorization API intended to be used by
10 privileged programs (“MECHANISMS”) offering service to unprivileged
11 programs (“CLIENTS”) through some form of IPC mechanism such as D-Bus
12 or Unix pipes. In this scenario, the mechanism typically treats the
13 client as untrusted. For every request from a client, the mechanism
14 needs to determine if the request is authorized or if it should refuse
15 to service the client. Using the PolicyKit API, a mechanism can offload
16 this decision to a trusted party: The PolicyKit Authority.
17 In addition to acting as an authority, PolicyKit allows users to obtain
19 temporary authorization through authenticating either an administrative
20 user or the owner of the session the client belongs to. This is useful
21 for scenarios where a mechanism needs to verify that the operator of
22 the system really is the user or really is an administrative user.
23
25 The system architecture of PolicyKit is comprised of the Authority
26 (implemented as a service on the system message bus) and a
27 Authentication Agent per user session (provided and started by the user
28 session e.g. GNOME or KDE). Additionally, PolicyKit supports a number
29 of extension points – specifically, vendors and/or sites can write
30 extensions to completely control authorization policy. In a block
31 diagram, the architecture looks like this:
32 [IMAGE][1]
34 +-------------------+
36 | Authentication |
37 | Agent |
38 +-------------------+
39 | libpolkit-agent-1 |
40 +-------------------+
41 ^ +--------+
42 | | Client |
43 +--------------+ +--------+
44 | ^
45 | |
46 User Session | |
47 =======================|========================|=============
48 System Context | |
49 | |
50 | +---+
51 V |
52 /------------\ |
53 | System Bus | |
54 \------------/ |
55 ^ ^ V
56 | | +---------------------+
57 +--------------+ | | Mechanism |
58 | | +---------------------+
59 V +----> | libpolkit-gobject-1 |
60 +------------------+ +---------------------+
61 | org.freedesktop. |
62 | PolicyKit1 |
63 +------------------+
64 | Backends and |
65 | Extensions |
66 +------------------+
67 For convenience, the libpolkit-gobject-1 library wraps the PolicyKit
69 D-Bus API using GObject. However, a mechanism can also use the D-Bus
70 API or the pkcheck(1) command to check authorizations.
71 The libpolkit-agent-1 library provides an abstraction of the native
73 authentication system, e.g. pam(8) and also facilities registration
74 and communication with the PolicyKit D-Bus service.
75 PolicyKit extensions and authority backends are implemented using the
77 libpolkit-backend-1 library.
78 See the developer documentation[2] for more information about using and
80 extending PolicyKit.
81 See pklocalauthority(8) for information about the Local Authority - the
83 default authority implementation shipped with PolicyKit.
84
86 An authentication agent is used to make the user of a session prove
87 that the user of the session really is the user (by authenticating as
88 the user) or an administrative user (by authenticating as a
89 administrator). In order to integrate well with the rest of the user
90 session (e.g. match the look and feel), authentication agents are meant
91 to be provided by the user session that the user uses. For example, an
92 authentication agent may look like this:
93 [IMAGE][3]
95 +----------------------------------------------------------+
97 | Authenticate [X] |
98 +----------------------------------------------------------+
99 | |
100 | [Icon] Authentication is required to run ATA SMART |
101 | self tests |
102 | |
103 | An application is attempting to perform an |
104 | action that requires privileges. Authentication |
105 | as the super user is required to perform this |
106 | action. |
107 | |
108 | Password for root: [_________________________] |
109 | |
110 | [V] Details: |
111 | Drive: ATA INTEL SSDSA2MH08 (045C) |
112 | Device: /dev/sda |
113 | Action: org.fd.devicekit.disks.drive-ata-smart-selftest |
114 | Vendor: The DeviceKit Project |
115 | |
116 | [Cancel] [Authenticate] |
117 +----------------------------------------------------------+
118 If the system is configured without a root account it may allow you to
120 select the administrative user who is authenticating:
121 [IMAGE][4]
123 +----------------------------------------------------------+
125 | Authenticate [X] |
126 +----------------------------------------------------------+
127 | |
128 | [Icon] Authentication is required to run ATA SMART |
129 | self tests |
130 | |
131 | An application is attempting to perform an |
132 | action that requires privileges. Authentication |
133 | as one of the users below is required to |
134 | perform this action. |
135 | |
136 | [[Face] Patrick Bateman (bateman) [V]] |
137 | |
138 | Password for bateman: [______________________] |
139 | |
140 | [V] Details: |
141 | Drive: ATA INTEL SSDSA2MH08 (045C) |
142 | Device: /dev/sda |
143 | Action: org.fd.devicekit.disks.drive-ata-smart-selftest |
144 | Vendor: The DeviceKit Project |
145 | |
146 | [Cancel] [Authenticate] |
147 +----------------------------------------------------------+
148 See pklocalauthority(8) on how to set up the local authority
150 implemention for systems without a root account.
151
153 A mechanism need to declare a set of “ACTIONS” in order to use
154 PolicyKit. Actions correspond to operations that clients can request
155 the mechanism to carry out and are defined in XML files that the
156 mechanism installs into the /usr/share/polkit-1/actions directory.
157 PolicyKit actions are namespaced and can only contain the characters
159 [a-z][0-9].- e.g. lower-case ASCII, digits, period and hyphen. Each XML
160 file can contain more than one action but all actions need to be in the
161 same namespace and the file needs to be named after the namespace and
162 have the extension .policy.
163 The XML file must have the following doctype declaration
165 <?xml version="1.0" encoding="UTF-8"?>
167 <!DOCTYPE policyconfig PUBLIC "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
168 "http://www.freedesktop.org/standards/PolicyKit/1.0/policyconfig.dtd">
169 The policyconfig element must be present exactly once. Elements that
171 can be used inside policyconfig includes:
172 vendor
174 The name of the project or vendor that is supplying the actions in
175 the XML document. Optional.
176 vendor_url
178 A URL to the project or vendor that is supplying the actions in the
179 XML document. Optional.
180 icon_name
182 An icon representing the project or vendor that is supplying the
183 actions in the XML document. The icon name must adhere to the
184 Freedesktop.org Icon Naming Specification[5]. Optional.
185 action
187 Declares an action. The action name is specified using the id
188 attribute and can only contain the characters [a-z][0-9].- e.g.
189 lower-case ASCII, digits, period and hyphen.
190 Elements that can be used inside action includes:
192 description
194 A human readable description of the action, e.g. “Install unsigned
195 software”.
196 message
198 A human readable message displayed to the user when asking for
199 credentials when authentication is needed, e.g. “Installing
200 unsigned software requires authentication”.
201 defaults
203 This element is used to specify implicit authorizations for
204 clients.
205 Elements that can be used inside defaults includes:
207 allow_any
209 Implicit authorizations that apply to any client. Optional.
210 allow_inactive
212 Implicit authorizations that apply to clients in inactive
213 sessions on local consoles. Optional.
214 allow_active
216 Implicit authorizations that apply to clients in active
217 sessions on local consoles. Optional.
218 Each of the allow_any, allow_inactive and allow_active elements can
220 contain the following values:
221 no
223 Not authorized.
224 yes
226 Authorized.
227 auth_self
229 Authentication by the owner of the session that the client
230 originates from is required.
231 auth_admin
233 Authentication by an administrative user is required.
234 auth_self_keep
236 Like auth_self but the authorization is kept for a brief
237 period.
238 auth_admin_keep
240 Like auth_admin but the authorization is kept for a brief
241 period.
242 annotate
244 Used for annotating an action with a key/value pair. The key is
245 specified using the the key attribute and the value is specified
246 using the value attribute. This element may appear zero or more
247 times. See pkexec(1) for an example of how this can be used.
248 vendor
250 Used for overriding the vendor on a per-action basis. Optional.
251 vendor_url
253 Used for overriding the vendor URL on a per-action basis. Optional.
254 icon_name
256 Used for overriding the icon name on a per-action basis. Optional.
257 For localization, description and message elements may occur multiple
259 times with different xml:lang attributes.
260 To list installed PolicyKit actions, use the pkaction(1) command.
262
264 Written by David Zeuthen davidz@redhat.com with a lot of help from many
265 others.
266
268 Please send bug reports to either the distribution or the polkit-devel
269 mailing list, see the link
270 http://lists.freedesktop.org/mailman/listinfo/polkit-devel on how to
271 subscribe.
272
274 pklocalauthority(8) polkitd(8) pkaction(1), pkcheck(1), pkexec(1),
275
277 1. /usr/share/gtk-doc/html/polkit-1/polkit-architecture.png
278 2. developer documentation
280 file:///usr/share/gtk-doc/html/polkit-1/index.html
281 3. /usr/share/gtk-doc/html/polkit-1/polkit-authentication-agent-
283 example.png
284 4. /usr/share/gtk-doc/html/polkit-1/polkit-authentication-agent-
286 example-wheel.png
287 5. Freedesktop.org Icon Naming Specification
289 http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
290polkit January 2009 POLKIT(8)