From fdcc6b9eb0942e40a1a1fd0118648e26df0be2b5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miloslav=20Trma=C4=8D?= <mitr@redhat.com>
Date: Thu, 18 Apr 2013 21:14:08 +0200
Subject: [PATCH] More warnings about using auth_self*

Suggested by Colin Walters.

https://bugs.freedesktop.org/show_bug.cgi?id=57284
---
 docs/man/polkit.xml      |  8 ++++++--
 docs/polkit/overview.xml | 24 ++++++++++++++++++++++--
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/docs/man/polkit.xml b/docs/man/polkit.xml
index f8b4849..d30ee52 100644
--- a/docs/man/polkit.xml
+++ b/docs/man/polkit.xml
@@ -356,7 +356,9 @@ System Context         |                        |
               <term><literal>auth_self</literal></term>
               <listitem><para>Authentication by the owner of the
               session that the client originates from is
-              required.</para></listitem>
+              required.  Note that this is not restrictive enough for most
+	      uses on multi-user systems; <literal>auth_admin</literal>* is
+	      generally recommended.</para></listitem>
             </varlistentry>
             <varlistentry>
               <term><literal>auth_admin</literal></term>
@@ -367,7 +369,9 @@ System Context         |                        |
               <term><literal>auth_self_keep</literal></term>
               <listitem><para>Like <literal>auth_self</literal> but
               the authorization is kept for a brief
-              period (e.g. five minutes).</para></listitem>
+              period (e.g. five minutes).  The warning about
+	      <literal>auth_self</literal> above applies
+	      likewise.</para></listitem>
             </varlistentry>
             <varlistentry>
               <term><literal>auth_admin_keep</literal></term>
diff --git a/docs/polkit/overview.xml b/docs/polkit/overview.xml
index fb14e50..150a7bc 100644
--- a/docs/polkit/overview.xml
+++ b/docs/polkit/overview.xml
@@ -74,6 +74,24 @@
 
         <listitem>
           <para>
+            <emphasis role='bold'>DO</emphasis> consider the impact of the
+            chosen implicit authorizations on multi-user systems.  Generally,
+            ordinary users should be able to neither modify important system's
+            behavior for other users, nor view other users' private data.  If
+            your application needs an authorization framework at all, it is
+            fairly likely that the default configuration should deny
+            authorization in at least some cases.  Default to using
+            <literal>auth_admin</literal>* instead of
+            <literal>auth_self</literal>*.  (On single-user desktops, the
+            single user is typically configured as a polkit administrator, so
+            the two variants behave equally.  On multi-user systems,
+            non-administrator users will be restricted by the default
+            configuration.)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
             <emphasis role='bold'>DO</emphasis> pass polkit variables
             along with <link
             linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.CheckAuthorization">CheckAuthorization()</link>
@@ -261,8 +279,10 @@
         that can be used together with
         <ulink url="http://developer.gnome.org/gtk3/unstable/GtkLockButton.html"><type>GtkLockButton</type></ulink>.
         Note that for <type>GtkLockButton</type> to work well, the
-        polkit action backing it should use <literal>auth_admin_keep</literal> or
-        <literal>auth_self_keep</literal> for its implicit authorizations.
+        polkit action backing it should use <literal>auth_admin_keep</literal>
+	for its implicit authorizations (or more rarely
+	<literal>auth_self_keep</literal> for services which don't affect other
+	users).
         This is often used to implement an <ulink
         url="http://developer.gnome.org/hig-book/3.2/hig-book.html#windows-instant-apply">instant
         apply</ulink> paradigm whereby the user
-- 
1.8.1.4