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
|
<?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">
<!ENTITY extensiondir SYSTEM "../extensiondir.xml">
]>
<part id="overview">
<title>polkit Overview</title>
<chapter id="polkit-intro">
<title>Introduction</title>
<para>
polkit provides an authorization API intended to be used by
privileged programs (<quote>MECHANISMS</quote>) offering service
to unprivileged programs (<quote>CLIENTS</quote>). See the
<link linkend="polkit.8">polkit</link> manual page for
the system architecture and big picture.
</para>
</chapter>
<chapter id="polkit-apps">
<title>Writing polkit applications</title>
<para>
polkit applications are privileged mechanisms using the
polkit authority as a decider component. To do this, a
<emphasis>mechanism</emphasis> use either
the <link linkend="ref-api">GObject API</link>,
the <link linkend="ref-dbus-api">D-Bus API</link> or
the <link linkend="pkcheck.1">pkcheck</link> command to
communicate with the polkit Authority.
</para>
<para>
Note that <emphasis>clients</emphasis> normally doesn't use the
polkit API directly – it is intended for privileged
<emphasis>mechanisms</emphasis>. If a client needs to disable,
modify or remove UI elements to e.g. convey to the user that a
certain action cannot be carried out (because e.g. the user is
not authorized) or authentication is needed (by e.g. displaying
a padlock icon in the UI), it is usually better to have the
mechanism provide an API for this.
</para>
<para>
If a polkit application wants to handle the case where no
authentication agent exists (for example if the app is launched
via a
<citerefentry><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>
login), it is trivial for the application to use the <link
linkend="PolkitAgentTextListener">PolkitAgentTextListener</link>
class to spawn its own authentication agent as
needed. Alternatively, the <xref linkend="pkttyagent.1"/>
helper can be used to do this.
</para>
<para>
As an example of code using the GObject API, see <xref linkend="cancel-example"/>.
For an example using the D-Bus API, see <xref linkend="polkit-raw-dbus-py"/>.
</para>
<example id="cancel-example"><title>Querying the Authority</title>
<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../src/examples/cancel.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
</example>
<example id="polkit-raw-dbus-py"><title>Accessing the Authority via D-Bus</title>
<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../src/examples/polkit-raw-dbus.py"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
</example>
</chapter>
<chapter id="polkit-agents">
<title>Writing polkit Authentication Agents</title>
<para>
Authentication agents are provided by desktop environments. When
an user session starts, the agent registers with the polkit
Authority using
the <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">RegisterAuthenticationAgent()</link>
method. When services are needed, the authority will invoke
methods on
the <link linkend="eggdbus-interface-org.freedesktop.PolicyKit1.AuthenticationAgent">org.freedesktop.PolicyKit1.AuthenticationAgent</link>
D-Bus interface. Once the user is authenticated, (a privileged
part of) the agent invokes
the <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse">AuthenticationAgentResponse()</link>
method. Note that the polkit Authority itself does not care
how the agent authenticates the user.
</para>
<para>
The <link linkend="ref-authentication-agent-api">libpolkit-agent-1</link>
library provides helpers to make it easy to build authentication
agents that use the native authentication system
e.g. pam<literal>(8)</literal>.
</para>
<para>
If the environment variable <literal>POLKIT_DEBUG</literal> is
set, the libpolkit-agent-1 library prints out diagnostic
information on standard output.
</para>
</chapter>
</part>
|
