Debian Codegraph @

docs/polkit/overview.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 <!ENTITY extensiondir SYSTEM "../extensiondir.xml">
6 ]>
7 <part id="overview">
8 <title>polkit Overview</title>
9 <chapter id="polkit-intro">
10 <title>Introduction</title>
11 <para>
12 polkit provides an authorization API intended to be used by
13 privileged programs (<quote>MECHANISMS</quote>) offering service
14 to unprivileged programs (<quote>CLIENTS</quote>). See the
15 <link linkend="polkit.8">polkit</link> manual page for
16 the system architecture and big picture.
17 </para>
18 </chapter>
19
20 <chapter id="polkit-apps">
21 <title>Writing polkit applications</title>
22 <para>
23 polkit applications are applications using the polkit authority
24 as a decider component. They do this by installing a <filename
25 class='extension'>.policy</filename> file into the <filename
26 class='directory'>/usr/share/polkit-1/actions</filename>
27 directory and communicating with the polkit authority at runtime
28 (either via the <link linkend="ref-dbus-api">D-Bus API</link> or
29 indirectly through the <link
30 linkend="ref-api">libpolkit-gobject-1</link> library or the
31 <link linkend="pkcheck.1">pkcheck</link> command).
32 </para>
33
34 <simplesect id="polkit-apps-best-practices">
35 <title>Best practices</title>
36 <itemizedlist mark='opencircle' spacing='compact'>
37
38 <listitem>
39 <para>
40 <emphasis role='bold'>DO</emphasis> use polkit if you are
41 writing a privileged mechanism (that is, running as
42 <emphasis>root</emphasis> or otherwise has special
43 permissions) that is intended to be used by unprivileged
44 programs.
45 </para>
46 </listitem>
47
48 <listitem>
49 <para>
50 <emphasis role='bold'>DO</emphasis> carefully consider
51 what actions to define. In many cases there isn't a 1:1
52 mapping between operations and polkit actions. Often a
53 polkit action has more to do with the object the operation
54 is acting on than the operation itself. It is important to
55 strike the right balance between too fine-grained and too
56 coarse-grained.
57 </para>
58 </listitem>
59
60 <listitem>
61 <para>
62 <emphasis role='bold'>DO</emphasis> try to pick actions
63 and implicit authorizations so applications using your
64 mechanism will work out-of-the box for users logged in at
65 the console. Not interrupting console users with
66 authentication dialogs should be considered a
67 priority. For example, it is not wise to require console
68 users to authenticate for such mundane tasks as adding a
69 printer queue (if the administrator really wants the OS to
70 act this way, he can always deploy suitable authorization
71 rules).
72 </para>
73 </listitem>
74
75 <listitem>
76 <para>
77 <emphasis role='bold'>DO</emphasis> consider the impact of the
78 chosen implicit authorizations on multi-user systems. Generally,
79 ordinary users should be able to neither modify important system's
80 behavior for other users, nor view other users' private data. If
81 your application needs an authorization framework at all, it is
82 fairly likely that the default configuration should deny
83 authorization in at least some cases. Default to using
84 <literal>auth_admin</literal>* instead of
85 <literal>auth_self</literal>*. (On single-user desktops, the
86 single user is typically configured as a polkit administrator, so
87 the two variants behave equally. On multi-user systems,
88 non-administrator users will be restricted by the default
89 configuration.)
90 </para>
91 </listitem>
92
93 <listitem>
94 <para>
95 <emphasis role='bold'>DO</emphasis> pass polkit variables
96 along with <link
97 linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.CheckAuthorization">CheckAuthorization()</link>
98 requests so it's possible to write <emphasis>authorization
99 rules</emphasis> matching on these. Also document these
100 variables in your documentation (for example, see the
101 <ulink
102 url="http://udisks.freedesktop.org/docs/latest/udisks-polkit-actions.html">udisks2
103 actions and variables</ulink>).
104 </para>
105 </listitem>
106
107 <listitem>
108 <para>
109 <emphasis role='bold'>DO</emphasis> pass a customized
110 authentication message (using the
111 <literal>polkit.message</literal> and
112 <literal>polkit.gettext_domain</literal> variables) that
113 include more detailed information about the request than
114 whatever is declared in the <filename
115 class='extension'>.policy</filename> file's
116 <literal>message</literal> element. For example, it's
117 better to show <quote>Authentication is needed to format
118 INTEL SSDSA2MH080G1GC (/dev/sda)</quote> than just
119 <quote>Authentication is needed to format the
120 device</quote>.
121 </para>
122 </listitem>
123
124 <listitem>
125 <para>
126 <emphasis role='bold'>DO</emphasis> make sure
127 your application works even when the
128 <literal>org.freedesktop.PolicyKit1</literal>
129 D-Bus service is not available (this can
130 happen if
131 <link linkend="polkitd.8"><citerefentry><refentrytitle>polkitd</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>
132 is not installed or if the <emphasis>polkit.service</emphasis> systemd unit/service has been
133 <ulink url="http://0pointer.de/blog/projects/three-levels-of-off.html">masked</ulink>). If you are using the
134 <link linkend="ref-api">libpolkit-gobject-1</link> library this
135 means handling
136 <link linkend="polkit-authority-get-sync">polkit_authority_get_sync()</link>
137 or
138 <link linkend="polkit-authority-get-finish">polkit_authority_get_finish()</link>
139 returning <constant>NULL</constant> or
140 <link linkend="polkit-authority-check-authorization">polkit_authority_check_authorization()</link> /
141 <link linkend="polkit-authority-check-authorization-sync">polkit_authority_check_authorization_sync()</link>
142 failing with an error not in the
143 <link linkend="POLKIT-ERROR:CAPS">POLKIT_ERROR</link>
144 domain.
145 An appropriate way of dealing with the polkit authority
146 not being available, could be to allow only uid 0 to
147 perform operations, forbid all operations or something
148 else.
149 </para>
150 </listitem>
151
152 <listitem>
153 <para>
154 <emphasis role='bold'>DON'T</emphasis> use polkit if your
155 program isn't intended to be used by unprivileged
156 programs. For example, if you are writing developer tools
157 or low-level core OS command-line tools it's fine to just
158 require the user to be root. Users can always run your
159 tool through e.g.
160 <citerefentry><refentrytitle>sudo</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
161 <link
162 linkend="pkexec.1"><citerefentry><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>
163 or write a simple polkit-using mechanism that allows
164 access to a (safe) subset of your tool.
165 </para>
166 </listitem>
167
168 <listitem>
169 <para>
170 <emphasis role='bold'>DON'T</emphasis> use polkit unless
171 you actually have to. In other words, not every single
172 privileged program providing service to unprivileged
173 programs has to use polkit. For example, if you have a
174 small well-written <ulink
175 url="http://en.wikipedia.org/wiki/Setuid">setuid</ulink>
176 helper to help deal with some implementation-detail of the
177 OS (such as elevating the priority of the sound server
178 process to real-time for console users) it's not really
179 helpful to define a polkit action for this since,
180 realistically, no-one is going to choose to
181 <emphasis>not</emphasis> grant the privilege. Remember, a
182 secure program is often one with little amount of code and
183 few dependencies.
184 </para>
185 </listitem>
186
187 <listitem>
188 <para>
189 <emphasis role='bold'>DON'T</emphasis> call <link
190 linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.CheckAuthorization">CheckAuthorization()</link>
191 for all your actions every time the authority emits the
192 <link
193 linkend="eggdbus-signal-org.freedesktop.PolicyKit1.Authority::Changed">Changed</link>
194 signal. Not only is this a waste of resources, the result
195 may also be inaccurate as authorization rules can return
196 whatever they want, whenever they want.
197 </para>
198 </listitem>
199
200 <listitem>
201 <para>
202 <emphasis role='bold'>DON'T</emphasis> block the main
203 thread in your mechanism (e.g. the one used to service IPC
204 requests from unprivileged programs) while waiting for the
205 authority to reply - calls to <link
206 linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.CheckAuthorization">CheckAuthorization()</link>
207 may take a very long time (seconds, even minutes) to
208 complete as user interaction may be involved. Instead,
209 use either the <link
210 linkend="polkit-authority-check-authorization">asynchronous
211 API</link> or a dedicated thread with the <link
212 linkend="polkit-authority-check-authorization-sync">synchronous
213 API</link>.
214 </para>
215 </listitem>
216
217 <listitem>
218 <para>
219 <emphasis role='bold'>DON'T</emphasis> include any
220 authorization rules with your application as this is only
221 intended for administrators and special-purpose operating
222 systems / environments. See <xref linkend="polkit-rules"/>
223 for more information.
224 </para>
225 </listitem>
226
227 </itemizedlist>
228 </simplesect>
229
230 <simplesect id="polkit-apps-unprivileged">
231 <title>Usage in unprivileged programs</title>
232
233 <para>
234 An unprivileged program normally does not use polkit directly
235 - it simply calls into a privileged mechanism and the
236 mechanism either renders service (or refuses the request)
237 after checking with polkit (which may include presenting an
238 authentication dialog). In this setup, the unprivileged
239 program is oblivious to the fact that polkit is being used -
240 it simply just waits for the privileged mechanism to carry out
241 the request (which, if authentication dialogs are involved may
242 take many seconds). This is a good thing because not worrying
243 about implementation details like polkit, helps simplify the
244 unprivileged program.
245 </para>
246 <para>
247 Occasionally unprivileged programs need to disable, modify or
248 remove UI elements to convey to the user that a certain action
249 cannot be carried out (because e.g. the user is not
250 authorized) or authentication is needed (by e.g. displaying a
251 padlock icon in the UI). In this case, the best approach is
252 usually to have the unprivileged program get this information
253 from the privileged mechanism instead of polkit. This is
254 especially true because often there is no reliable way that
255 the unprivileged program can know what polkit action is going
256 to be used. In general, there is no guarantee that operations
257 (such as D-Bus methods) map 1:1: to polkit action - for
258 example, a disk manager service's <literal>Format()</literal>
259 method may check for the action
260 <literal>net.company.diskmanager.format-removable</literal> if
261 the disk is removable and
262 <literal>net.company.diskmanager.format-fixed</literal>
263 otherwise.
264 </para>
265 <para>
266 However, in certain cases, for example when using the
267 <emphasis>org.freedesktop.policykit.imply</emphasis> annotation
268 (see the
269 <link linkend="polkit.8"><citerefentry><refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum></citerefentry></link> man page),
270 it is meaningful for an unprivileged program to query the
271 polkit authority (to e.g. update UI elements) and it is
272 in fact allowed to do so as long as the unprivileged program doesn't pass any variables along with the
273 <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.CheckAuthorization">CheckAuthorization()</link>
274 call (otherwise it would be easy to spoof authentication dialogs and bypass authorization rules).
275 In fact, since this use-case is so common,
276 <link linkend="ref-api">libpolkit-gobject-1</link> provides the
277 <link linkend="PolkitPermission"><type>PolkitPermission</type></link> type (which is derived from
278 <ulink url="http://developer.gnome.org/gio/unstable/GPermission.html"><type>GPermission</type></ulink>)
279 that can be used together with
280 <ulink url="http://developer.gnome.org/gtk3/unstable/GtkLockButton.html"><type>GtkLockButton</type></ulink>.
281 Note that for <type>GtkLockButton</type> to work well, the
282 polkit action backing it should use <literal>auth_admin_keep</literal>
283 for its implicit authorizations (or more rarely
284 <literal>auth_self_keep</literal> for services which don't affect other
285 users).
286 This is often used to implement an <ulink
287 url="http://developer.gnome.org/hig-book/3.2/hig-book.html#windows-instant-apply">instant
288 apply</ulink> paradigm whereby the user
289 <emphasis>unlocks</emphasis> (by authenticating) e.g. a
290 preference pane window and is then free to change settings
291 until the authorization expires or is revoked.
292 </para>
293 </simplesect>
294
295 <simplesect id="polkit-apps-no-auth-agent">
296 <title>No authentication agent</title>
297 <para>
298 If a polkit application wants to handle the case where no
299 authentication agent exists (for example if the app is launched
300 via a
301 <citerefentry><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>
302 login), the application can use the <link
303 linkend="PolkitAgentTextListener">PolkitAgentTextListener</link>
304 type to spawn its own authentication agent as
305 needed. Alternatively, the <xref linkend="pkttyagent.1"/>
306 helper can be used to do this.
307 </para>
308 </simplesect>
309
310 </chapter>
311
312 <chapter id="polkit-agents">
313 <title>Writing polkit Authentication Agents</title>
314 <para>
315 Authentication agents are provided by desktop environments. When
316 an user session starts, the agent registers with the polkit
317 Authority using the <link
318 linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">RegisterAuthenticationAgent()</link>
319 method. When services are needed, the authority will invoke
320 methods on the <link
321 linkend="eggdbus-interface-org.freedesktop.PolicyKit1.AuthenticationAgent">org.freedesktop.PolicyKit1.AuthenticationAgent</link>
322 D-Bus interface. Once the user is authenticated, (a privileged
323 part of) the agent invokes the <link
324 linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse2">AuthenticationAgentResponse2()</link>
325 method. This method should be treated as an internal
326 implementation detail, and callers should use the
327 <link linkend="PolkitAgentSession">PolkitAgentSession</link> API to invoke
328 it, which currently uses a setuid helper program.
329 </para>
330 <para>
331 The <link linkend="ref-authentication-agent-api">libpolkit-agent-1</link>
332 library provides helpers to make it easy to build authentication
333 agents that use the native authentication system
334 e.g. pam<literal>(8)</literal>.
335 </para>
336 <para>
337 If the environment variable <literal>POLKIT_DEBUG</literal> is
338 set, the libpolkit-agent-1 library prints out diagnostic
339 information on standard output.
340 </para>
341 </chapter>
342
343 </part>