Commit f7954ab0 authored by David Zeuthen's avatar David Zeuthen

Add a "PolicyKit Overview" section to the docs

parent b0e8a912
......@@ -418,6 +418,7 @@ src/programs/Makefile
src/examples/Makefile
src/nullbackend/Makefile
docs/version.xml
docs/extensiondir.xml
docs/Makefile
docs/polkit/Makefile
docs/polkitbackend/Makefile
......
@libdir@/polkit-1/backends
......@@ -3,7 +3,7 @@
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "../version.xml">
]>
<refentry id="devkit-disks-daemon.8">
<refentry id="polkitd-1.8">
<refentryinfo>
<title>polkitd-1</title>
<date>May 2009</date>
......
......@@ -48,6 +48,8 @@ MKTMPL_OPTIONS=
# Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE)
content_files = \
overview.xml \
../extensiondir.xml \
../version.xml \
../../src/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml \
../../src/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthorityManager.xml \
......
<?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>
<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
<link linkend="PolicyKit-1.8">this page</link> for the system
architecture and big picture.
</para>
</chapter>
<chapter>
<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 speak
to the PolicyKit Authority.
</para>
<para>
Note that <emphasis>clients</emphasis> never use the PolicyKit
API directly – it is intended solely 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), the mechanism will
need to provide API for this.
</para>
<para>
As an example of code using the GObject API, see <xref linkend="cancel-example"/>.
</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>
</chapter>
<chapter>
<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>
......@@ -2,6 +2,7 @@
<!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">
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
......@@ -55,6 +56,8 @@
</legalnotice>
</bookinfo>
<xi:include href="overview.xml"/>
<reference id="ref-dbus-api">
<title>D-Bus API Reference</title>
<xi:include href="../../src/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml"/>
......
......@@ -33,7 +33,6 @@ cancel_LDADD = \
$(top_builddir)/src/polkit/libpolkit-gobject-1.la \
$(NULL)
# ----------------------------------------------------------------------------------------------------
bin_PROGRAMS += pk-example-frobnicate
......
......@@ -19,14 +19,17 @@
* Author: David Zeuthen <davidz@redhat.com>
*/
/* Simple example that shows how to check for an authorization including
* cancelling the check.
/* Simple example that shows how to check for an authorization
* including cancelling the check.
*
* Cancelling an authorization check is desirable in situations where the
* object/action to check for vanishes. One concrete example of this is
* a disks daemon in which the user needs to authenticate to mount a file
* system. If the disk is removed while the user is busy with the authentication
* dialog, the disks daemon should cancel the authorization check.
* Cancelling an authorization check is desirable in situations where
* the object/action to check for vanishes.
*
* One concrete example of this is a disks service in which the user
* needs to authenticate to modify a disk. If the disk is removed
* while the authentication dialog is shown, the disks service should
* cancel the authorization check. A side effect of this, is that the
* authentication dialog is removed.
*/
#include <polkit/polkit.h>
......@@ -63,7 +66,6 @@ check_authorization_cb (PolkitAuthority *authority,
}
g_print ("Authorization result: %s\n", result_str);
/* TODO: print details if authorized */
}
g_main_loop_quit (loop);
......@@ -80,30 +82,54 @@ do_cancel (GCancellable *cancellable)
int
main (int argc, char *argv[])
{
pid_t parent_pid;
const gchar *action_id;
GMainLoop *loop;
PolkitSubject *calling_process;
PolkitSubject *subject;
PolkitAuthority *authority;
GCancellable *cancellable;
g_type_init ();
if (argc != 2)
{
g_printerr ("usage: %s <action_id>\n", argv[0]);
return 1;
}
action_id = argv[1];
loop = g_main_loop_new (NULL, FALSE);
authority = polkit_authority_get ();
calling_process = polkit_unix_process_new (getppid ());
/* Typically mechanisms will use a PolkitSystemBusName since most
* clients communicate with the mechanism via D-Bus. However for
* this simple example we use the process id of the calling process.
*
* Note that if the parent was reaped we have to be careful not to
* check if init(1) is authorized (it always is).
*/
parent_pid = getppid ();
if (parent_pid == 1)
{
g_printerr ("Parent process was reaped by init(1)\n");
return 1;
}
subject = polkit_unix_process_new (parent_pid);
cancellable = g_cancellable_new ();
g_print ("Will cancel authorization check in 10 seconds\n");
/* Set up a 10 second timer to cancel the check */
g_timeout_add (10 * 1000,
(GSourceFunc) do_cancel,
cancellable);
polkit_authority_check_authorization (authority,
calling_process,
"org.freedesktop.policykit.grant",
NULL,
subject,
action_id,
NULL, /* PolkitDetails */
POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION,
cancellable,
(GAsyncReadyCallback) check_authorization_cb,
......@@ -112,7 +138,7 @@ main (int argc, char *argv[])
g_main_loop_run (loop);
g_object_unref (authority);
g_object_unref (calling_process);
g_object_unref (subject);
g_object_unref (cancellable);
g_main_loop_unref (loop);
......
......@@ -295,4 +295,3 @@ main (int argc, char *argv[])
return ret;
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment