From: Katariina Lounento <katariina.lounento@vaisala.com>
Date: Mon, 9 Dec 2024 14:09:13 +0000 (+0200)
Subject: man: document unprivileged is not for reading properties
X-Git-Tag: v258-rc1~1911
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=3ca09aa4dd57327989eceb1298754601046ac041;p=thirdparty%2Fsystemd.git

man: document unprivileged is not for reading properties

Document the fact that read-only properties may not have the flag
SD_BUS_VTABLE_UNPRIVILEGED as that is not obvious especially given the
flag is accepted for writable properties.

Based on the check in `add_object_vtable_internal` called by
`sd_bus_add_object_vtable` (as of the current tip of the main branch
f7f5ba019206cacd486b0892fec76f70f525e04d):

    case _SD_BUS_VTABLE_PROPERTY: {
            [...]
            if ([...] ||
                [...]
                (v->flags & SD_BUS_VTABLE_UNPRIVILEGED && v->type == _SD_BUS_VTABLE_PROPERTY)) {
                    r = -EINVAL;
                    goto fail;
            }

(where `_SD_BUS_VTABLE_PROPERTY` means read-only property whereas
`_SD_BUS_VTABLE_WRITABLE_PROPERTY` maps to writable property).

This was implemented in the commit
adacb9575a09981fcf11279f2f661e3fc21e58ff ("bus: introduce "trusted" bus
concept and encode access control in object vtables") where
`SD_BUS_VTABLE_UNPRIVILEGED` was introduced:

    Writable properties are also subject to SD_BUS_VTABLE_UNPRIVILEGED
    and SD_BUS_VTABLE_CAPABILITY() for controlling write access to them.
    Note however that read access is unrestricted, as PropertiesChanged
    messages might send out the values anyway as an unrestricted
    broadcast.
---

diff --git a/man/sd_bus_add_object.xml b/man/sd_bus_add_object.xml
index 4d14a7e7316..5572f421fb6 100644
--- a/man/sd_bus_add_object.xml
+++ b/man/sd_bus_add_object.xml
@@ -589,6 +589,9 @@
           <constant>org.freedesktop.systemd1.Privileged</constant> annotation with value
           <literal>true</literal> will be shown in introspection data.</para>
 
+          <para><constant>SD_BUS_VTABLE_UNPRIVILEGED</constant> may not be applied to read-only properties,
+          but read access (to both read-only and writable properties) is always unrestricted.</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