doc: document the new broadcast behaviour

Currently we do not check senders when doing broadcasts.

In order to block the following scenarios, we need to improve the
broadcast logic and check the policy rules before allowing broadcast
messages.

* Since unprivileged users can't use unicast to communicate unless a
  policy that permits this was uploaded, follow and block broadcast
  communications between unprivileged users unless a policy rule that
  allows this is satisfied.

* We do not want unprivileged connections that do not own names to
  send signals to privileged connections.

* We do not want unprivileged connections that do not own names to
  send signals to other connections that might own names.

So to achieve this and to allow broadcast messages for legitimate
scenarios, we follow the same unicast checks, and we introduce one
implicit rule to allow broadcast from connections that own names.

1) Check custom endpoint policies, if it allows the TALK continue,
otherwise block.

2) If the sender connection is a privileged connection, allow broadcast.

3) If the sender and receiver run under the same user, allow broadcast.

4) If the sender connection owns names on the bus and if the
   destination connection do not own names, allow broadcast.
   Otherwise check bus policy rules for these two reasons:

   * anonymous connections should not signal to other connections.
   * receivers that own names may have policies that block the TALK
     access, so do not bypass this.

   This openes the case where connections that own names may gain TALK
   access to other connections on the bus through broadcast! Yes but
   since this is the intended behaviour of signals we can't do
   otherwise. Of course as stated above if the destination owns names
   then broadcasts are subject to policy rules (we do not bypass policy
   rules).

5) If the policy rules of the default endpoint block the TALK access,
then block broadcasts, otherwise allow it.

These are the same rules that apply to TALK access and unicast checks,
the only exception is rule 4) that was instroduced to allow services to
signal on the bus.

Signed-off-by: Djalal Harouni <tixxdz@opendz.org>

diff --git a/kdbus.txt b/kdbus.txt
index 3aa6f13e6478dedf4511dcb71a4aac321f7c2018..b5abcce22a781a1f482001b9dd280e39b8e26d44 100644 (file)
--- a/kdbus.txt
+++ b/kdbus.txt
@@ -1103,7 +1103,11 @@ A message addressed at the connection ID KDBUS_DST_ID_BROADCAST (~0ULL) is a
 broadcast message, delivered to all connected peers which installed a rule to
 match certain properties of the message. Without any rules installed in the
 connection, no broadcast message or kernel-side notifications will be delivered
-to the connection.
+to the connection. Broadcast messages are subject to policy rules and TALK
+access checks.
+
+See section 11 for details on policies, and section 11.5 for more
+details on implicit policies.
 
 Matches for messages from other connections (not kernel notifications) are
 implemented as bloom filters. The sender adds certain properties of the message
@@ -1410,6 +1414,11 @@ demand) or for a custom endpoint (which always has one), each one is consulted
 during name registry listing, name owning or message delivery. If either one
 fails, the operation is failed with -EPERM.
 
+For best practices, connections that own names with a restricted TALK
+access should not install matches. This avoids cases where the sent
+message may pass the bloom filter due to false-positives and may also
+satisfy the policy rules.
+
 11.5 Implicit policies
 ----------------------
 
@@ -1419,14 +1428,18 @@ enforced. On default endpoints, the following set is enforced:
   * Privileged connections always override any installed policy. Those
     connections could easily install their own policies, so there is no
     reason to enforce installed policies.
-  * Connections can always talk to connections of the same user.
+  * Connections can always talk to connections of the same user. This
+    includes broadcast messages.
+  * Connections that own names might send broadcast messages to other
+    connections that belong to a different user, but only if that
+    destination connection does not own any name.
 
 Custom endpoints have stricter policies. The following rules apply:
 
   * Policy rules are always enforced, even if the connection is a privileged
     connection.
   * Policy rules are always enforced for TALK access, even if both ends are
-    running under the same user.
+    running under the same user. This includes broadcast messages.
   * To restrict the set of names that can be seen, endpoint policies can
     install "SEE" policies.