From f21de28b08809b264bafa2007524a2910c4c7ed5 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@collabora.com>
Date: Wed, 31 May 2017 18:32:05 +0100
Subject: [PATCH 4/4] spec: Document the canonical object path for the bus
 driver

Signed-off-by: Simon McVittie <smcv@collabora.com>
---
 doc/dbus-specification.xml | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 20f9f178..320a5c9a 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -5218,7 +5218,25 @@
       <title>Message Bus Messages</title>
       <para>
         The special message bus name <literal>org.freedesktop.DBus</literal>
-        responds to a number of additional messages.
+        responds to a number of additional messages at the object path
+        <literal>/org/freedesktop/DBus</literal>.
+        That object path is also used when emitting the
+        <xref linkend='bus-messages-name-owner-changed'/> signal.
+      </para>
+
+      <para>
+        For historical reasons, some of the methods in the
+        <literal>org.freedesktop.DBus</literal> interface are available
+        on multiple object paths. Message bus implementations should
+        accept method calls that were added before specification version
+        0.26 on any object path. Message bus implementations should
+        not accept newer method calls on unexpected object paths,
+        and as a security hardening measure, older method calls
+        that are security-sensitive may be rejected with the error
+        <literal>org.freedesktop.DBus.Error.AccessDenied</literal> when
+        called on an unexpected object path. Client software should send
+        all method calls to <literal>/org/freedesktop/DBus</literal>
+        instead of relying on this.
       </para>
 
       <sect3 id="bus-messages-hello">
-- 
2.11.0