~ubuntu-branches/ubuntu/oneiric/dbus/oneiric-security

����������</p></div></div></div></div></div><div><p class="releaseinfo">Version 0.15</p></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td align="left">Revision current</td><td align="left"><a class="ulink" href="http://cgit.freedesktop.org/dbus/dbus/log/doc/dbus-specification.xml" target="_top">commit log</a></td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.15</td><td align="left">3 November 2010</td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.14</td><td align="left">12 May 2010</td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.13</td><td align="left">23 Dezember 2009</td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.12</td><td align="left">7 November, 2006</td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.11</td><td align="left">6 February 2005</td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.10</td><td align="left">28 January 2005</td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.9</td><td align="left">7 Januar 2005</td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.8</td><td align="left">06 September 2003</td><td align="left"></td></tr><tr><td align="left" colspan="3">First released document.</td></tr></table></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#introduction">Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="#stability">Protocol and Specification Stability</a></span></dt></dl></dd><dt><span class="sect1"><a href="#message-protocol">Message Protocol</a></span></dt><dd><dl><dt><span class="sect2"><a href="#message-protocol-signatures">Type Signatures</a></span></dt><dt><span class="sect2"><a href="#message-protocol-marshaling">Marshaling (Wire Format)</a></span></dt><dt><span class="sect2"><a href="#message-protocol-messages">Message Format</a></span></dt><dt><span class="sect2"><a href="#message-protocol-names">Valid Names</a></span></dt><dt><span class="sect2"><a href="#message-protocol-types">Message Types</a></span></dt><dt><span class="sect2"><a href="#message-protocol-handling-invalid">Invalid Protocol and Spec Extensions</a></span></dt></dl></dd><dt><span class="sect1"><a href="#auth-protocol">Authentication Protocol</a></span></dt><dd><dl><dt><span class="sect2"><a href="#auth-protocol-overview">Protocol Overview</a></span></dt><dt><span class="sect2"><a href="#auth-nul-byte">Special credentials-passing nul byte</a></span></dt><dt><span class="sect2"><a href="#auth-command-auth">AUTH command</a></span></dt><dt><span class="sect2"><a href="#auth-command-cancel">CANCEL Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-data">DATA Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-begin">BEGIN Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-rejected">REJECTED Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-ok">OK Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-error">ERROR Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-negotiate-unix-fd">NEGOTIATE_UNIX_FD Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-agree-unix-fd">AGREE_UNIX_FD Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-future">Future Extensions</a></span></dt><dt><span class="sect2"><a href="#auth-examples">Authentication examples</a></span></dt><dt><span class="sect2"><a href="#auth-states">Authentication state diagrams</a></span></dt><dt><span class="sect2"><a href="#auth-mechanisms">Authentication mechanisms</a></span></dt></dl></dd><dt><span class="sect1"><a href="#addresses">Server Addresses</a></span></dt><dt><span class="sect1"><a href="#transports">Transports</a></span></dt><dd><dl><dt><span class="sect2"><a href="#transports-unix-domain-sockets">Unix Domain Sockets</a></span></dt><dt><span class="sect2"><a href="#transports-launchd">launchd</a></span></dt><dt><span class="sect2"><a href="#transports-tcp-sockets">TCP Sockets</a></span></dt><dt><span class="sect2"><a href="#transports-nonce-tcp-sockets">Nonce-secured TCP Sockets</a></span></dt></dl></dd><dt><span class="sect1"><a href="#meta-transports">Meta Transports</a></span></dt><dd><dl><dt><span class="sect2"><a href="#meta-transports-autolaunch">Autolaunch</a></span></dt></dl></dd><dt><span class="sect1"><a href="#naming-conventions">Naming Conventions</a></span></dt><dt><span class="sect1"><a href="#uuids">UUIDs</a></span></dt><dt><span class="sect1"><a href="#standard-interfaces">Standard Interfaces</a></span></dt><dd><dl><dt><span class="sect2"><a href="#standard-interfaces-peer"><code class="literal">org.freedesktop.DBus.Peer</code></a></span></dt><dt><span class="sect2"><a href="#standard-interfaces-introspectable"><code class="literal">org.freedesktop.DBus.Introspectable</code></a></span></dt><dt><span class="sect2"><a href="#standard-interfaces-properties"><code class="literal">org.freedesktop.DBus.Properties</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="#introspection-format">Introspection Data Format</a></span></dt><dt><span class="sect1"><a href="#message-bus">Message Bus Specification</a></span></dt><dd><dl><dt><span class="sect2"><a href="#message-bus-overview">Message Bus Overview</a></span></dt><dt><span class="sect2"><a href="#message-bus-names">Message Bus Names</a></span></dt><dt><span class="sect2"><a href="#message-bus-routing">Message Bus Message Routing</a></span></dt><dt><span class="sect2"><a href="#message-bus-starting-services">Message Bus Starting Services</a></span></dt><dt><span class="sect2"><a href="#message-bus-types">Well-known Message Bus Instances</a></span></dt><dt><span class="sect2"><a href="#message-bus-messages">Message Bus Messages</a></span></dt></dl></dd><dt><span class="glossary"><a href="#id367478">Glossary</a></span></dt></dl></div><div class="sect1" title="Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction"></a>Introduction</h2></div></div></div><p>

                  A variant type has a marshaled

                  <code class="literal">SIGNATURE</code> followed by a marshaled

                  value with the type given in the signature.  Unlike

                  a message signature, the variant signature can

                  contain only a single complete type.  So "i", "ai"

                  or "(ii)" is OK, but "ii" is not.  Use of variants may not

                  cause a total message depth to be larger than 64, including

                  other container types such as structures.

        </p><div class="figure"><a name="id362126"></a><p class="title"><b>Figure�1.�Example of successful magic cookie authentication</b></p><div class="figure-contents"><pre class="programlisting">

        </p><div class="figure"><a name="id362141"></a><p class="title"><b>Figure�2.�Example of finding out mechanisms then picking one</b></p><div class="figure-contents"><pre class="programlisting">

        </p><div class="figure"><a name="id362157"></a><p class="title"><b>Figure�3.�Example of client sends unknown command then falls back to regular auth</b></p><div class="figure-contents"><pre class="programlisting">

        </p><div class="figure"><a name="id362173"></a><p class="title"><b>Figure�4.�Example of server doesn't support initial auth mechanism</b></p><div class="figure-contents"><pre class="programlisting">

        </p><div class="figure"><a name="id362190"></a><p class="title"><b>Figure�5.�Example of wrong password or the like followed by successful retry</b></p><div class="figure-contents"><pre class="programlisting">

        </p><div class="figure"><a name="id362208"></a><p class="title"><b>Figure�6.�Example of skey cancelled and restarted</b></p><div class="figure-contents"><pre class="programlisting">

        </p><div class="figure"><a name="id362225"></a><p class="title"><b>Figure�7.�Example of successful magic cookie authentication with successful negotiation of Unix FD passing</b></p><div class="figure-contents"><pre class="programlisting">

        </p><div class="figure"><a name="id362242"></a><p class="title"><b>Figure�8.�Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing</b></p><div class="figure-contents"><pre class="programlisting">

                lock. ^{[<a name="id362953" href="#ftn.id362953" class="footnote">1</a>]}

      abstract namespace on linux), launchd, TCP/IP, and a debug/testing transport

      using in-process pipes. Future possible transports include one that

        </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td>path</td><td>(path)</td><td>path of the unix domain socket. If set, the "tmpdir" and "abstract" key must not be set.</td></tr><tr><td>tmpdir</td><td>(path)</td><td>temporary directory in which a socket file with a random file name starting with 'dbus-' will be created by the server. This key can only be used in server addresses, not in client addresses. If set, the "path" and "abstract" key must not be set.</td></tr><tr><td>abstract</td><td>(string)</td><td>unique string (path) in the abstract namespace. If set, the "path" or "tempdir" key must not be set.</td></tr></tbody></table></div></div></div><div class="sect2" title="launchd"><div class="titlepage"><div><div><h3 class="title"><a name="transports-launchd"></a>launchd</h3></div></div></div><p>

        launchd is a open-source server management system that replaces init, inetd

        and cron on Apple Mac OS X versions 10.4 and above. It provides a common session

        bus address for each user and deprecates the X11-enabled D-Bus launcher on OSX.

      </p><p>

        launchd allocates a socket and provides it with the unix path through the

        DBUS_LAUNCHD_SESSION_BUS_SOCKET variable in launchd's environment. Every process

        spawned by launchd (or dbus-daemon, if it was started by launchd) can access

        it through its environment.

        Other processes can query for the launchd socket by executing:

        $ launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET

        This is normally done by the D-Bus client library so doesn't have to be done

        manually.

      </p><p>

        launchd is not available on Microsoft Windows.

      </p><div class="sect3" title="Server Address Format"><div class="titlepage"><div><div><h4 class="title"><a name="transports-launchd-addresses"></a>Server Address Format</h4></div></div></div><p>

          launchd addresses are identified by the "launchd:" prefix

          and support the following key/value pairs:

        </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td>env</td><td>(environment variable)</td><td>path of the unix domain socket for the launchd created dbus-daemon.</td></tr></tbody></table></div></div></div><div class="sect2" title="TCP Sockets"><div class="titlepage"><div><div><h3 class="title"><a name="transports-tcp-sockets"></a>TCP Sockets</h3></div></div></div><p>

           </td></tr><tr><td>family</td><td>(string)</td><td>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</td></tr><tr><td>noncefile</td><td>(path)</td><td>file location containing the secret</td></tr></tbody></table></div></div></div></div><div class="sect1" title="Meta Transports"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="meta-transports"></a>Meta Transports</h2></div></div></div><p>

      Meta transports are a kind of transport with special enhancements or

      behavior. Currently available meta transports include: autolaunch

    </p><div class="sect2" title="Autolaunch"><div class="titlepage"><div><div><h3 class="title"><a name="meta-transports-autolaunch"></a>Autolaunch</h3></div></div></div><p>The autolaunch transport provides a way for dbus clients to autodetect

       a running dbus session bus and to autolaunch a session bus if not present.

     </p><div class="sect3" title="Server Address Format"><div class="titlepage"><div><div><h4 class="title"><a name="meta-transports-autolaunch-addresses"></a>Server Address Format</h4></div></div></div><p>

         Autolaunch addresses uses the "autolaunch:" prefix and support the

         following key/value pairs:

       </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td>scope</td><td>(string)</td><td>scope of autolaunch (Windows only)

            <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

               "*install-path" - limit session bus to dbus installation path.

               The dbus installation path is determined from the location of

               the shared dbus library. If the library is located in a 'bin'

               subdirectory the installation root is the directory above,

               otherwise the directory where the library lives is taken as

               installation root.

               </p><pre class="programlisting">

                   &lt;install-root&gt;/bin/[lib]dbus-1.dll

                   &lt;install-root&gt;/[lib]dbus-1.dll

               </pre><p>

              </p></li><li class="listitem"><p>

               "*user" - limit session bus to the recent user.

              </p></li><li class="listitem"><p>

               other values - specify dedicated session bus like "release",

               "debug" or other

              </p></li></ul></div>

           </td></tr></tbody></table></div></div><div class="sect3" title="Windows implementation"><div class="titlepage"><div><div><h4 class="title"><a name="meta-transports-autolaunch-windows-implementation"></a>Windows implementation</h4></div></div></div><p>

        On start, the server opens a platform specific transport, creates a mutex

        and a shared memory section containing the related session bus address.

        This mutex will be inspected by the dbus client library to detect a

        running dbus session bus. The access to the mutex and the shared memory

        section are protected by global locks.

      </p><p>

       In the recent implementation the autolaunch transport uses a tcp transport

       on localhost with a port choosen from the operating system. This detail may

       change in the future.

      </p><p>

        Disclaimer: The recent implementation is in an early state and may not

        work in all cirumstances and/or may have security issues. Because of this

        the implementation is not documentated yet.

      </p></div></div></div><div class="sect1" title="Naming Conventions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="naming-conventions"></a>Naming Conventions</h2></div></div></div><p>

        The message bus must send messages (of any type) with the

        <code class="literal">DESTINATION</code> field set to the specified recipient,

        regardless of whether the recipient has set up a match rule matching

        the message.

        is similar to that of <a class="ulink" href="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html" target="_top">desktop

        </p><div class="figure"><a name="id365470"></a><p class="title"><b>Figure�9.�Example service description file</b></p><div class="figure-contents"><pre class="programlisting">

        </p><p>The address of the login session message bus is given in the

        <code class="literal">DBUS_SESSION_BUS_ADDRESS</code> environment variable. If

        DBUS_SESSION_BUS_ADDRESS is not set, or if it's set to the string

        "autolaunch:", the system should use platform-specific methods of

        locating a running D-Bus session server, or starting one if a running

        instance cannot be found. Note that this mechanism is not recommended

        for attempting to determine if a daemon is running. It is inherently

        racy to attempt to make this determination, since the bus daemon may

        be started just before or just after the determination is made.

        Therefore, it is recommended that applications do not try to make this

        determination for their functionality purposes, and instead they

        should attempt to start the server.</p><div class="sect4" title="X Windowing System"><div class="titlepage"><div><div><h5 class="title"><a name="message-bus-types-login-x-windows"></a>X Windowing System</h5></div></div></div><p>

            For the X Windowing System, the application must locate the

            window owner of the selection represented by the atom formed by

            concatenating:

            </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>the literal string "_DBUS_SESSION_BUS_SELECTION_"</p></li><li class="listitem"><p>the current user's username</p></li><li class="listitem"><p>the literal character '_' (underscore)</p></li><li class="listitem"><p>the machine's ID</p></li></ul></div><p>

          </p><p>

            The following properties are defined for the window that owns

            this X selection:

            </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td>

                      <p>Atom</p>

                    </td><td>

                      <p>meaning</p>

                    </td></tr><tr><td>

                      <p>_DBUS_SESSION_BUS_ADDRESS</p>

                    </td><td>

                      <p>the actual address of the server socket</p>

                    </td></tr><tr><td>

                      <p>_DBUS_SESSION_BUS_PID</p>

                    </td><td>

                      <p>the PID of the server process</p>

                    </td></tr></tbody></table></div><p>

          </p><p>

            At least the _DBUS_SESSION_BUS_ADDRESS property MUST be

            present in this window.

          </p><p>

            If the X selection cannot be located or if reading the

            properties from the window fails, the implementation MUST conclude

            that there is no D-Bus server running and proceed to start a new

            server. (See below on concurrency issues)

          </p><p>

            Failure to connect to the D-Bus server address thus obtained

            MUST be treated as a fatal connection error and should be reported

            to the application.

          </p><p>

            As an alternative, an implementation MAY find the information

            in the following file located in the current user's home directory,

            in subdirectory .dbus/session-bus/:

            </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>the machine's ID</p></li><li class="listitem"><p>the literal character '-' (dash)</p></li><li class="listitem"><p>the X display without the screen number, with the

                following prefixes removed, if present: ":", "localhost:"

                ."localhost.localdomain:". That is, a display of

                "localhost:10.0" produces just the number "10"</p></li></ul></div><p>

          </p><p>

            The contents of this file NAME=value assignment pairs and

            lines starting with # are comments (no comments are allowed

            otherwise). The following variable names are defined:

            </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td>

                      <p>Variable</p>

                    </td><td>

                      <p>meaning</p>

                    </td></tr><tr><td>

                      <p>DBUS_SESSION_BUS_ADDRESS</p>

                    </td><td>

                      <p>the actual address of the server socket</p>

                    </td></tr><tr><td>

                      <p>DBUS_SESSION_BUS_PID</p>

                    </td><td>

                      <p>the PID of the server process</p>

                    </td></tr><tr><td>

                      <p>DBUS_SESSION_BUS_WINDOWID</p>

                    </td><td>

                      <p>the window ID</p>

                    </td></tr></tbody></table></div><p>

          </p><p>

            At least the DBUS_SESSION_BUS_ADDRESS variable MUST be present

            in this file.

          </p><p>

            Failure to open this file MUST be interpreted as absence of a

            running server. Therefore, the implementation MUST proceed to

            attempting to launch a new bus server if the file cannot be

            opened.

          </p><p>

            However, success in opening this file MUST NOT lead to the

            conclusion that the server is running. Thus, a failure to connect to

            the bus address obtained by the alternative method MUST NOT be

            considered a fatal error. If the connection cannot be established,

            the implementation MUST proceed to check the X selection settings or

            to start the server on its own.

          </p><p>

            If the implementation concludes that the D-Bus server is not

            running it MUST attempt to start a new server and it MUST also

            ensure that the daemon started as an effect of the "autolaunch"

            mechanism provides the lookup mechanisms described above, so

            subsequent calls can locate the newly started server. The

            implementation MUST also ensure that if two or more concurrent

            initiations happen, only one server remains running and all other

            initiations are able to obtain the address of this server and

            connect to it. In other words, the implementation MUST ensure that

            the X selection is not present when it attempts to set it, without

            allowing another process to set the selection between the

            verification and the setting (e.g., by using XGrabServer /

            XungrabServer).

          </p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="id366057"></a></h5></div></div></div><p>

            [FIXME specify location of .service files, probably using

            DESKTOP_DIRS etc. from basedir specification, though login session

            bus is not really desktop-specific]

          </p></div></div><div class="sect3" title="System message bus"><div class="titlepage"><div><div><h4 class="title"><a name="message-bus-types-system"></a>System message bus</h4></div></div></div><p>

          ^{[<a name="id366098" href="#ftn.id366098" class="footnote">2</a>]}

        </p></div></div></div><div class="glossary" title="Glossary"><div class="titlepage"><div><div><h2 class="title"><a name="id367478"></a>Glossary</h2></div></div></div><p>

        </p></dd></dl></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p>^{[<a name="ftn.id362953" href="#id362953" class="para">1</a>]}Lockfiles are used instead of real file

                filesystems.</p></div><div class="footnote"><p>^{[<a name="ftn.id366098" href="#id366098" class="para">2</a>]}