From 6bbd5189e967e8ddc36100bf22cd12bcb152ab5f Mon Sep 17 00:00:00 2001
From: David Zeuthen <davidz@redhat.com>
Date: Tue, 20 Sep 2011 14:13:12 -0400
Subject: Add support for the org.freedesktop.policykit.imply annotation

For example, GNOME control center can now defined e.g.

  <action id="org.zee.example.meta">
    <description>Meta Action</description>
    <message>Example of a meta action, blabla</message>
    <defaults>
      <allow_any>no</allow_any>
      <allow_inactive>no</allow_inactive>
      <allow_active>auth_admin_keep</allow_active>
    </defaults>
    <annotate key="org.freedesktop.policykit.imply">org.freedesktop.udisks2.ata-smart-selftest org.freedesktop.udisks2.encrypted-lock-others org.freedesktop.udisks2.filesystem-unmount-others</annotate>
  </action>

and set up a single GtkLockButton for a PolkitPermission for action id
"org.zee.example.meta".

When unlocked the given subject will now be authorized for the actions
mentioned in the annotation.

Example test program:

int
main (int argc, char *argv[])
{
  PolkitSubject *subject;
  GtkWidget *window;
  GtkWidget *table;
  GMainLoop *loop;
  guint n;

  gtk_init (&argc, &argv);

  subject = polkit_unix_process_new (getpid ());

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);

  table = gtk_table_new (1, 2, FALSE);
  for (n = 1; n < argc; n++)
    {
      const gchar *action_id = argv[n];
      GPermission *permission;
      GtkWidget *label;
      GtkWidget *lock_button;
      GError *error = NULL;

      label = gtk_label_new (action_id);

      permission = polkit_permission_new_sync (action_id, subject, NULL, &error);
      if (permission == NULL)
        {
          g_error ("Error constructing permission for action_id %s: %s (%s, %d)",
                   action_id, error->message, g_quark_to_string (error->domain), error->code);
          goto out;
        }
      lock_button = gtk_lock_button_new (permission);
      g_object_unref (permission);

      gtk_table_attach (GTK_TABLE (table), label,       0, 1, n - 1, n, GTK_FILL, GTK_FILL, 0, 0);
      gtk_table_attach (GTK_TABLE (table), lock_button, 1, 2, n - 1, n, GTK_FILL, GTK_FILL, 0, 0);
    }
  gtk_container_add (GTK_CONTAINER (window), table);

  gtk_widget_show_all (window);

  loop = g_main_loop_new (NULL, FALSE);
  g_main_loop_run (loop);

 out:
  ;
}

Compile with:

 gcc -o showpolkit showpolkit.c `pkg-config --cflags --libs polkit-gobject-1 gtk+-3.0` -g -O0

Run with:

 ./showpolkit org.freedesktop.udisks2.ata-smart-selftest org.freedesktop.udisks2.encrypted-lock-others org.freedesktop.udisks2.filesystem-unmount-others org.zee.example.meta

Signed-off-by: David Zeuthen <davidz@redhat.com>
---
 docs/man/polkit.xml | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/man/polkit.xml b/docs/man/polkit.xml
index bcb276b..bfa5ccd 100644
--- a/docs/man/polkit.xml
+++ b/docs/man/polkit.xml
@@ -369,8 +369,7 @@ System Context         |                        |
         the <literal>key</literal> attribute and the value is
         specified using the <literal>value</literal> attribute. This
         element may appear zero or more times. See
-            <citerefentry><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-            for an example of how this can be used. </para></listitem>
+            below for known annotations. </para></listitem>
       </varlistentry>
       <varlistentry>
         <term><emphasis>vendor</emphasis></term>
@@ -398,6 +397,28 @@ System Context         |                        |
       <citerefentry><refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum></citerefentry>
       command.
     </para>
+
+    <refsect2><title>Known annotations</title>
+    <para>
+      The <literal>org.freedesktop.policykit.exec.path</literal>
+      annotation is used by the <command>pkexec</command> program
+      shipped with PolicyKit - see the
+      <citerefentry><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      man page for details.
+    </para>
+    <para>
+      The <literal>org.freedesktop.policykit.imply</literal>
+      annotation (its value is a string containing a space separated
+      list of action identifiers) can be used to define <emphasis>meta
+      actions</emphasis>. The way it works is that if a subject is
+      authorized for an action with this annotation, then it is also
+      authorized for any action specified by the annotation. A typical
+      use of this annotation is when defining an UI shell with a
+      single lock button that should unlock multiple actions from
+      distinct mechanisms.
+    </para>
+    </refsect2>
+
   </refsect1>
 
   <refsect1 id="polkit-author"><title>AUTHOR</title>
-- 
cgit v1.2.1