docs: Update for changes to uid binding/AuthenticationAgentResponse2

 - Refer to PolkitAgentSession in general instead of to _response only
 - Revert to the original description of authentication cancellation, the
   agent really needs to return an error to the caller (in addition to dealing
   with the session if any).
 - Explicitly document the UID assumption; in the process fixing bug #69980.
 - Keep documenting that we need a sufficiently privileged caller.
 - Refer to the ...Response2 API in more places.
 - Also update docbook documentation.
 - Drop a paragraph suggesting non-PolkitAgentSession implementations are
   expected and commonplace.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=90837
Reviewed-by: Colin Walters <walters@redhat.com>

3 files changed, 17 insertions, 10 deletions

diff --git a/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml b/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml
index ec59626..ab27b2f 100644
--- a/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml
+++ b/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml
@@ -47,10 +47,13 @@ BeginAuthentication (IN  String               action_id,
         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>
+        linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse2">AuthenticationAgentResponse2()</link>
         method on the <link
         linkend="eggdbus-interface-org.freedesktop.PolicyKit1.Authority">org.freedesktop.PolicyKit1.Authority</link>
-        interface of the PolicyKit daemon before returning.
+        interface of the PolicyKit daemon before returning. This is normally
+        achieved via the <link linkend="PolkitAgentSession">PolkitAgentSession</link>
+        API, which invokes a private setuid helper process to verify the
+        authentication.
       </para>
       <para>
         The authentication agent should not return until after authentication is complete.
diff --git a/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml b/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml
index e66bf53..f2eed63 100644
--- a/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml
+++ b/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml
@@ -42,7 +42,7 @@ Structure    <link linkend="eggdbus-struct-TemporaryAuthorization">TemporaryAuth
                                   IN  String                         object_path)
 <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse">AuthenticationAgentResponse</link>      (IN  String                         cookie,
                                   IN  <link linkend="eggdbus-struct-Identity">Identity</link>                       identity)
-<link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse">AuthenticationAgentResponse2</link>      (IN uint32 uid, IN  String                         cookie,
+<link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse2">AuthenticationAgentResponse2</link>      (IN uint32 uid, IN  String                         cookie,
                                   IN  <link linkend="eggdbus-struct-Identity">Identity</link>                       identity)
 <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.EnumerateTemporaryAuthorizations">EnumerateTemporaryAuthorizations</link> (IN  <link linkend="eggdbus-struct-Subject">Subject</link>                        subject,
                                   OUT Array&lt;<link linkend="eggdbus-struct-TemporaryAuthorization">TemporaryAuthorization</link>&gt;  temporary_authorizations)
@@ -701,7 +701,7 @@ RegisterAuthenticationAgent (IN  <link linkend="eggdbus-struct-Subject">Subject<
                              IN  String   object_path)
     </programlisting>
     <para>
-<para>Register an authentication agent.</para><para>Note that current versions of PolicyKit will only work if <parameter>session_id</parameter> is set to the empty string. In the future it might work for non-empty strings if the caller is sufficiently privileged.</para>
+<para>Register an authentication agent.</para><para>Note that this should be called by same effective UID which will be passed to <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse2">AuthenticationAgentResponse2()</link>.</para>
     </para>
 <variablelist role="params">
   <varlistentry>
@@ -781,7 +781,8 @@ AuthenticationAgentResponse (IN  String    cookie,
     <para>
 Method for authentication agents to invoke on successful
 authentication, intended only for use by a privileged helper process
-internal to polkit.  Deprecated in favor of AuthenticationAgentResponse2.
+internal to polkit. This method will fail unless a sufficiently privileged
++caller invokes it. Deprecated in favor of <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse2">AuthenticationAgentResponse2()</link>.
     </para>
 <variablelist role="params">
   <varlistentry>
@@ -812,7 +813,10 @@ AuthenticationAgentResponse2 (IN  uint32 uid,
     <para>
 Method for authentication agents to invoke on successful
 authentication, intended only for use by a privileged helper process
-internal to polkit.  Note this method was introduced in 0.114 to fix a security issue.
+internal to polkit. This method will fail unless a sufficiently privileged
+caller invokes it. Note this method was introduced in 0.114 and should be
+preferred over <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse">AuthenticationAgentResponse()</link>
+as it fixes a security issue.
     </para>
 <variablelist role="params">
   <varlistentry>
diff --git a/docs/polkit/overview.xml b/docs/polkit/overview.xml
index 176d2ea..2fa55bf 100644
--- a/docs/polkit/overview.xml
+++ b/docs/polkit/overview.xml
@@ -321,11 +321,11 @@
       linkend="eggdbus-interface-org.freedesktop.PolicyKit1.AuthenticationAgent">org.freedesktop.PolicyKit1.AuthenticationAgent</link>
       D-Bus interface. Once the user is authenticated, (a privileged
       part of) the agent invokes the <link
-      linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse">AuthenticationAgentResponse()</link>
+      linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse2">AuthenticationAgentResponse2()</link>
       method.  This method should be treated as an internal
-      implementation detail, and callers should use the public shared
-      library API to invoke it, which currently uses a setuid helper
-      program.
+      implementation detail, and callers should use the
+      <link linkend="PolkitAgentSession">PolkitAgentSession</link> API to invoke
+      it, which currently uses a setuid helper program.
     </para>
     <para>
       The <link linkend="ref-authentication-agent-api">libpolkit-agent-1</link>