File: overview.xml

package info (click to toggle)
policykit-1 0.105-15~deb8u2
  • links: PTS, VCS
  • area: main
  • in suites: jessie
  • size: 8,644 kB
  • ctags: 4,294
  • sloc: ansic: 18,560; sh: 11,430; xml: 3,384; makefile: 767
file content (128 lines) | stat: -rw-r--r-- 5,938 bytes parent folder | download | duplicates (4)
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
<?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.AuthenticationAgentResponse2">AuthenticationAgentResponse2()</link>
      method.  This method should be treated as an internal
      implementation detail, and callers should use the
      <link linkend="PolkitAgentSession">PolkitAgentSession</link> API to invoke
      it, which currently uses a setuid helper program.
    </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 polkit</title>
    <para>
      polkit exports a number of extension points to
      replace/customize behavior of the polkit daemon. Note that
      all extensions run with super user privileges in the same
      process as the polkit daemon.
    </para>
    <para>
      The polkit 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 polkit.
    </para>
    <para>
      The following extension points are currently defined by
      polkit:
    </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
        polkit sources for an example.
      </para>
    </formalpara>

  </chapter>
</part>