More warnings about using auth_self*

Suggested by Colin Walters.

https://bugs.freedesktop.org/show_bug.cgi?id=57284

diff --git a/docs/man/polkit.xml b/docs/man/polkit.xml
index f8b4849c1b603f25987159fd95dc83f37309dd0b..d30ee52a502512da73606c0755cdd9be282b918e 100644 (file)
--- 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 fb14e50eeb13e6dbe00d5251f58ec42a389e62a7..150a7bcbc26af06cf94c3a7e42fa2025fd5d7e21 100644 (file)
--- a/docs/polkit/overview.xml
+++ b/docs/polkit/overview.xml
@@ -72,6 +72,24 @@
           </para>
         </listitem>
 
+        <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
@@ -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