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.

2 files changed, 52 insertions, 10 deletions

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 @@
     <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>
@@ -122,6 +123,10 @@
       </funcprototype>
 
       <para>
+        <constant>SD_BUS_VTABLE_CAPABILITY(<replaceable>capability</replaceable>)</constant>
+      </para>
+
+      <para>
         <constant>SD_BUS_VTABLE_START(<replaceable>flags</replaceable>)</constant>
       </para>
       <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>
@@ -495,14 +502,6 @@
         </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>
 
           <listitem><para>Mark this vtable entry as a method that will not return a reply using the
@@ -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>