From: David Zeuthen <davidz@redhat.com>
Date: Mon, 23 Apr 2012 17:23:38 +0000 (-0400)
Subject: Add section about polkit actions to the docs
X-Git-Tag: upstream/2.1.2~286
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=249485bfa029219603ea9be7a46dce18dccfdcc9;p=platform%2Fupstream%2Fudisks2.git

Add section about polkit actions to the docs

Also,

 - Add more comments to the .policy file (since it's included verbatim)
 - Explicitly state that polkit actions are not considered stable
 - Don't reference polkit actions in D-Bus docs
 - Cross-reference polkit actions chapter from udisks(8) man page
 - Mention ID_SEAT in udisks(8) man page

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

diff --git a/data/org.freedesktop.UDisks2.xml b/data/org.freedesktop.UDisks2.xml
index ee76c32..4d0a2bd 100644
--- a/data/org.freedesktop.UDisks2.xml
+++ b/data/org.freedesktop.UDisks2.xml
@@ -1118,36 +1118,21 @@
         filesystem types are validated against a (small) whitelist to
         avoid unexpected privilege escalation
 
-        Mounting a file system is a privileged operation and before
-        fulfilling the request, an authorization check for one of the
-        two actions
-        <emphasis>org.freedesktop.udisks2.filesystem-mount</emphasis>
-        or
-        <emphasis>org.freedesktop.udisks2.filesystem-mount-system</emphasis>
-        is performed (the value of the
-        #org.freedesktop.UDisks2.Block:HintSystem property is used to
-        determine which one). The latter check typically results in
-        the user having to authenticate as an administrator while the
-        former typically doesn't require authentication if the caller
-        is on a local console.
-
         If the device in question is referenced in the
         <filename>/etc/fstab</filename> file, the
         <command>mount</command> command is called directly (as root)
         and the given options or filesystem type given in @options are
-        ignored. The authorization checks mentioned above are still
-        performed.
+        ignored.
 
         If <literal>x-udisks-auth</literal> is specified as an option
         for the device in the <filename>/etc/fstab</filename> file,
         then the <command>mount</command> command is run as the
-        calling user, without performing any of the authorization
-        checks mentioned above. If this fails because of insufficient
-        permissions, an authorization check is performed for the
-        <emphasis>org.freedesktop.udisks2.filesystem-fstab</emphasis>
-        action which typically results in the user having to
-        authenticate as an administrator. If authorized, the
-        <command>mount</command> command is then run as root.
+        calling user, without performing any authorization check
+        mentioned above. If this fails because of insufficient
+        permissions, an authorization check is performed (which
+        typically results in the user having to authenticate as an
+        administrator). If authorized, the <command>mount</command>
+        command is then run as root.
 
         The filesystem should be unmounted using the
         org.freedesktop.UDisks2.Filesystem.Unmount() method.
@@ -1175,11 +1160,9 @@
         If the device in question was not mounted by the calling user
         via the org.freedesktop.UDisks2.Filesystem.Mount() method the
         filesystem is unmounted without any authorization checks.
-        Otherwise, an authorization check is performed for the
-        <emphasis>org.freedesktop.udisks2.filesystem-unmount-others</emphasis>
-        action which typically results in the user having to
-        authenticate as an administrator. If authorized, the
-        filesystem is unmounted.
+        Otherwise, an authorization check is performed (which
+        typically results in the user having to authenticate as an
+        administrator). If authorized, the filesystem is unmounted.
 
         If the filesystem is busy, this operation fails with the error
         <link linkend="UDISKS-ERROR-DEVICE-BUSY:CAPS"><constant>org.freedesktop.UDisks2.Error.DeviceBusy</constant></link>
diff --git a/data/org.freedesktop.udisks2.policy.in b/data/org.freedesktop.udisks2.policy.in
index 7963252..7425765 100644
--- a/data/org.freedesktop.udisks2.policy.in
+++ b/data/org.freedesktop.udisks2.policy.in
@@ -9,7 +9,9 @@
   <vendor_url>http://udisks.freedesktop.org/</vendor_url>
   <icon_name>drive-removable-media</icon_name>
 
+  <!-- ###################################################################### -->
   <!-- Mounting filesystems -->
+
   <action id="org.freedesktop.udisks2.filesystem-mount">
     <_description>Mount a filesystem</_description>
     <_message>Authentication is required to mount the filesystem</_message>
@@ -20,6 +22,7 @@
     </defaults>
   </action>
 
+  <!-- mount a device considered a "system device" -->
   <action id="org.freedesktop.udisks2.filesystem-mount-system">
     <_description>Mount a filesystem on a system device</_description>
     <_message>Authentication is required to mount the filesystem</_message>
@@ -30,6 +33,7 @@
     </defaults>
   </action>
 
+  <!-- mount a device attached to on another seat -->
   <action id="org.freedesktop.udisks2.filesystem-mount-other-seat">
     <_description>Mount a filesystem from a device plugged into another seat</_description>
     <_message>Authentication is required to mount the filesystem</_message>
@@ -40,6 +44,7 @@
     </defaults>
   </action>
 
+  <!-- mount a device referenced in the /etc/fstab file with the x-udisks-auth option -->
   <action id="org.freedesktop.udisks2.filesystem-fstab">
     <_description>Mount/unmount filesystems defined in the fstab file with the x-udisks-auth option</_description>
     <_message>Authentication is required to mount/unmount the filesystem</_message>
@@ -50,6 +55,10 @@
     </defaults>
   </action>
 
+  <!-- ###################################################################### -->
+  <!-- Unmounting filesystems -->
+
+  <!-- unmount a filesystem mounted by another user -->
   <action id="org.freedesktop.udisks2.filesystem-unmount-others">
     <_description>Unmount a device mounted by another user</_description>
     <_message>Authentication is required to unmount a filesystem mounted by another user</_message>
@@ -60,6 +69,7 @@
     </defaults>
   </action>
 
+  <!-- unmount a filesystem mounted by another user, on a drive shared by all seats -->
   <action id="org.freedesktop.udisks2.filesystem-unmount-others-shared">
     <_description>Unmount a shared device mounted by another user</_description>
     <_message>Authentication is required to unmount a filesystem mounted by another user</_message>
@@ -70,7 +80,9 @@
     </defaults>
   </action>
 
+  <!-- ###################################################################### -->
   <!-- Unlocking encrypted devices -->
+
   <action id="org.freedesktop.udisks2.encrypted-unlock">
     <_description>Unlock an encrypted device</_description>
     <_message>Authentication is required to unlock an encrypted device</_message>
@@ -81,6 +93,7 @@
     </defaults>
   </action>
 
+  <!-- unlock a device considered a "system device" -->
   <action id="org.freedesktop.udisks2.encrypted-unlock-system">
     <_description>Unlock an encrypted system device</_description>
     <_message>Authentication is required to unlock an encrypted device</_message>
@@ -91,6 +104,7 @@
     </defaults>
   </action>
 
+  <!-- mount a device attached to on another seat -->
   <action id="org.freedesktop.udisks2.encrypted-unlock-other-seat">
     <_description>Unlock an encrypted device plugged into another seat</_description>
     <_message>Authentication is required to unlock an encrypted device</_message>
@@ -101,6 +115,7 @@
     </defaults>
   </action>
 
+  <!-- unlock a device referenced in the /etc/crypttab file with the x-udisks-auth option -->
   <action id="org.freedesktop.udisks2.encrypted-unlock-crypttab">
     <_description>Unlock an encrypted device specified in the crypttab file with the x-udisks-auth option</_description>
     <_message>Authentication is required to unlock an encrypted device</_message>
@@ -111,6 +126,10 @@
     </defaults>
   </action>
 
+  <!-- ###################################################################### -->
+  <!-- Locking encrypted devices -->
+
+  <!-- lock a device unlocked by another user -->
   <action id="org.freedesktop.udisks2.encrypted-lock-others">
     <_description>Lock an encrypted device unlocked by another user</_description>
     <_message>Authentication is required to lock an encrypted device unlocked by another user</_message>
@@ -121,6 +140,9 @@
     </defaults>
   </action>
 
+  <!-- ###################################################################### -->
+  <!-- Changing passphrases on encrypted devices -->
+
   <action id="org.freedesktop.udisks2.encrypted-change-passphrase">
     <_description>Change passphrase for an encrypted device</_description>
     <_message>Authentication is required to change the passphrase for an encrypted device</_message>
@@ -131,6 +153,7 @@
     </defaults>
   </action>
 
+  <!-- change passphrase on a device considered a "system device" -->
   <action id="org.freedesktop.udisks2.encrypted-change-passphrase-system">
     <_description>Change passphrase for an encrypted device</_description>
     <_message>Authentication is required to change the passphrase for an encrypted device</_message>
@@ -141,18 +164,23 @@
     </defaults>
   </action>
 
+  <!-- ###################################################################### -->
   <!-- Setting up loop devices -->
+
   <action id="org.freedesktop.udisks2.loop-setup">
     <_description>Manage loop devices</_description>
     <_message>Authentication is required to set up a loop device</_message>
     <defaults>
       <allow_any>auth_admin</allow_any>
       <allow_inactive>auth_admin</allow_inactive>
-      <!-- not a DoS because we are using /dev/loop-control -->
+      <!-- NOTE: this is not a DoS because we are using /dev/loop-control -->
       <allow_active>yes</allow_active>
     </defaults>
   </action>
 
+  <!-- ###################################################################### -->
+  <!-- Deleting loop devices -->
+
   <action id="org.freedesktop.udisks2.loop-delete-others">
     <_description>Manage loop devices</_description>
     <_message>Authentication is required to delete a loop device set up by another user</_message>
@@ -163,7 +191,9 @@
     </defaults>
   </action>
 
-  <!-- Manage swapspace -->
+  <!-- ###################################################################### -->
+  <!-- Manage (start/stop) swapspace -->
+
   <action id="org.freedesktop.udisks2.manage-swapspace">
     <_description>Manage swapspace</_description>
     <_message>Authentication is required to manage swapspace</_message>
@@ -174,7 +204,9 @@
     </defaults>
   </action>
 
+  <!-- ###################################################################### -->
   <!-- Modify a device (create new filesystem, partitioning, change FS label, ejecting media, etc.) -->
+
   <action id="org.freedesktop.udisks2.modify-device">
     <_description>Modify a device</_description>
     <_message>Authentication is required to modify a device</_message>
@@ -185,6 +217,7 @@
     </defaults>
   </action>
 
+  <!-- modify a device considered a "system device" -->
   <action id="org.freedesktop.udisks2.modify-device-system">
     <_description>Modify a system device</_description>
     <_message>Authentication is required to modify a device</_message>
@@ -195,6 +228,7 @@
     </defaults>
   </action>
 
+  <!-- modify a device attached to on another seat -->
   <action id="org.freedesktop.udisks2.modify-device-other-seat">
     <_description>Modify a device</_description>
     <_message>Authentication is required to modify a device plugged into another seat</_message>
@@ -205,7 +239,9 @@
     </defaults>
   </action>
 
-  <!-- Open a device for reading (for creating disk images) -->
+  <!-- ###################################################################### -->
+  <!-- Open a device for reading (for creating / restoring disk images) -->
+
   <action id="org.freedesktop.udisks2.open-device">
     <_description>Open a device</_description>
     <_message>Authentication is required to open a device</_message>
@@ -226,12 +262,16 @@
     </defaults>
   </action>
 
+  <!-- ###################################################################### -->
   <!-- Manage system-wide configuration files such as /etc/fstab or
        /etc/crypttab ... including files referenced by these files.
 
-       It is insecure to automatically grant this to groups of users or
-       to allow a process to retain the authorization.
+       IMPORTANT: It is not secure to automatically grant authority
+       for this action to groups of users. Neither is it secure to
+       to allow a process to retain the authorization (e.g. don't
+       use the _keep variants).
   -->
+
   <action id="org.freedesktop.udisks2.modify-system-configuration">
     <_description>Modify system-wide configuration</_description>
     <_message>Authentication is required to modify system-wide configuration</_message>
@@ -253,7 +293,10 @@
     </defaults>
   </action>
 
-  <!-- Update SMART data -->
+  <!-- ###################################################################### -->
+  <!-- ATA SMART -->
+
+  <!-- Update/refresh SMART data -->
   <action id="org.freedesktop.udisks2.ata-smart-update">
     <_description>Update SMART data</_description>
     <_message>Authentication is required to update SMART data</_message>
diff --git a/doc/man/udisks.xml b/doc/man/udisks.xml
index ed69f98..0612c09 100644
--- a/doc/man/udisks.xml
+++ b/doc/man/udisks.xml
@@ -31,37 +31,51 @@
   <refsect1><title>ACCESS CONTROL</title>
     <para>
       By default, logged-in users in active log-in sessions are
-      permitted to mount and unlock devices attached to the local
-      console. To lock down globally, configure the
-      <citerefentry><refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-      authorizations for the actions
-      <literal>filesystem-mount</literal>,
-      <literal>filesystem-mount-system</literal>,
-      <literal>encrypted-unlock</literal> and
-      <literal>encrypted-unlock-system</literal>, all in the
-      <literal>org.freedesktop.udisks2</literal> namespace.
+      permitted to perform operations (for example, mounting,
+      unlocking or modifying) devices attached to the seat their
+      session is on. Access-control is fine-grained and based on
+      <citerefentry><refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      see the <quote><link
+      linkend="udisks-polkit-actions">Authorization
+      Checks</link></quote> chapter in the udisks documentation for
+      more information (<ulink
+      url="http://udisks.freedesktop.org/docs/latest/udisks-polkit-actions.html">available
+      online here</ulink>).
     </para>
     <para>
-      Note that the actions ending in <literal>-system</literal>
-      typically requires administrator authentication and are used for
-      devices not considered "removable" (devices considered
-      "removable" include USB attached storage, Flash media, optical
-      discs etc.). The udev property <literal>UDISKS_SYSTEM</literal>
-      can be used to override this on a per-device basis, see below.
+      Note that the polkit actions ending in
+      <literal>-system</literal> typically requires administrator
+      authentication and are used for devices not considered
+      <quote>removable</quote> (devices considered removable include
+      USB attached storage, Flash media, optical discs etc.). The udev
+      property <literal>UDISKS_SYSTEM</literal> can be used to
+      override this on a per-device basis, see below.
     </para>
     <para>
-      To lock down access on a per-device basis, use the option
-      <literal>x-udisks-auth</literal> in the
-      <filename>/etc/fstab</filename> file and the option
-      <literal>x-udisks-auth</literal> in the
-      <filename>/etc/crypttab</filename> file.
+      The <literal>x-udisks-auth</literal> option can be used in the
+      <filename>/etc/fstab</filename> and
+      <filename>/etc/crypttab</filename> files to specify that
+      additional authorization is required to mount resp. unlock the
+      device (typically requiring the user to authenticate as an
+      administrator).
+    </para>
+  </refsect1>
+
+  <refsect1><title>WHAT THE USER SEES</title>
+    <para>
+      udisks is a system-level component and is not per se concerned
+      with what a desktop user interface shows the user. For GNOME see
+      these <ulink
+      url="http://git.gnome.org/browse/gvfs/tree/monitor/udisks2/what-is-shown.txt">GVfs
+      notes</ulink> about what is shown in the desktop user interface
+      and how to influence it.
     </para>
   </refsect1>
 
   <refsect1>
     <title>DEVICE INFORMATION</title>
     <para>
-      On Linux, udisks relies on recent versions of
+      udisks relies on recent versions of
       <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>
       and the Linux kernel. Influential device properties in the udev
       database include:
@@ -116,6 +130,23 @@
           </para>
         </listitem>
       </varlistentry>
+      <varlistentry>
+        <term><option>ID_SEAT</option></term>
+        <listitem>
+          <para>
+            The physical seat the device is attached to. If not set,
+            <quote>seat0</quote> (the first seat) is assumed. The
+            special value <quote>all</quote> means that the device
+            should be available on all seats, e.g. available from
+            login sessions running on any seat. This also means that
+            special mount options and mount directory will be used so
+            all users can access mounted filesystems from the device -
+            for example, the device will be mounted in
+            <filename>/media</filename> instead of
+            <filename>/run/media/USER</filename>.
+          </para>
+        </listitem>
+      </varlistentry>
     </variablelist>
 
     <para>
diff --git a/doc/udisks2-docs.xml b/doc/udisks2-docs.xml
index b7363b8..558a208 100644
--- a/doc/udisks2-docs.xml
+++ b/doc/udisks2-docs.xml
@@ -125,6 +125,60 @@
         </para>
       </sect1>
 
+      <sect1 id="udisks-polkit-actions">
+        <title>Authorization Checks</title>
+        <para>
+          Many methods and operations offered by udisks requires the
+          calling user to be sufficiently authorized. Whether the user
+          is authorized is checked using <ulink
+          url="http://hal.freedesktop.org/docs/polkit/polkit.8.html">polkit</ulink>
+          and the administrator can configure <ulink
+          url="http://hal.freedesktop.org/docs/polkit/pklocalauthority.8.html">polkit's
+          local authority</ulink> (but note that the system may be
+          using another polkit authority implementation).
+        </para>
+        <para>
+          There is not necessarily a one-to-one relationship between
+          D-Bus methods and polkit actions - typically the
+          relationship is more complicated and depends on both the
+          context of the process invoking the method, the object the
+          method is acting on and possibly more factors. For example,
+          the <link
+          linkend="gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount">Filesystem.Mount()</link>
+          method call may check that the caller is authorized for one
+          of the four actions
+          <emphasis>org.freedesktop.udisks2.filesystem-mount</emphasis>,
+          <emphasis>org.freedesktop.udisks2.filesystem-mount-system</emphasis>,
+          <emphasis>org.freedesktop.udisks2.filesystem-mount-other-seat</emphasis>
+          or
+          <emphasis>org.freedesktop.udisks2.filesystem-mount-fstab</emphasis>
+          depending on circumstances.
+        </para>
+        <para>
+          Often there will be two polkit actions for one operation -
+          one for so-called <quote>system devices</quote> and one for
+          non-system devices. In this context <quote>system
+          device</quote> refers to the value of the <link
+          linkend="gdbus-property-org-freedesktop-UDisks2-Block.HintSystem">Block:HintSystem</link>
+          D-Bus property and is normally only
+          <constant>TRUE</constant> for devices not considered
+          <quote>removable</quote> (devices considered removable
+          include USB attached storage, Flash media and optical
+          drives). See <xref linkend="udisks.8"/> for how to control
+          if a device is considered a system device.
+        </para>
+        <para>
+          The polkit actions are not considered stable and may change
+          from release to release so administrators should take notice
+          when upgrading from one version of udisks to another. For
+          example, <filename>.pkla</filename> files may need to be
+          updated to match an updated policy.
+          For reference, the polkit actions defined by udisks &version;
+          are included here:
+          <informalexample id="udisks-polkit-actions-file"><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../data/org.freedesktop.udisks2.policy.in"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></informalexample>
+        </para>
+      </sect1>
+
       <sect1 id="udisks-std-options">
         <title>The <parameter>options</parameter> parameter</title>
         <para>
@@ -157,6 +211,7 @@
           </tgroup>
         </table>
       </sect1>
+
     </chapter>
 
     <chapter>