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.

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 793010f75f4e7c6cd9ccc4de8af0eec7247054db..2e334ff331d0d2fc90241c8ffbb37594298d1458 100644 (file)
--- 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 dcf9377ffdd813ddd9356186eb90e9513a151af9..3249b7f98de90a2e711e7a8a6137b4cb89eae40e 100644 (file)
--- a/man/sd_bus_add_object.xml
+++ b/man/sd_bus_add_object.xml
@@ -22,6 +22,7 @@
     <refname>sd_bus_add_object_vtable</refname>
     <refname>sd_bus_add_fallback_vtable</refname>
     <refname>sd_bus_add_filter</refname>
+    <refname>SD_BUS_VTABLE_CAPABILITY</refname>
     <refname>SD_BUS_VTABLE_START</refname>
     <refname>SD_BUS_VTABLE_END</refname>
     <refname>SD_BUS_METHOD_WITH_NAMES_OFFSET</refname>
@@ -121,6 +122,10 @@
         <paramdef>void *<parameter>userdata</parameter></paramdef>
       </funcprototype>
 
+      <para>
+        <constant>SD_BUS_VTABLE_CAPABILITY(<replaceable>capability</replaceable>)</constant>
+      </para>
+
       <para>
         <constant>SD_BUS_VTABLE_START(<replaceable>flags</replaceable>)</constant>
       </para>
@@ -334,10 +339,12 @@
 
       <variablelist>
         <varlistentry>
-          <term><constant>SD_BUS_VTABLE_START()</constant></term>
+          <term><constant>SD_BUS_VTABLE_START(<replaceable>flags</replaceable>)</constant></term>
           <term><constant>SD_BUS_VTABLE_END</constant></term>
 
-          <listitem><para>Those must always be the first and last element.</para></listitem>
+          <listitem><para>Those must always be the first and last element. The
+          <replaceable>flags</replaceable> parameter can be used to set attributes that apply to the whole
+          array; see the "Flags" section below.</para></listitem>
         </varlistentry>
 
         <varlistentry>
@@ -494,14 +501,6 @@
           hidden.</para></listitem>
         </varlistentry>
 
-        <varlistentry>
-          <term><constant>SD_BUS_VTABLE_UNPRIVILEGED</constant></term>
-
-          <listitem><para>Mark this vtable entry as unprivileged. If not specified, the
-          <constant>org.freedesktop.systemd1.Privileged</constant> annotation with value
-          <literal>true</literal> will be shown in introspection data.</para></listitem>
-        </varlistentry>
-
         <varlistentry>
           <term><constant>SD_BUS_VTABLE_METHOD_NO_REPLY</constant></term>
 
@@ -558,6 +557,48 @@
           passed directly, converted to a pointer, without taking the user data pointer specified during
           vtable registration into account.</para></listitem>
         </varlistentry>
+
+        <varlistentry>
+          <term><constant>SD_BUS_VTABLE_CAPABILITY(<replaceable>capability</replaceable>)</constant></term>
+
+          <listitem><para>Access to this vtable entry will be allowed if the calling proccess has the
+          capability <replaceable>capability</replaceable>, as described in
+          <citerefentry><refentrytitle>sd_bus_query_sender_privilege</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+          If used for <constant>SD_BUS_VTABLE_START()</constant>, provides a default for all entries in the
+          array. If not specified, either for an individual entry or the whole array,
+          <constant>CAP_SYS_ADMIN</constant> is checked by default. See <citerefentry
+          project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+          for information about capabilities.</para>
+
+          <para>Note that vtable entries may be marked as unprivileged and the whole bus may be marked as
+          trusted, see the discussion of <constant>SD_BUS_VTABLE_UNPRIVILEGED</constant> below.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>SD_BUS_VTABLE_UNPRIVILEGED</constant></term>
+
+          <listitem><para>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 <ulink
+          url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>.</para>
+
+          <para>The whole bus may be marked as trusted, in which case annotations at the entry level are
+          ignored, see
+          <citerefentry><refentrytitle>sd_bus_set_trusted</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+          </para>
+
+          <para>When <emphasis>not</emphasis> specified, the
+          <constant>org.freedesktop.systemd1.Privileged</constant> annotation with value
+          <literal>true</literal> will be shown in introspection data.</para>
+
+          <para>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
+          <citerefentry project='man-pages'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+          </para></listitem>
+        </varlistentry>
       </variablelist>
     </refsect2>
   </refsect1>

diff --git a/src/libsystemd/sd-bus/bus-objects.c b/src/libsystemd/sd-bus/bus-objects.c
index 40158a732601cacaa56369113ee36449bbcbc3ba..b8524754191062ac641018589ddde2370fb1c0a2 100644 (file)
--- a/src/libsystemd/sd-bus/bus-objects.c
+++ b/src/libsystemd/sd-bus/bus-objects.c
@@ -315,11 +315,9 @@ static int check_access(sd_bus *bus, sd_bus_message *m, struct vtable_member *c,
         if (c->vtable->flags & SD_BUS_VTABLE_UNPRIVILEGED)
                 return 0;
 
-        /* Check have the caller has the requested capability
-         * set. Note that the flags value contains the capability
-         * number plus one, which we need to subtract here. We do this
-         * so that we have 0 as special value for "default
-         * capability". */
+        /* Check that the caller has the requested capability set. Note that the flags value contains the
+         * capability number plus one, which we need to subtract here. We do this so that we have 0 as
+         * special value for the default. */
         cap = CAPABILITY_SHIFT(c->vtable->flags);
         if (cap == 0)
                 cap = CAPABILITY_SHIFT(c->parent->vtable[0].flags);