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.
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>
<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>
</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>
</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>
</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>
</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>
</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>
</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>
</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>
</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>
</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>
</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>
</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>
</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>
</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>
</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>
</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>
</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>
</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>
</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>
</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>
</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>
<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:
</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>
</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>
</tgroup>
</table>
</sect1>
+
</chapter>
<chapter>
projects / platform / upstream / udisks2.git / commitdiff