PolicyKit: Branch 'master'
David Zeuthen
david at kemper.freedesktop.org
Mon Jun 8 09:38:33 PDT 2009
configure.ac | 1
docs/extensiondir.xml.in | 1
docs/man/polkitd-1.xml | 2
docs/polkit/Makefile.am | 2
docs/polkit/overview.xml | 91 ++++++++++++++++++++++++++++++++++++++++++
docs/polkit/polkit-1-docs.xml | 3 +
src/examples/Makefile.am | 1
src/examples/cancel.c | 54 ++++++++++++++++++------
src/programs/pkcheck.c | 1
9 files changed, 139 insertions(+), 17 deletions(-)
New commits:
commit f7954ab0f537df7ead3d4901beab714fbfa55e62
Author: David Zeuthen <davidz at redhat.com>
Date: Mon Jun 8 12:35:56 2009 -0400
Add a "PolicyKit Overview" section to the docs
diff --git a/configure.ac b/configure.ac
index 03f5291..47976ee 100644
--- a/configure.ac
+++ b/configure.ac
@@ -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
diff --git a/docs/extensiondir.xml.in b/docs/extensiondir.xml.in
new file mode 100644
index 0000000..c12c3d6
--- /dev/null
+++ b/docs/extensiondir.xml.in
@@ -0,0 +1 @@
+ at libdir@/polkit-1/backends
diff --git a/docs/man/polkitd-1.xml b/docs/man/polkitd-1.xml
index 5a6fdee..3080f74 100644
--- a/docs/man/polkitd-1.xml
+++ b/docs/man/polkitd-1.xml
@@ -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>
diff --git a/docs/polkit/Makefile.am b/docs/polkit/Makefile.am
index 4e182af..ebfb06f 100644
--- a/docs/polkit/Makefile.am
+++ b/docs/polkit/Makefile.am
@@ -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 \
diff --git a/docs/polkit/overview.xml b/docs/polkit/overview.xml
new file mode 100644
index 0000000..f3ebca9
--- /dev/null
+++ b/docs/polkit/overview.xml
@@ -0,0 +1,91 @@
+<?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>
diff --git a/docs/polkit/polkit-1-docs.xml b/docs/polkit/polkit-1-docs.xml
index 7283c98..fb2082b 100644
--- a/docs/polkit/polkit-1-docs.xml
+++ b/docs/polkit/polkit-1-docs.xml
@@ -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"/>
diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am
index b30155b..88cea72 100644
--- a/src/examples/Makefile.am
+++ b/src/examples/Makefile.am
@@ -33,7 +33,6 @@ cancel_LDADD = \
$(top_builddir)/src/polkit/libpolkit-gobject-1.la \
$(NULL)
-
# ----------------------------------------------------------------------------------------------------
bin_PROGRAMS += pk-example-frobnicate
diff --git a/src/examples/cancel.c b/src/examples/cancel.c
index 351f974..2c6224c 100644
--- a/src/examples/cancel.c
+++ b/src/examples/cancel.c
@@ -19,14 +19,17 @@
* Author: David Zeuthen <davidz at 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);
diff --git a/src/programs/pkcheck.c b/src/programs/pkcheck.c
index ea17668..7850cf5 100644
--- a/src/programs/pkcheck.c
+++ b/src/programs/pkcheck.c
@@ -295,4 +295,3 @@ main (int argc, char *argv[])
return ret;
}
-
More information about the hal-commit
mailing list