Attachment 116543 Details for Bug 90837 – 0002-Documentation-fixes-and-additions.patch

[patch] 0002-Documentation-fixes-and-additions.patch

0002-Documentation-fixes-and-additions.patch (text/plain), 15.58 KB, created by Miloslav Trmac on 2015-06-16 23:15:11 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Miloslav Trmac

Created: 2015-06-16 23:15:11 UTC

Size: 15.58 KB

patch

obsolete

>From 06e801df208c61e395c4a6537ff18622bd458cca Mon Sep 17 00:00:00 2001
>From: =?UTF-8?q?Miloslav=20Trma=C4=8D?= <mitr@redhat.com>
>Date: Wed, 17 Jun 2015 01:01:27 +0200
>Subject: [PATCH 2/2] Documentation fixes and additions
>
>---
> ....freedesktop.PolicyKit1.AuthenticationAgent.xml |  6 +++---
> data/org.freedesktop.PolicyKit1.Authority.xml      | 11 ++++++----
> ....freedesktop.PolicyKit1.AuthenticationAgent.xml |  7 +++++--
> ...erface-org.freedesktop.PolicyKit1.Authority.xml | 12 +++++++----
> docs/polkit/overview.xml                           |  8 ++++----
> src/polkit/polkitauthority.c                       | 24 ++++++++++++++++++++--
> src/polkitagent/polkitagentlistener.c              |  5 +----
> src/polkitbackend/polkitbackendauthority.c         |  1 +
> 8 files changed, 51 insertions(+), 23 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">
>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>
>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.
>-- 
>2.4.3
>

Actions: View | Splinter Review

Attachments on bug 90837: 116273 | 116289 | 116290 | 116337 | 116338 | 116542 | 116543

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.