Bug 30653 – No way to detect cancellation in pkexec

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

Signed-off-by: David Zeuthen <davidz@redhat.com>

4 files changed, 24 insertions, 4 deletions

diff --git a/docs/man/pkexec.xml b/docs/man/pkexec.xml
index 6f5dc9c..97ab315 100644
--- a/docs/man/pkexec.xml
+++ b/docs/man/pkexec.xml
@@ -61,7 +61,10 @@
       of <replaceable>PROGRAM</replaceable>. If the calling process is
       not authorized or an authorization could not be obtained through
       authentication or an error occured, <command>pkexec</command>
-      exits with a return value of 127.
+      exits with a return value of 127. If the authorization could not
+      be obtained because the user dismissed the authentication
+      dialog, <command>pkexec</command> exits with a return value of
+      126.
     </para>
   </refsect1>
 
diff --git a/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml b/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml
index 663169e..b01fceb 100644
--- a/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml
+++ b/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml
@@ -40,8 +40,24 @@ BeginAuthentication (IN  String               action_id,
                      IN  Array&lt;<link linkend="eggdbus-struct-Identity">Identity</link>&gt;      identities)
     </programlisting>
     <para>
-<para>Called by the PolicyKit daemon when the authentication agent needs the user to authenticate as one of the identities in <parameter>identities</parameter> for the action with the identifier <parameter>action_id</parameter>.</para><para>Upon succesful authentication, the authentication agent must invoke the <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse">AuthenticationAgentResponse()</link> method on the <link linkend="eggdbus-interface-org.freedesktop.PolicyKit1.Authority">org.freedesktop.PolicyKit1.Authority</link> interface of the PolicyKit daemon before returning.</para><para>If the user dismisses the authentication dialog, the authentication agent should return an error.</para>
+      <para>
+        Called by the PolicyKit daemon when the authentication agent
+        needs the user to authenticate as one of the identities in
+        <parameter>identities</parameter> for the action with the
+        identifier <parameter>action_id</parameter>.</para><para>Upon
+        succesful authentication, the authentication agent must invoke
+        the <link
+        linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse">AuthenticationAgentResponse()</link>
+        method on the <link
+        linkend="eggdbus-interface-org.freedesktop.PolicyKit1.Authority">org.freedesktop.PolicyKit1.Authority</link>
+        interface of the PolicyKit daemon before returning.
+      </para>
+      <para>
+        The authentication agent should not return until after authentication is complete.
+        If the user dismisses the authentication dialog, the authentication agent should return the <link linkend="eggdbus-constant-Error.org.freedesktop.PolicyKit1.Error.Cancelled">org.freedesktop.PolicyKit1.Error.Cancelled</link> error.
+      </para>
     </para>
+
 <variablelist role="params">
   <varlistentry>
     <term><literal>IN  String <parameter>action_id</parameter></literal>:</term>
@@ -71,7 +87,7 @@ The themed icon describing the action or the empty string if no icon is set.
     <term><literal>IN  Dict&lt;String,String&gt; <parameter>details</parameter></literal>:</term>
     <listitem>
       <para>
-Details about the authentication request. This is a dictionary of key/value pairs where both key and value are strings. These strings are translated into the locale passed when registering the authentication agent using <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">RegisterAuthenticationAgent().</link>.
+Details about the authentication request. This is a dictionary of key/value pairs where both key and value are strings. These strings are translated into the locale passed when registering the authentication agent using <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">RegisterAuthenticationAgent()</link>.
 Keys starting with <literal>polkit.</literal> are reserved for internal use and should never be displayed in the UI.
 Known key/value-pairs include <literal>polkit.caller-pid</literal> (the process id of the mechanism making the authorization check) and <literal>polkit.subject-pid</literal> (the process id of the subject the check is for).
       </para>
diff --git a/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml b/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml
index cb9da6b..93f8cfa 100644
--- a/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml
+++ b/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml
@@ -461,7 +461,7 @@ TRUE if the given <link linkend="eggdbus-struct-Subject">Subject</link> could be
     <term><literal>Dict&lt;String,String&gt; <structfield>details</structfield></literal></term>
     <listitem>
       <para>
-Details for the result or empty if not authorized. Known key/value-pairs include <literal>polkit.temporary_authorization_id</literal> (if the authorization is temporary, this is set to the opaque temporary authorization id), <literal>polkit.retains_authorization_after_challenge</literal> (Set to a non-empty string if the authorization will be retained after authentication (if is_challenge is TRUE)).
+Details for the result or empty if not authorized. Known key/value-pairs include <literal>polkit.temporary_authorization_id</literal> (if the authorization is temporary, this is set to the opaque temporary authorization id), <literal>polkit.retains_authorization_after_challenge</literal> (Set to a non-empty string if the authorization will be retained after authentication (if is_challenge is TRUE)), <literal>polkit.dismissed</literal> (Set to a non-empty string if the authentication dialog was dismissed by the user).
       </para>
     </listitem>
   </varlistentry>
diff --git a/docs/polkit/polkit-1-sections.txt b/docs/polkit/polkit-1-sections.txt
index 78248dc..12141e3 100644
--- a/docs/polkit/polkit-1-sections.txt
+++ b/docs/polkit/polkit-1-sections.txt
@@ -71,6 +71,7 @@ polkit_authorization_result_get_is_authorized
 polkit_authorization_result_get_is_challenge
 polkit_authorization_result_get_retains_authorization
 polkit_authorization_result_get_temporary_authorization_id
+polkit_authorization_result_get_dismissed
 polkit_authorization_result_get_details
 <SUBSECTION Standard>
 PolkitAuthorizationResultClass