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, 24 insertions, 6 deletions

diff --git a/src/polkit/polkitauthority.c b/src/polkit/polkitauthority.c
index 6bd684a..7c4db7b 100644
--- a/src/polkit/polkitauthority.c
+++ b/src/polkit/polkitauthority.c
@@ -1038,6 +1038,10 @@ polkit_authority_check_authorization_sync (PolkitAuthority               *author
  *
  * Asynchronously registers an authentication agent.
  *
+ * Note that this should be called by the same effective UID which will be
+ * the real UID using the #PolkitAgentSession API or otherwise calling
+ * polkit_authority_authentication_agent_response().
+ *
  * When the operation is finished, @callback will be invoked in the
  * <link linkend="g-main-context-push-thread-default">thread-default
  * main loop</link> of the thread you are calling this method
@@ -1129,7 +1133,13 @@ polkit_authority_register_authentication_agent_finish (PolkitAuthority *authorit
  * @cancellable: (allow-none): A #GCancellable or %NULL.
  * @error: (allow-none): Return location for error or %NULL.
  *
- * Registers an authentication agent. The calling thread is blocked
+ * Registers an authentication agent.
+ *
+ * Note that this should be called by the same effective UID which will be
+ * the real UID using the #PolkitAgentSession API or otherwise calling
+ * polkit_authority_authentication_agent_response().
+ *
+ * The calling thread is blocked
  * until a reply is received. See
  * polkit_authority_register_authentication_agent() for the
  * asynchronous version.
@@ -1178,6 +1188,10 @@ polkit_authority_register_authentication_agent_sync (PolkitAuthority     *author
  *
  * Asynchronously registers an authentication agent.
  *
+ * Note that this should be called by the same effective UID which will be
+ * the real UID using the #PolkitAgentSession API or otherwise calling
+ * polkit_authority_authentication_agent_response().
+ *
  * When the operation is finished, @callback will be invoked in the
  * <link linkend="g-main-context-push-thread-default">thread-default
  * main loop</link> of the thread you are calling this method
@@ -1292,7 +1306,13 @@ polkit_authority_register_authentication_agent_with_options_finish (PolkitAuthor
  * @cancellable: (allow-none): A #GCancellable or %NULL.
  * @error: (allow-none): Return location for error or %NULL.
  *
- * Registers an authentication agent. The calling thread is blocked
+ * Registers an authentication agent.
+ *
+ * Note that this should be called by the same effective UID which will be
+ * the real UID using the #PolkitAgentSession API or otherwise calling
+ * polkit_authority_authentication_agent_response().
+ *
+ * The calling thread is blocked
  * until a reply is received. See
  * polkit_authority_register_authentication_agent_with_options() for the
  * asynchronous version.
diff --git a/src/polkitagent/polkitagentlistener.c b/src/polkitagent/polkitagentlistener.c
index 8c333af..80d1dc1 100644
--- a/src/polkitagent/polkitagentlistener.c
+++ b/src/polkitagent/polkitagentlistener.c
@@ -37,10 +37,7 @@
  *
  * Typically authentication agents use #PolkitAgentSession to
  * authenticate users (via passwords) and communicate back the
- * authentication result to the PolicyKit daemon.  This is however not
- * requirement. Depending on the system an authentication agent may
- * use other means (such as a Yes/No dialog) to obtain sufficient
- * evidence that the user is one of the requested identities.
+ * authentication result to the PolicyKit daemon.
  *
  * To register a #PolkitAgentListener with the PolicyKit daemon, use
  * polkit_agent_listener_register() or
diff --git a/src/polkitbackend/polkitbackendauthority.c b/src/polkitbackend/polkitbackendauthority.c
index 03a4e84..a09d667 100644
--- a/src/polkitbackend/polkitbackendauthority.c
+++ b/src/polkitbackend/polkitbackendauthority.c
@@ -343,6 +343,7 @@ polkit_backend_authority_unregister_authentication_agent (PolkitBackendAuthority
  * polkit_backend_authority_authentication_agent_response:
  * @authority: A #PolkitBackendAuthority.
  * @caller: The system bus name that initiated the query.
+ * @uid: The real UID of the registered agent, or (uid_t)-1 if unknown.
  * @cookie: The cookie passed to the authentication agent from the authority.
  * @identity: The identity that was authenticated.
  * @error: Return location for error or %NULL.