PolicyKit: Branch 'master'

[David Zeuthen]

 docs/man/polkit.xml |   20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

New commits:
commit d81f4d16ab96c4084bf20c7174ac6fb16f69c402
Author: David Zeuthen <zeuthen at gmail.com>
Date:   Thu Jun 7 10:35:07 2012 -0400

    Mention the implications of returning *_keep in an authorization rule
    
    Pointed out by Dan Williams <dcbw at redhat.com> on IRC.
    
    Signed-off-by: David Zeuthen <zeuthen at gmail.com>

diff --git a/docs/man/polkit.xml b/docs/man/polkit.xml
index a055707..d48b1a0 100644
--- a/docs/man/polkit.xml
+++ b/docs/man/polkit.xml
@@ -367,11 +367,11 @@ 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.</para></listitem>
+              period (e.g. five minutes).</para></listitem>
             </varlistentry>
             <varlistentry>
               <term><literal>auth_admin_keep</literal></term>
-              <listitem><para>Like <literal>auth_admin</literal> but the authorization is kept for a brief period.</para></listitem>
+              <listitem><para>Like <literal>auth_admin</literal> but the authorization is kept for a brief period  (e.g. five minutes).</para></listitem>
             </varlistentry>
           </variablelist>
         </listitem>
@@ -564,6 +564,22 @@ System Context         |                        |
       </para>
 
       <para>
+        Keep in mind that if <literal>"auth_self_keep"</literal> or
+        <literal>"auth_admin_keep"</literal> is returned,
+        authorization checks for the same action identifier and
+        subject will succeed (that is, return "yes") for the next
+        brief period (e.g. five minutes) <emphasis>even</emphasis> if
+        the variables passed along with the check are
+        different. Therefore, if the result of an authorization rule
+        depend on such variables, it should not use the
+        <literal>"*_keep"</literal> variants (if similar functionality
+        is required, the authorization rule can easily implement
+        temporary authorizations using the
+        <ulink url="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date"><type>Date</type></ulink>
+        type for timestamps).
+      </para>
+
+      <para>
         The <function>addAdminRule()</function> method is used for
         adding a function may be called whenever administrator
         authentication is required. The function is used to specify what