From f03cd71c1ad16a35548b722e4038ef456834dc0e Mon Sep 17 00:00:00 2001
From: Simon McVittie <simon.mcvittie@collabora.co.uk>
Date: Wed, 9 Nov 2016 17:53:02 +0000
Subject: [PATCH 8/9] Spec: document AppArmor mediation of auto-starting

Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
---
 doc/dbus-specification.xml | 66 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 39795fe..b182a5e 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -5181,6 +5181,72 @@
           service is started by systemd during boot.
         </para>
       </sect3>
+
+      <sect3 id="message-bus-starting-services-apparmor">
+        <title>Mediating Activation with AppArmor</title>
+
+        <para>
+          Please refer to AppArmor documentation for general information on
+          AppArmor, and how it mediates D-Bus messages when used in conjunction
+          with a kernel and <literal>dbus-daemon</literal> that support this.
+        </para>
+
+        <para>
+          In recent versions of the reference <literal>dbus-daemon</literal>,
+          AppArmor policy rules of type <literal>dbus send</literal>
+          are also used to control auto-starting: if a message is sent to
+          the well-known name of an activatable service, the
+          <literal>dbus-daemon</literal> will attempt to determine whether
+          it would deliver the message to that service
+          <emphasis>before</emphasis>auto-starting it, by making some
+          assumptions about the resulting process's credentials.
+          If it does proceed with auto-starting, when the service appears, the
+          <literal>dbus-daemon</literal> repeats the policy check (with
+          the service's true credentials, which might not be identical)
+          before delivering the message.
+        </para>
+
+        <para>
+          To support this process, service description files may contain a
+          <literal>AssumedAppArmorLabel</literal> key. Its value is the name
+          of an AppArmor label, for example
+          <literal>/usr/sbin/mydaemon</literal>.
+          If present, AppArmor mediation of messages that auto-start a
+          service will decide whether to allow auto-starting to occur based
+          on the assumption that the activated service will be confined
+          under the specified label; in particular, rules of the form
+          <literal>dbus send peer=(label=/usr/sbin/mydaemon)</literal> or
+          <literal>deny dbus send peer=(label=/usr/sbin/mydaemon)</literal>
+          will match it, allowing or denying as appropriate.
+        </para>
+
+        <para>
+          Otherwise, AppArmor mediation of messages that auto-start a
+          service will decide whether to allow auto-starting to occur
+          without specifying any particular label. In particular, any rule of
+          the form
+          <literal>dbus send peer=(label=X)</literal> (for any value of X)
+          will not allow the auto-start, and any rule of the form
+          <literal>deny dbus send peer=(label=X)</literal>
+          will not deny it.
+        </para>
+
+        <para>
+          Rules of type <literal>dbus receive</literal> are not checked
+          when deciding whether to allow auto-starting; they are only checked
+          against the service's profile after the service has started, when
+          deciding whether to deliver the message that caused the auto-starting
+          operation.
+        </para>
+
+        <para>
+          Explicit activation via
+          <xref linkend="bus-messages-start-service-by-name"/> is not currently
+          affected by this mediation: if a confined process is to be prevented
+          from starting arbitrary services, then it must not be allowed to call
+          that method.
+        </para>
+      </sect3>
     </sect2>
 
     <sect2 id="message-bus-types">
-- 
2.10.2