Add some documentation about polkit variables
authorDavid Zeuthen <davidz@redhat.com>
Fri, 18 May 2012 17:08:06 +0000 (13:08 -0400)
committerDavid Zeuthen <davidz@redhat.com>
Fri, 18 May 2012 17:08:06 +0000 (13:08 -0400)
In particular, guarantee that $(udisks2.device) is always a device
file, if set.

We may want to add more variables in the future such as
udisks2.drive.{vendor,model,serial,wwn}.

This is related to the new experimental JS-based polkit authority, see

 https://plus.google.com/u/0/110773474140772402317/posts/LB1QjaoaEn2

for more details.

Signed-off-by: David Zeuthen <davidz@redhat.com>
doc/udisks2-docs.xml
src/udisksdaemonutil.c
src/udiskslinuxblock.c
src/udiskslinuxdrive.c
src/udiskslinuxdriveata.c
src/udiskslinuxencrypted.c
src/udiskslinuxfilesystem.c
src/udiskslinuxloop.c
src/udiskslinuxpartition.c
src/udiskslinuxpartitiontable.c
src/udiskslinuxswapspace.c

index 3c91ffe..2a73e00 100644 (file)
           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.
+        </para>
+        <para>
+          See <xref linkend="udisks-polkit-details"/> for the
+          variables that can be used to assist in determining if the
+          caller is authorized (note that each variable may not be set
+          for request). For example, a polkit authorization rule for
+          any of the
+          <emphasis>org.freedesktop.udisks2.filesystem-mount*</emphasis>
+          actions can use the <parameter>udisks2.device</parameter>
+          variable to determine if the caller is authorized to mount a
+          specific device.
+        </para>
+        <para>
           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>
index 0350b1f..0ed0d6a 100644 (file)
@@ -417,9 +417,30 @@ udisks_daemon_util_setup_by_user (UDisksDaemon *daemon,
  * authentication which may be a very long time unless
  * @auth_no_user_interaction is %TRUE.
  *
- * The follow variables can be used in @message
- *
- * - udisks2.device - If @object has a #UDisksBlock interface, this property is set to the value of the #UDisksBlock::preferred-device property.
+ * See <xref linkend="udisks-polkit-details"/> for the variables that
+ * can be used in @message.
+ *
+ * <table frame="all" id="udisks-polkit-details">
+ *   <title>Known polkit details variables</title>
+ *   <tgroup cols="2" align="left" colsep="1" rowsep="1">
+ *     <thead>
+ *       <row>
+ *         <entry>key</entry>
+ *         <entry>value</entry>
+ *       </row>
+ *     </thead>
+ *     <tbody>
+ *       <row>
+ *         <entry><parameter>udisks2.device</parameter></entry>
+ *         <entry>If @object has a #UDisksBlock interface or #UDisksDrive interface, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Block.PreferredDevice">Block:PreferredDevice</link> property. If set, this is guaranteed to be a device file.</entry>
+ *       </row>
+ *       <row>
+ *         <entry><parameter>udisks2.drive</parameter></entry>
+ *         <entry>Like <parameter>udisks2.device</parameter>, but also includes Vital Product Data about the drive e.g. vendor/model (if available), for example "INTEL SSDSA2MH080G1GC (/dev/sda1)". Otherwise is just set to the same value as <parameter>udisks2.device</parameter>.</entry>
+ *       </row>
+ *     </tbody>
+ *   </tgroup>
+ * </table>
  *
  * Returns: %TRUE if caller is authorized, %FALSE if not.
  */
@@ -442,7 +463,8 @@ udisks_daemon_util_check_authorization_sync (UDisksDaemon          *daemon,
   UDisksObject *block_object = NULL;
   UDisksObject *drive_object = NULL;
   gboolean auth_no_user_interaction = FALSE;
-  gchar *details_udisks2_device = NULL;
+  const gchar *details_udisks2_device = NULL;
+  gchar *details_udisks2_drive = NULL;
 
   subject = polkit_system_bus_name_new (g_dbus_method_invocation_get_sender (invocation));
   if (options != NULL)
@@ -472,6 +494,9 @@ udisks_daemon_util_check_authorization_sync (UDisksDaemon          *daemon,
         }
     }
 
+  if (block != NULL)
+    details_udisks2_device = udisks_block_get_preferred_device (block);
+
   /* If we have a drive, use vendor/model in the message (in addition to Block:preferred-device) */
   if (drive != NULL)
     {
@@ -495,22 +520,24 @@ udisks_daemon_util_check_authorization_sync (UDisksDaemon          *daemon,
 
       if (block != NULL)
         {
-          details_udisks2_device = g_strdup_printf ("%s (%s)", s, udisks_block_get_preferred_device (block));
+          details_udisks2_drive = g_strdup_printf ("%s (%s)", s, udisks_block_get_preferred_device (block));
         }
       else
         {
-          details_udisks2_device = s;
+          details_udisks2_drive = s;
           s = NULL;
         }
       g_free (s);
     }
 
   /* Fall back to Block:preferred-device */
-  if (details_udisks2_device == NULL && block != NULL)
-    details_udisks2_device = udisks_block_dup_preferred_device (block);
+  if (details_udisks2_drive == NULL && block != NULL)
+    details_udisks2_drive = udisks_block_dup_preferred_device (block);
 
   if (details_udisks2_device != NULL)
     polkit_details_insert (details, "udisks2.device", details_udisks2_device);
+  if (details_udisks2_drive != NULL)
+    polkit_details_insert (details, "udisks2.drive", details_udisks2_drive);
 
   error = NULL;
   result = polkit_authority_check_authorization_sync (udisks_daemon_get_authority (daemon),
@@ -552,7 +579,7 @@ udisks_daemon_util_check_authorization_sync (UDisksDaemon          *daemon,
   ret = TRUE;
 
  out:
-  g_free (details_udisks2_device);
+  g_free (details_udisks2_drive);
   g_clear_object (&block_object);
   g_clear_object (&drive_object);
   g_clear_object (&block);
index 028b33e..85defd8 100644 (file)
@@ -1880,10 +1880,10 @@ handle_format (UDisksBlock           *block,
    * device. This includes both creating a filesystem or partition
    * table.
    *
-   * Do not translate $(udisks2.device), it's a placeholder and will
+   * Do not translate $(udisks2.drive), it's a placeholder and will
    * be replaced by the name of the drive/device in question
    */
-  message = N_("Authentication is required to format $(udisks2.device)");
+  message = N_("Authentication is required to format $(udisks2.drive)");
   action_id = "org.freedesktop.udisks2.modify-device";
   if (udisks_block_get_hint_system (block))
     {
@@ -2243,10 +2243,10 @@ handle_open_for_backup (UDisksBlock           *block,
                                                     /* Translators: Shown in authentication dialog when creating a
                                                      * disk image file.
                                                      *
-                                                     * Do not translate $(udisks2.device), it's a placeholder and will
+                                                     * Do not translate $(udisks2.drive), it's a placeholder and will
                                                      * be replaced by the name of the drive/device in question
                                                      */
-                                                    N_("Authentication is required to open $(udisks2.device) for reading"),
+                                                    N_("Authentication is required to open $(udisks2.drive) for reading"),
                                                     invocation))
     goto out;
 
@@ -2307,10 +2307,10 @@ handle_open_for_restore (UDisksBlock           *block,
                                                     /* Translators: Shown in authentication dialog when restoring
                                                      * from a disk image file.
                                                      *
-                                                     * Do not translate $(udisks2.device), it's a placeholder and will
+                                                     * Do not translate $(udisks2.drive), it's a placeholder and will
                                                      * be replaced by the name of the drive/device in question
                                                      */
-                                                    N_("Authentication is required to open $(udisks2.device) for writing"),
+                                                    N_("Authentication is required to open $(udisks2.drive) for writing"),
                                                     invocation))
     goto out;
 
index 37ce4d2..d8d7444 100644 (file)
@@ -740,10 +740,10 @@ handle_eject (UDisksDrive           *_drive,
   /* Translators: Shown in authentication dialog when the user
    * requests ejecting media from a drive.
    *
-   * Do not translate $(udisks2.device), it's a placeholder and
+   * Do not translate $(udisks2.drive), it's a placeholder and
    * will be replaced by the name of the drive/device in question
    */
-  message = N_("Authentication is required to eject $(udisks2.device)");
+  message = N_("Authentication is required to eject $(udisks2.drive)");
   action_id = "org.freedesktop.udisks2.eject-media";
   if (udisks_block_get_hint_system (block))
     {
index 2513445..afc6517 100644 (file)
@@ -611,10 +611,10 @@ handle_smart_update (UDisksDriveAta        *_drive,
   /* Translators: Shown in authentication dialog when the user
    * refreshes SMART data from a disk.
    *
-   * Do not translate $(udisks2.device), it's a placeholder and
+   * Do not translate $(udisks2.drive), it's a placeholder and
    * will be replaced by the name of the drive/device in question
    */
-  message = N_("Authentication is required to update SMART data from $(udisks2.device)");
+  message = N_("Authentication is required to update SMART data from $(udisks2.drive)");
   action_id = "org.freedesktop.udisks2.ata-smart-update";
 
   if (atasmart_blob != NULL)
@@ -622,10 +622,10 @@ handle_smart_update (UDisksDriveAta        *_drive,
       /* Translators: Shown in authentication dialog when the user
        * tries to simulate SMART data from a libatasmart blob.
        *
-       * Do not translate $(udisks2.device), it's a placeholder and
+       * Do not translate $(udisks2.drive), it's a placeholder and
        * will be replaced by the name of the drive/device in question
        */
-      message = N_("Authentication is required to set SMART data from a blob on $(udisks2.device)");
+      message = N_("Authentication is required to set SMART data from a blob on $(udisks2.drive)");
       action_id = "org.freedesktop.udisks2.ata-smart-simulate";
     }
   else
@@ -756,10 +756,10 @@ handle_smart_selftest_abort (UDisksDriveAta        *_drive,
                                                     /* Translators: Shown in authentication dialog when the user
                                                      * aborts a running SMART self-test.
                                                      *
-                                                     * Do not translate $(udisks2.device), it's a placeholder and
+                                                     * Do not translate $(udisks2.drive), it's a placeholder and
                                                      * will be replaced by the name of the drive/device in question
                                                      */
-                                                    N_("Authentication is required to abort a SMART self-test on $(udisks2.device)"),
+                                                    N_("Authentication is required to abort a SMART self-test on $(udisks2.drive)"),
                                                     invocation))
     goto out;
 
@@ -953,10 +953,10 @@ handle_smart_selftest_start (UDisksDriveAta        *_drive,
                                                     /* Translators: Shown in authentication dialog when the user
                                                      * initiates a SMART self-test.
                                                      *
-                                                     * Do not translate $(udisks2.device), it's a placeholder and
+                                                     * Do not translate $(udisks2.drive), it's a placeholder and
                                                      * will be replaced by the name of the drive/device in question
                                                      */
-                                                    N_("Authentication is required to start a SMART self-test on $(udisks2.device)"),
+                                                    N_("Authentication is required to start a SMART self-test on $(udisks2.drive)"),
                                                     invocation))
     goto out;
 
index 152258e..9322e67 100644 (file)
@@ -346,10 +346,10 @@ handle_unlock (UDisksEncrypted        *encrypted,
   /* Translators: Shown in authentication dialog when the user
    * requests unlocking an encrypted device.
    *
-   * Do not translate $(udisks2.device), it's a placeholder and
+   * Do not translate $(udisks2.drive), it's a placeholder and
    * will be replaced by the name of the drive/device in question
    */
-  message = N_("Authentication is required to unlock the encrypted device $(udisks2.device)");
+  message = N_("Authentication is required to unlock the encrypted device $(udisks2.drive)");
   if (!udisks_daemon_util_setup_by_user (daemon, object, caller_uid))
     {
       if (is_in_crypttab && has_option (crypttab_options, "x-udisks-auth"))
@@ -577,10 +577,10 @@ handle_lock (UDisksEncrypted        *encrypted,
                                                          * requests locking an encrypted device that was previously.
                                                          * unlocked by another user.
                                                          *
-                                                         * Do not translate $(udisks2.device), it's a placeholder and
+                                                         * Do not translate $(udisks2.drive), it's a placeholder and
                                                          * will be replaced by the name of the drive/device in question
                                                          */
-                                                        N_("Authentication is required to lock the encrypted device $(udisks2.device) unlocked by another user"),
+                                                        N_("Authentication is required to lock the encrypted device $(udisks2.drive) unlocked by another user"),
                                                         invocation))
         goto out;
     }
@@ -698,10 +698,10 @@ handle_change_passphrase (UDisksEncrypted        *encrypted,
                                                     /* Translators: Shown in authentication dialog when the user
                                                      * requests unlocking an encrypted device.
                                                      *
-                                                     * Do not translate $(udisks2.device), it's a placeholder and
+                                                     * Do not translate $(udisks2.drive), it's a placeholder and
                                                      * will be replaced by the name of the drive/device in question
                                                      */
-                                                    N_("Authentication is required to unlock the encrypted device $(udisks2.device)"),
+                                                    N_("Authentication is required to unlock the encrypted device $(udisks2.drive)"),
                                                     invocation))
     goto out;
 
index 3848aea..c46f446 100644 (file)
@@ -1216,10 +1216,10 @@ handle_mount (UDisksFilesystem       *filesystem,
           /* Translators: Shown in authentication dialog when the user
            * requests mounting a filesystem.
            *
-           * Do not translate $(udisks2.device), it's a placeholder and
+           * Do not translate $(udisks2.drive), it's a placeholder and
            * will be replaced by the name of the drive/device in question
            */
-          message = N_("Authentication is required to mount $(udisks2.device)");
+          message = N_("Authentication is required to mount $(udisks2.drive)");
           if (!udisks_daemon_util_setup_by_user (daemon, object, caller_uid))
             {
               if (udisks_block_get_hint_system (block))
@@ -1281,13 +1281,13 @@ handle_mount (UDisksFilesystem       *filesystem,
                                                                  * user requests mounting a filesystem that is in
                                                                  * /etc/fstab file with the x-udisks-auth option.
                                                                  *
-                                                                 * Do not translate $(udisks2.device), it's a
+                                                                 * Do not translate $(udisks2.drive), it's a
                                                                  * placeholder and will be replaced by the name of
                                                                  * the drive/device in question
                                                                  *
                                                                  * Do not translate /etc/fstab
                                                                  */
-                                                                N_("Authentication is required to mount $(udisks2.device) referenced in the /etc/fstab file"),
+                                                                N_("Authentication is required to mount $(udisks2.drive) referenced in the /etc/fstab file"),
                                                                 invocation))
                 goto out;
               mount_fstab_as_root = TRUE;
@@ -1377,10 +1377,10 @@ handle_mount (UDisksFilesystem       *filesystem,
   /* Translators: Shown in authentication dialog when the user
    * requests mounting a filesystem.
    *
-   * Do not translate $(udisks2.device), it's a placeholder and
+   * Do not translate $(udisks2.drive), it's a placeholder and
    * will be replaced by the name of the drive/device in question
    */
-  message = N_("Authentication is required to mount $(udisks2.device)");
+  message = N_("Authentication is required to mount $(udisks2.drive)");
   if (!udisks_daemon_util_setup_by_user (daemon, object, caller_uid))
     {
       if (udisks_block_get_hint_system (block))
@@ -1626,13 +1626,13 @@ handle_unmount (UDisksFilesystem       *filesystem,
                                                                  * user requests unmounting a filesystem that is in
                                                                  * /etc/fstab file with the x-udisks-auth option.
                                                                  *
-                                                                 * Do not translate $(udisks2.device), it's a
+                                                                 * Do not translate $(udisks2.drive), it's a
                                                                  * placeholder and will be replaced by the name of
                                                                  * the drive/device in question
                                                                  *
                                                                  * Do not translate /etc/fstab
                                                                  */
-                                                                N_("Authentication is required to unmount $(udisks2.device) referenced in the /etc/fstab file"),
+                                                                N_("Authentication is required to unmount $(udisks2.drive) referenced in the /etc/fstab file"),
                                                                 invocation))
                 goto out;
               unmount_fstab_as_root = TRUE;
@@ -1676,10 +1676,10 @@ handle_unmount (UDisksFilesystem       *filesystem,
        * requests unmounting a filesystem previously mounted by
        * another user.
        *
-       * Do not translate $(udisks2.device), it's a placeholder and
+       * Do not translate $(udisks2.drive), it's a placeholder and
        * will be replaced by the name of the drive/device in question
        */
-      message = N_("Authentication is required to unmount $(udisks2.device) mounted by another user");
+      message = N_("Authentication is required to unmount $(udisks2.drive) mounted by another user");
 
       if (!udisks_daemon_util_check_authorization_sync (daemon,
                                                         object,
@@ -1894,10 +1894,10 @@ handle_set_label (UDisksFilesystem       *filesystem,
   /* Translators: Shown in authentication dialog when the user
    * requests changing the filesystem label.
    *
-   * Do not translate $(udisks2.device), it's a placeholder and
+   * Do not translate $(udisks2.drive), it's a placeholder and
    * will be replaced by the name of the drive/device in question
    */
-  message = N_("Authentication is required to change the filesystem label on $(udisks2.device)");
+  message = N_("Authentication is required to change the filesystem label on $(udisks2.drive)");
   if (udisks_block_get_hint_system (block))
     {
       action_id = "org.freedesktop.udisks2.modify-device-system";
index 937d3b7..44088bf 100644 (file)
@@ -238,10 +238,10 @@ handle_delete (UDisksLoop             *loop,
                                                          * requests deleting a loop device previously set up by
                                                          * another user.
                                                          *
-                                                         * Do not translate $(udisks2.device), it's a placeholder and
+                                                         * Do not translate $(udisks2.drive), it's a placeholder and
                                                          * will be replaced by the name of the drive/device in question
                                                          */
-                                                        N_("Authentication is required to delete the loop device $(udisks2.device)"),
+                                                        N_("Authentication is required to delete the loop device $(udisks2.drive)"),
                                                         invocation))
         goto out;
     }
@@ -416,10 +416,10 @@ handle_set_autoclear (UDisksLoop             *loop,
                                                          * requests changing autoclear on a loop device set up by
                                                          * another user.
                                                          *
-                                                         * Do not translate $(udisks2.device), it's a placeholder and
+                                                         * Do not translate $(udisks2.drive), it's a placeholder and
                                                          * will be replaced by the name of the drive/device in question
                                                          */
-                                                        N_("Authentication is required to modify the loop device $(udisks2.device)"),
+                                                        N_("Authentication is required to modify the loop device $(udisks2.drive)"),
                                                         invocation))
         goto out;
     }
index 9582346..7694ca6 100644 (file)
@@ -259,10 +259,10 @@ handle_set_flags (UDisksPartition        *partition,
   /* Translators: Shown in authentication dialog when the user
    * requests modifying a partition (changing type, flags, name etc.).
    *
-   * Do not translate $(udisks2.device), it's a placeholder and
+   * Do not translate $(udisks2.drive), it's a placeholder and
    * will be replaced by the name of the drive/device in question
    */
-  message = N_("Authentication is required to modify the partition on device $(udisks2.device)");
+  message = N_("Authentication is required to modify the partition on device $(udisks2.drive)");
   if (udisks_block_get_hint_system (block))
     {
       action_id = "org.freedesktop.udisks2.modify-device-system";
@@ -404,10 +404,10 @@ handle_set_name (UDisksPartition        *partition,
   /* Translators: Shown in authentication dialog when the user
    * requests modifying a partition (changing type, flags, name etc.).
    *
-   * Do not translate $(udisks2.device), it's a placeholder and
+   * Do not translate $(udisks2.drive), it's a placeholder and
    * will be replaced by the name of the drive/device in question
    */
-  message = N_("Authentication is required to modify the partition on device $(udisks2.device)");
+  message = N_("Authentication is required to modify the partition on device $(udisks2.drive)");
   if (udisks_block_get_hint_system (block))
     {
       action_id = "org.freedesktop.udisks2.modify-device-system";
@@ -586,10 +586,10 @@ handle_set_type (UDisksPartition        *partition,
   /* Translators: Shown in authentication dialog when the user
    * requests modifying a partition (changing type, flags, name etc.).
    *
-   * Do not translate $(udisks2.device), it's a placeholder and
+   * Do not translate $(udisks2.drive), it's a placeholder and
    * will be replaced by the name of the drive/device in question
    */
-  message = N_("Authentication is required to modify the partition on device $(udisks2.device)");
+  message = N_("Authentication is required to modify the partition on device $(udisks2.drive)");
   if (udisks_block_get_hint_system (block))
     {
       action_id = "org.freedesktop.udisks2.modify-device-system";
@@ -759,10 +759,10 @@ handle_delete (UDisksPartition        *partition,
   /* Translators: Shown in authentication dialog when the user
    * requests deleting a partition.
    *
-   * Do not translate $(udisks2.device), it's a placeholder and
+   * Do not translate $(udisks2.drive), it's a placeholder and
    * will be replaced by the name of the drive/device in question
    */
-  message = N_("Authentication is required to delete the partition $(udisks2.device)");
+  message = N_("Authentication is required to delete the partition $(udisks2.drive)");
   if (udisks_block_get_hint_system (block))
     {
       action_id = "org.freedesktop.udisks2.modify-device-system";
index 8f0d3d9..b348e69 100644 (file)
@@ -326,10 +326,10 @@ handle_create_partition (UDisksPartitionTable   *table,
   /* Translators: Shown in authentication dialog when the user
    * requests creating a new partition.
    *
-   * Do not translate $(udisks2.device), it's a placeholder and
+   * Do not translate $(udisks2.drive), it's a placeholder and
    * will be replaced by the name of the drive/device in question
    */
-  message = N_("Authentication is required to create a partition on $(udisks2.device)");
+  message = N_("Authentication is required to create a partition on $(udisks2.drive)");
   if (udisks_block_get_hint_system (block))
     {
       action_id = "org.freedesktop.udisks2.modify-device-system";
index 8e46e80..cf50857 100644 (file)
@@ -179,10 +179,10 @@ handle_start (UDisksSwapspace        *swapspace,
                                                     /* Translators: Shown in authentication dialog when the user
                                                      * requests activating a swap device.
                                                      *
-                                                     * Do not translate $(udisks2.device), it's a placeholder and
+                                                     * Do not translate $(udisks2.drive), it's a placeholder and
                                                      * will be replaced by the name of the drive/device in question
                                                      */
-                                                    N_("Authentication is required to activate swapspace on $(udisks2.device)"),
+                                                    N_("Authentication is required to activate swapspace on $(udisks2.drive)"),
                                                     invocation))
     goto out;
 
@@ -253,10 +253,10 @@ handle_stop (UDisksSwapspace        *swapspace,
                                                     /* Translators: Shown in authentication dialog when the user
                                                      * requests deactivating a swap device.
                                                      *
-                                                     * Do not translate $(udisks2.device), it's a placeholder and
+                                                     * Do not translate $(udisks2.drive), it's a placeholder and
                                                      * will be replaced by the name of the drive/device in question
                                                      */
-                                                    N_("Authentication is required to deactivate swapspace on $(udisks2.device)"),
+                                                    N_("Authentication is required to deactivate swapspace on $(udisks2.drive)"),
                                                     invocation))
     goto out;