blob: 31f856f1e6ad822128f430f3b1c1fbe100b40541 (
plain)
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
|
<?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>PolicyKit Overview</title>
<chapter id="polkit-intro">
<title>Introduction</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>). 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 PolicyKit applications</title>
<para>
PolicyKit applications are privileged mechanisms using the
PolicyKit 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 PolicyKit Authority.
</para>
<para>
Note that <emphasis>clients</emphasis> normally doesn't use the
PolicyKit 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 PolicyKit 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. See the
<link linkend="pkcheck.1">pkcheck</link> or <link
linkend="pkexec.1">pkexec</link> program sources for an example
of how 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 PolicyKit Authentication Agents</title>
<para>
Authentication agents are provided by desktop environments. When
an user session starts, the agent registers with the PolicyKit
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 PolicyKit 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>
<chapter id="polkit-extending">
<title>Extending PolicyKit</title>
<para>
PolicyKit exports a number of extension points to
replace/customize behavior of the PolicyKit daemon. Note that
all extensions run with super user privileges in the same
process as the PolicyKit daemon.
</para>
<para>
The PolicyKit daemons loads extensions
from the <filename>&extensiondir;</filename> directory. See
the <link linkend="gio-Extension-Points">GIO Extension Point
documentation</link> for more information about the extension
system used by PolicyKit.
</para>
<para>
The following extension points are currently defined by
PolicyKit:
</para>
<formalpara>
<title>POLKIT_BACKEND_AUTHORITY_EXTENSION_POINT_NAME</title>
<para>
Allows replacing the Authority – the entity responsible for
making authorization decisions. Implementations of this
extension point must be derived from the
PolkitBackendAuthority class. See
the <filename>src/nullbackend/</filename> directory in the
PolicyKit sources for an example.
</para>
</formalpara>
<formalpara>
<title>POLKIT_BACKEND_ACTION_LOOKUP_EXTENSION_POINT_NAME</title>
<para>
Allows a mechanism to customize the contents of authentication
dialogs. Implementations of this extension point must
implement the #PolkitBackendActionLookup interface.
</para>
</formalpara>
</chapter>
</part>
|
