From 9428df3740e668ab822cdb33d391d06ac9a0dd30 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@collabora.com>
Date: Fri, 20 Oct 2023 16:30:26 +0100
Subject: [PATCH] specification: Describe the trust model for container info

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

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index a61218cd..c20a6bbe 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -7632,8 +7632,6 @@
           Metadata from the first three arguments is stored by the message
           bus, but not interpreted; software that interacts with the
           container manager can use this metadata.
-          <!-- TODO: Clarify how the trust model works here. See
-          <https://bugs.freedesktop.org/show_bug.cgi?id=100344#c15>-->
           The method call may fail with the error
           <literal>org.freedesktop.DBus.Error.LimitsExceeded</literal>
           if the caller provides more metadata than the message bus
@@ -7857,6 +7855,7 @@
                     The opaque object path that was returned from the
                     <literal>AddServer</literal> method, identifying a
                     container instance.
+                    This output parameter is produced by the message bus.
                   </entry>
                 </row>
                 <row>
@@ -7868,6 +7867,8 @@
                     documented for
                     <link linkend="bus-messages-get-connection-credentials"
                       >GetConnectionCredentials</link>.
+                    This output parameter is produced by the message bus
+                    and is appropriate to use in trust decisions.
                   </entry>
                 </row>
                 <row>
@@ -7879,6 +7880,8 @@
                     <literal>AddServer</literal> method, such as
                     <literal>org.flatpak</literal> or
                     <literal>io.snapcraft</literal>.
+                    This output parameter is controlled by the creator
+                    of the container instance.
                   </entry>
                 </row>
                 <row>
@@ -7888,6 +7891,8 @@
                     Some unique identifier for an application or container,
                     whose meaning is defined by the maintainers of the
                     container type.
+                    This output parameter is controlled by the creator
+                    of the container instance.
                   </entry>
                 </row>
                 <row>
@@ -7897,6 +7902,8 @@
                     Metadata describing the application or container, with the
                     keys and values defined by the maintainers of the container
                     type.
+                    This output parameter is controlled by the creator
+                    of the container instance.
                   </entry>
                 </row>
               </tbody>
@@ -7914,6 +7921,15 @@
           <literal>org.freedesktop.DBus.Error.NameHasNoOwner</literal> error
           is returned instead.
         </para>
+        <para>
+          Several of the output parameters are controlled by the creator of
+          the container instance.
+          On a bus that accepts connections from multiple clients at
+          different privilege levels, it is not appropriate to trust those
+          output parameters or use them in trust decisions unless the
+          process identified by the <literal>creator</literal> parameter
+          is trusted.
+        </para>
       </sect3>
 
       <sect3 id="bus-messages-containers1-get-instance-info">
@@ -7956,6 +7972,8 @@
                     documented for
                     <link linkend="bus-messages-get-connection-credentials"
                       >GetConnectionCredentials</link>.
+                    This output parameter is produced by the message bus
+                    and is appropriate to use in trust decisions.
                   </entry>
                 </row>
                 <row>
@@ -7967,6 +7985,8 @@
                     <literal>AddServer</literal> method, such as
                     <literal>org.flatpak</literal> or
                     <literal>io.snapcraft</literal>.
+                    This output parameter is controlled by the creator
+                    of the container instance.
                   </entry>
                 </row>
                 <row>
@@ -7976,6 +7996,8 @@
                     Some unique identifier for an application or container,
                     whose meaning is defined by the maintainers of the
                     container type.
+                    This output parameter is controlled by the creator
+                    of the container instance.
                   </entry>
                 </row>
                 <row>
@@ -7985,6 +8007,8 @@
                     Metadata describing the application or container, with the
                     keys and values defined by the maintainers of the container
                     type.
+                    This output parameter is controlled by the creator
+                    of the container instance.
                   </entry>
                 </row>
               </tbody>
@@ -7999,6 +8023,12 @@
           <literal>org.freedesktop.DBus.Error.NotContainer</literal> error
           is returned.
         </para>
+        <para>
+          Several of the output parameters are controlled by the creator of
+          the container instance.
+          See <xref linkend="bus-messages-containers1-get-connection-instance"/>
+          for more details.
+        </para>
       </sect3>
 
       <sect3 id="bus-messages-containers1-instance-removed">