From 5dbb35efcae39b507293f4181dca8d50766fe5d3 Mon Sep 17 00:00:00 2001 From: David Zeuthen Date: Mon, 4 Jun 2012 12:24:42 -0400 Subject: [PATCH] Move table with polkit variables to the "Authorization Checks" chapter Signed-off-by: David Zeuthen --- doc/udisks2-docs.xml | 59 +++++++++++++++++++++++++++++++++++++------ src/udisksdaemonutil.c | 68 +++++++++++++------------------------------------- 2 files changed, 69 insertions(+), 58 deletions(-) diff --git a/doc/udisks2-docs.xml b/doc/udisks2-docs.xml index 2a73e00..bbc27f1 100644 --- a/doc/udisks2-docs.xml +++ b/doc/udisks2-docs.xml @@ -135,10 +135,8 @@ calling user to be sufficiently authorized. Whether the user is authorized is checked using polkit - and the administrator can configure polkit's - local authority (but note that the system may be - using another polkit authority implementation). + allowing the administrator to configure fine-grained permissions via + polkit authorization rules. There is not necessarily a one-to-one relationship between @@ -174,8 +172,8 @@ 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, .pkla files may need to be - updated to match an updated policy. + example, polkit authorization rules may need to be updated + to match an updated policy. See for the @@ -184,10 +182,57 @@ for request). For example, a polkit authorization rule for any of the org.freedesktop.udisks2.filesystem-mount* - actions can use the udisks2.device + actions can use the device_file variable to determine if the caller is authorized to mount a specific device. + + + Known variables + + + + key + value + + + + + device_file + If the object is a block device, this property is set to the value of the Block:PreferredDevice property. If set, this is guaranteed to be a device file, for example /dev/vg_lucifer/lv_root or /dev/sda1. If the object is not a block device, this is not set. + + + drive + Like device_file, but if the object is also a drive, this variable includes Vital Product Data about the drive such as the vendor and model identifiers (if available), for example INTEL SSDSA2MH080G1GC (/dev/sda1). Otherwise is just set to the same value as device_file. If the object is not a block device, this is not set (it is however set if the object is a block device but not a drive). + + + drive.wwn + If the object is a drive, this is set to the World Wide Name (See Drive:WWN). If the object is not a drive, this is not set. + + + drive.serial + If the object is a drive, this is set to the serial number (See Drive:Serial). If the object is not a drive, this is not set. + + + drive.vendor + If the object is a drive, this is set to the vendor (See Drive:Vendor). If the object is not a drive, this is not set. + + + drive.model + If the object is a drive, this is set to the model (See Drive:Model). If the object is not a drive, this is not set. + + + drive.revision + If the object is a drive, this is set to the firmware revision (See Drive:Revision). If the object is not a drive, this is not set. + + + drive.removable + If the object is a drive that is considered removable, set to true (See Drive:Removable). If the object is not a drive, this is not set. + + + +
+ For reference, the polkit actions defined by udisks &version; are included here: diff --git a/src/udisksdaemonutil.c b/src/udisksdaemonutil.c index a6287aa..1e8d064 100644 --- a/src/udisksdaemonutil.c +++ b/src/udisksdaemonutil.c @@ -414,7 +414,7 @@ _safe_polkit_details_insert (PolkitDetails *details, const gchar *key, const gch * @daemon: A #UDisksDaemon. * @object: (allow-none): The #GDBusObject that the call is on or %NULL. * @action_id: The action id to check for. - * @options: (allow-none): A #GVariant to check for the auth.no_user_interaction option or %NULL. + * @options: (allow-none): A #GVariant to check for the auth.no_user_interaction option or %NULL. * @message: The message to convey (use N_). * @invocation: The invocation to check for. * @@ -424,58 +424,24 @@ _safe_polkit_details_insert (PolkitDetails *details, const gchar *key, const gch * authorized, the appropriate error is already returned to the caller * via @invocation. * - * The calling thread is blocked for the duration of the - * authentication which may be a very long time unless - * @auth_no_user_interaction is %TRUE. + * The calling thread is blocked for the duration of the authorization + * check which could be a very long time since it may involve + * presenting an authentication dialog and having a human user use + * it. If auth.no_user_interaction in @options is %TRUE + * no authentication dialog will be presented and the check is not + * expected to take a long time. * * See for the variables that - * can be used in @message. - * - * - * Known polkit details variables - * - * - * - * key - * value - * - * - * - * - * device_file - * If @object has a #UDisksBlock interface or #UDisksDrive interface, this property is set to the value of the Block:PreferredDevice property. If set, this is guaranteed to be a device file. - * - * - * drive - * Like device_file, 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 device_file. - * - * - * drive.wwn - * If @object has a #UDisksDrive, this is set to the World Wide Name (WWN). - * - * - * drive.serial - * If @object has a #UDisksDrive, this is set to the serial number (Serial). - * - * - * drive.vendor - * If @object has a #UDisksDrive, this is set to the vendor (Vendor). - * - * - * drive.model - * If @object has a #UDisksDrive, this is set to the model (Model). - * - * - * drive.revision - * If @object has a #UDisksDrive, this is set to the firmware revision (Revision). - * - * - * drive.removable - * If @object has a #UDisksDrive and drive is considered removable, set to true (Removable). - * - * - * - *
+ * can be used in @message but note that not all variables can be used + * in all checks. For example, any check involving a #UDisksDrive or a + * #UDisksBlock object can safely include the fragment + * $(drive) since it will always expand to the name of + * the drive, e.g. INTEL SSDSA2MH080G1GC (/dev/sda1) or + * the block device file e.g. /dev/vg_lucifer/lv_root + * or /dev/sda1. However this won't work for operations + * that isn't on a drive or block device, for example calls on the + * Manager + * object. * * Returns: %TRUE if caller is authorized, %FALSE if not. */ -- 2.7.4