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>

2 files changed, 10 insertions, 7 deletions

diff --git a/data/org.freedesktop.PolicyKit1.AuthenticationAgent.xml b/data/org.freedesktop.PolicyKit1.AuthenticationAgent.xml
index 5beef7d..482332f 100644
--- a/data/org.freedesktop.PolicyKit1.AuthenticationAgent.xml
+++ b/data/org.freedesktop.PolicyKit1.AuthenticationAgent.xml
@@ -13,14 +13,14 @@
       user to authenticate as one of the identities in @identities for
       the action with the identifier @action_id.</para><para>This
       authentication is normally achieved via the
-      polkit_agent_session_response() API, which invokes a private
+      PolkitAgentSession API, which invokes a private
       setuid helper process to verify the authentication.  When
       successful, it calls the
       org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse2()
       method on the #org.freedesktop.PolicyKit1.Authority interface of
       the PolicyKit daemon before returning.  If the user dismisses the
-      authentication dialog, the authentication agent should call
-      polkit_agent_session_cancel().</para>"/>
+      authentication dialog, the authentication agent should return an
+      error.</para>"/>
 
       <arg name="action_id" direction="in" type="s">
         <annotation name="org.gtk.EggDBus.DocString" value="The identifier for the action that the user is authentication for."/>
diff --git a/data/org.freedesktop.PolicyKit1.Authority.xml b/data/org.freedesktop.PolicyKit1.Authority.xml
index f9021ee..88da3c0 100644
--- a/data/org.freedesktop.PolicyKit1.Authority.xml
+++ b/data/org.freedesktop.PolicyKit1.Authority.xml
@@ -283,7 +283,7 @@
     <!-- ---------------------------------------------------------------------------------------------------- -->
 
     <method name="RegisterAuthenticationAgent">
-      <annotation name="org.gtk.EggDBus.DocString" value="<para>Register an authentication agent.</para><para>Note that current versions of PolicyKit will only work if @session_id is set to the empty string. In the future it might work for non-empty strings if the caller is sufficiently privileged.</para>"/>
+      <annotation name="org.gtk.EggDBus.DocString" value="<para>Register an authentication agent.</para><para>Note that this should be called by the same effective UID which will be passed to org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse2().</para>"/>
 
       <arg name="subject" direction="in" type="(sa{sv})">
         <annotation name="org.gtk.EggDBus.Type" value="Subject"/>
@@ -315,7 +315,8 @@
     <method name="AuthenticationAgentResponse">
       <annotation name="org.gtk.EggDBus.DocString" value="Method for authentication agents to invoke on successful
 authentication, intended only for use by a privileged helper process
-internal to polkit."/>
+internal to polkit. This method will fail unless a sufficiently privileged
+caller invokes it. Deprecated in favor of org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse2."/>
 
       <arg name="cookie" direction="in" type="s">
         <annotation name="org.gtk.EggDBus.DocString" value="The cookie identifying the authentication request that was passed to the authentication agent."/>
@@ -330,11 +331,13 @@ internal to polkit."/>
     <method name="AuthenticationAgentResponse2">
       <annotation name="org.gtk.EggDBus.DocString" value="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 added in 0.114, and should be preferred over AuthenticationAgentResponse
+internal to polkit. This method will fail unless a sufficiently privileged
+caller invokes it. Note this method was added in 0.114, and should be preferred over org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse()
 as it fixes a security issue."/>
 
       <arg name="uid" direction="in" type="u">
-        <annotation name="org.gtk.EggDBus.DocString" value="The real uid of the agent.  Normally set by the setuid helper program."/>
+        <annotation name="org.gtk.EggDBus.DocString" value="The real uid of the agent.  Normally set by the setuid helper program.
+Must match the effective UID of the caller of org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent()."/>
       </arg>
 
       <arg name="cookie" direction="in" type="s">