diff options
author | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2022-03-04 15:41:31 +0100 |
---|---|---|
committer | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2022-03-04 15:43:18 +0100 |
commit | b4e7d7555e6266ff566a17eb5f616b365771028f (patch) | |
tree | 3b808de557295e3417c9cb6b5345f823e2d2fb56 | |
parent | 3c080282e928a7edfcdb74feb2139ef1ac6f2ad0 (diff) | |
download | systemd-b4e7d7555e6266ff566a17eb5f616b365771028f.tar.gz |
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.
-rw-r--r-- | man/rules/meson.build | 1 | ||||
-rw-r--r-- | man/sd_bus_add_object.xml | 61 | ||||
-rw-r--r-- | src/libsystemd/sd-bus/bus-objects.c | 8 |
3 files changed, 55 insertions, 15 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> diff --git a/src/libsystemd/sd-bus/bus-objects.c b/src/libsystemd/sd-bus/bus-objects.c index 40158a7326..b852475419 100644 --- 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); |