From b4e7d7555e6266ff566a17eb5f616b365771028f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 4 Mar 2022 15:41:31 +0100 Subject: man: describe capability checks on the bus A description of SD_BUS_VTABLE_CAPABILITY is added, and the discussion on SD_BUS_VTABLE_UNPRIVILEGED in expanded. I think it would be nice to add longer description of how access is checked (maybe in sd-bus(3)), but I'm leaving that for later. I think the text that was added here describes everything, even if tersely. Fixes #21882. --- man/rules/meson.build | 1 + man/sd_bus_add_object.xml | 61 +++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 52 insertions(+), 10 deletions(-) (limited to 'man') diff --git a/man/rules/meson.build b/man/rules/meson.build index 793010f75f..2e334ff331 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -158,6 +158,7 @@ manpages = [ 'SD_BUS_PROPERTY', 'SD_BUS_SIGNAL', 'SD_BUS_SIGNAL_WITH_NAMES', + 'SD_BUS_VTABLE_CAPABILITY', 'SD_BUS_VTABLE_END', 'SD_BUS_VTABLE_START', 'SD_BUS_WRITABLE_PROPERTY', diff --git a/man/sd_bus_add_object.xml b/man/sd_bus_add_object.xml index dcf9377ffd..3249b7f98d 100644 --- a/man/sd_bus_add_object.xml +++ b/man/sd_bus_add_object.xml @@ -22,6 +22,7 @@ sd_bus_add_object_vtable sd_bus_add_fallback_vtable sd_bus_add_filter + SD_BUS_VTABLE_CAPABILITY SD_BUS_VTABLE_START SD_BUS_VTABLE_END SD_BUS_METHOD_WITH_NAMES_OFFSET @@ -121,6 +122,10 @@ void *userdata + + SD_BUS_VTABLE_CAPABILITY(capability) + + SD_BUS_VTABLE_START(flags) @@ -334,10 +339,12 @@ - SD_BUS_VTABLE_START() + SD_BUS_VTABLE_START(flags) SD_BUS_VTABLE_END - Those must always be the first and last element. + Those must always be the first and last element. The + flags parameter can be used to set attributes that apply to the whole + array; see the "Flags" section below. @@ -494,14 +501,6 @@ hidden. - - SD_BUS_VTABLE_UNPRIVILEGED - - Mark this vtable entry as unprivileged. If not specified, the - org.freedesktop.systemd1.Privileged annotation with value - true will be shown in introspection data. - - SD_BUS_VTABLE_METHOD_NO_REPLY @@ -558,6 +557,48 @@ passed directly, converted to a pointer, without taking the user data pointer specified during vtable registration into account. + + + SD_BUS_VTABLE_CAPABILITY(capability) + + Access to this vtable entry will be allowed if the calling proccess has the + capability capability, as described in + sd_bus_query_sender_privilege3. + If used for SD_BUS_VTABLE_START(), provides a default for all entries in the + array. If not specified, either for an individual entry or the whole array, + CAP_SYS_ADMIN is checked by default. See capabilities7 + for information about capabilities. + + Note that vtable entries may be marked as unprivileged and the whole bus may be marked as + trusted, see the discussion of SD_BUS_VTABLE_UNPRIVILEGED below. + + + + + SD_BUS_VTABLE_UNPRIVILEGED + + Mark this vtable entry as unprivileged. Access to privileged entries is limited to + users with appropriate capabilities as described above. In practice many vtable entries are marked + as unprivileged, and either are open to everyone, or the decision whether to allow access is taken + later, e.g. by delegating to polkit. + + The whole bus may be marked as trusted, in which case annotations at the entry level are + ignored, see + sd_bus_set_trusted3. + + + When not specified, the + org.freedesktop.systemd1.Privileged annotation with value + true will be shown in introspection data. + + Note that this page describes checks implemented in the D-Bus client. The D-Bus server has an + additional policy that may permit or deny connections, see + "CONFIGURATION FILE" in + dbus-daemon1. + + -- cgit v1.2.1