-<?xml version="1.0" standalone="no"?>
+<?xml version="1.0" standalone="no" ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
[
<article id="index">
<articleinfo>
<title>D-Bus Specification</title>
- <releaseinfo>Version 0.12</releaseinfo>
- <date>7 November 2006</date>
+ <releaseinfo>Version 0.13</releaseinfo>
+ <date>23 Dezember 2009</date>
<authorgroup>
<author>
<firstname>Havoc</firstname>
<entry><literal>DICT_ENTRY</literal></entry>
<entry>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </entry>
<entry>Entry in a dict or map (array of key-value pairs)</entry>
+ </row><row>
+ <entry><literal>UNIX_FD</literal></entry>
+ <entry>104 (ASCII 'h')</entry>
+ <entry>Unix file descriptor</entry>
</row>
</tbody>
</tgroup>
<entry>
8
</entry>
+ </row><row>
+ <entry><literal>UNIX_FD</literal></entry>
+ <entry>32-bit unsigned integer in the message's byte
+ order. The actual file descriptors need to be
+ transferred out-of-band via some platform specific
+ mechanism. On the wire, values of this type store the index to the
+ file descriptor in the array of file descriptors that
+ accompany the message.</entry>
+ <entry>4</entry>
</row>
</tbody>
</tgroup>
If omitted, it is assumed to be the
empty signature "" (i.e. the body must be 0-length).</entry>
</row>
+ <row>
+ <entry><literal>UNIX_FDS</literal></entry>
+ <entry>9</entry>
+ <entry><literal>UINT32</literal></entry>
+ <entry>optional</entry>
+ <entry>The number of Unix file descriptors that
+ accompany the message. If omitted, it is assumed
+ that no Unix file descriptors accompany the
+ message. The actual file descriptors need to be
+ transferred via platform specific mechanism
+ out-of-band. They must be sent at the same time as
+ part of the message itself. They may not be sent
+ before the first byte of the message itself is
+ transferred or after the last byte of the message
+ itself.</entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
<listitem><para>BEGIN</para></listitem>
<listitem><para>DATA <data in hex encoding></para></listitem>
<listitem><para>ERROR [human-readable error explanation]</para></listitem>
+ <listitem><para>NEGOTIATE_UNIX_FD</para></listitem>
</itemizedlist>
From server to client are as follows:
<listitem><para>OK <GUID in hex></para></listitem>
<listitem><para>DATA <data in hex encoding></para></listitem>
<listitem><para>ERROR</para></listitem>
+ <listitem><para>AGREE_UNIX_FD</para></listitem>
</itemizedlist>
</para>
<para>
an OK command must be sent to the client.
</para>
<para>
- The first octet received by the client after the \r\n of the OK
- command must be the first octet of the authenticated/encrypted
- stream of D-Bus messages.
- </para>
- <para>
The first octet received by the server after the \r\n of the BEGIN
command from the client must be the first octet of the
authenticated/encrypted stream of D-Bus messages.
</para>
+ <para>
+ If BEGIN is received by the server, the first octet received
+ by the client after the \r\n of the OK command must be the
+ first octet of the authenticated/encrypted stream of D-Bus
+ messages.
+ </para>
</sect2>
<sect2 id="auth-command-cancel">
<title>CANCEL Command</title>
<sect2 id="auth-command-ok">
<title>OK Command</title>
<para>
- The OK command indicates that the client has been authenticated,
- and that further communication will be a stream of D-Bus messages
- (optionally encrypted, as negotiated) rather than this protocol.
+ The OK command indicates that the client has been
+ authenticated. The client may now proceed with negotiating
+ Unix file descriptor passing. To do that it shall send
+ NEGOTIATE_UNIX_FD to the server.
</para>
<para>
- The first octet received by the client after the \r\n of the OK
- command must be the first octet of the authenticated/encrypted
- stream of D-Bus messages.
+ Otherwise, the client must respond to the OK command by
+ sending a BEGIN command, followed by its stream of messages,
+ or by disconnecting. The server must not accept additional
+ commands using this protocol after the BEGIN command has been
+ received. Further communication will be a stream of D-Bus
+ messages (optionally encrypted, as negotiated) rather than
+ this protocol.
</para>
<para>
- The client must respond to the OK command by sending a BEGIN
- command, followed by its stream of messages, or by disconnecting.
- The server must not accept additional commands using this protocol
- after the OK command has been sent.
+ If a client sends BEGIN the first octet received by the client
+ after the \r\n of the OK command must be the first octet of
+ the authenticated/encrypted stream of D-Bus messages.
</para>
<para>
The OK command has one argument, which is the GUID of the server.
negotiate extensions or changes to the D-Bus protocol in the future.
</para>
</sect2>
+ <sect2 id="auth-command-negotiate-unix-fd">
+ <title>NEGOTIATE_UNIX_FD Command</title>
+ <para>
+ The NEGOTIATE_UNIX_FD command indicates that the client
+ supports Unix file descriptor passing. This command may only
+ be sent after the connection is authenticated, i.e. after OK
+ was received by the client. This command may only be sent on
+ transports that support Unix file descriptor passing.
+ </para>
+ <para>
+ On receiving NEGOTIATE_UNIX_FD the server must respond with
+ either AGREE_UNIX_FD or ERROR. It shall respond the former if
+ the transport chosen supports Unix file descriptor passing and
+ the server supports this feature. It shall respond the latter
+ if the transport does not support Unix file descriptor
+ passing, the server does not support this feature, or the
+ server decides not to enable file descriptor passing due to
+ security or other reasons.
+ </para>
+ </sect2>
+ <sect2 id="auth-command-agree-unix-fd">
+ <title>AGREE_UNIX_FD Command</title>
+ <para>
+ The AGREE_UNIX_FD command indicates that the server supports
+ Unix file descriptor passing. This command may only be sent
+ after the connection is authenticated, and the client sent
+ NEGOTIATE_UNIX_FD to enable Unix file descriptor passing. This
+ command may only be sent on transports that support Unix file
+ descriptor passing.
+ </para>
+ <para>
+ On receiving AGREE_UNIX_FD the client must respond with BEGIN,
+ followed by its stream of messages, or by disconnecting. The
+ server must not accept additional commands using this protocol
+ after the BEGIN command has been received. Further
+ communication will be a stream of D-Bus messages (optionally
+ encrypted, as negotiated) rather than this protocol.
+ </para>
+ </sect2>
+ <sect2 id="auth-command-future">
+ <title>Future Extensions</title>
+ <para>
+ Future extensions to the authentication and negotiation
+ protocol are possible. For that new commands may be
+ introduced. If a client or server receives an unknown command
+ it shall respond with ERROR and not consider this fatal. New
+ commands may be introduced both before, and after
+ authentication, i.e. both before and after the OK command.
+ </para>
+ </sect2>
<sect2 id="auth-examples">
<title>Authentication examples</title>
C: BEGIN
</programlisting>
</figure>
+ <figure>
+ <title>Example of successful magic cookie authentication with successful negotiation of Unix FD passing</title>
+ <programlisting>
+ (MAGIC_COOKIE is a made up mechanism)
+
+ C: AUTH MAGIC_COOKIE 3138363935333137393635383634
+ S: OK 1234deadbeef
+ C: NEGOTIATE_UNIX_FD
+ S: AGREE_UNIX_FD
+ C: BEGIN
+ </programlisting>
+ </figure>
+ <figure>
+ <title>Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing</title>
+ <programlisting>
+ (MAGIC_COOKIE is a made up mechanism)
+
+ C: AUTH MAGIC_COOKIE 3138363935333137393635383634
+ S: OK 1234deadbeef
+ C: NEGOTIATE_UNIX_FD
+ S: ERROR
+ C: BEGIN
+ </programlisting>
+ </figure>
</para>
</sect2>
<sect2 id="auth-states">
length path name. Names which were shorter than the fixed length
would be padded by Nul bytes.
</para>
+ <para>
+ Unix domain sockets are not available on windows.
+ </para>
+ <sect3 id="transports-unix-domain-sockets-addresses">
+ <title>Server Address Format</title>
+ <para>
+ Unix domain socket addresses are identified by the "unix:" prefix
+ and support the following key/value pairs:
+ </para>
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Values</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>path</entry>
+ <entry>(path)</entry>
+ <entry>path of the unix domain socket. If set, the "tmpdir" and "abstract" key must not be set.</entry>
+ </row>
+ <row>
+ <entry>tmpdir</entry>
+ <entry>(path)</entry>
+ <entry>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.</entry>
+ </row>
+ <row>
+ <entry>abstract</entry>
+ <entry>(string)</entry>
+ <entry>unique string (path) in the abstract namespace. If set, the "path" or "tempdir" key must not be set.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect3>
</sect2>
+ <sect2 id="transports-tcp-sockets">
+ <title>TCP Sockets</title>
+ <para>
+ The tcp transport provides TCP/IP based connections between clients
+ located on the same or different hosts.
+ </para>
+ <para>
+ Using tcp transport without any additional secure authentification mechanismus
+ over a network is unsecure.
+ </para>
+ <para>
+ Windows notes: Because of the tcp stack on windows does not provide sending
+ credentials over a tcp connection, the EXTERNAL authentification
+ mechanismus does not work.
+ </para>
+ <sect3 id="transports-tcp-sockets-addresses">
+ <title>Server Address Format</title>
+ <para>
+ TCP/IP socket addresses are identified by the "tcp:" prefix
+ and support the following key/value pairs:
+ </para>
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Values</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>host</entry>
+ <entry>(string)</entry>
+ <entry>dns name or ip address</entry>
+ </row>
+ <row>
+ <entry>port</entry>
+ <entry>(number)</entry>
+ <entry>The tcp port the server will open. A zero value let the server
+ choose a free port provided from the underlaying operating system.
+ libdbus is able to retrieve the real used port from the server.
+ </entry>
+ </row>
+ <row>
+ <entry>family</entry>
+ <entry>(string)</entry>
+ <entry>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect3>
+ </sect2>
+ <sect2 id="transports-nonce-tcp-sockets">
+ <title>Nonce-secured TCP Sockets</title>
+ <para>
+ The nonce-tcp transport provides a secured TCP transport, using a
+ simple authentication mechanism to ensure that only clients with read
+ access to a certain location in the filesystem can connect to the server.
+ The server writes a secret, the nonce, to a file and an incoming client
+ connection is only accepted if the client sends the nonce right after
+ the connect. The nonce mechanism requires no setup and is orthogonal to
+ the higher-level authentication mechanisms described in the
+ Authentication section.
+ </para>
+
+ <para>
+ On start, the server generates a random 16 byte nonce and writes it
+ to a file in the user's temporary directory. The nonce file location
+ is published as part of the server's D-Bus address using the
+ "noncefile" key-value pair.
+
+ After an accept, the server reads 16 bytes from the socket. If the
+ read bytes do not match the nonce stored in the nonce file, the
+ server MUST immediately drop the connection.
+ If the nonce match the received byte sequence, the client is accepted
+ and the transport behaves like an unsecured tcp transport.
+ </para>
+ <para>
+ After a successful connect to the server socket, the client MUST read
+ the nonce from the file published by the server via the noncefile=
+ key-value pair and send it over the socket. After that, the
+ transport behaves like an unsecured tcp transport.
+ </para>
+ <sect3 id="transports-nonce-tcp-sockets-addresses">
+ <title>Server Address Format</title>
+ <para>
+ Nonce TCP/IP socket addresses uses the "nonce-tcp:" prefix
+ and support the following key/value pairs:
+ </para>
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Values</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>host</entry>
+ <entry>(string)</entry>
+ <entry>dns name or ip address</entry>
+ </row>
+ <row>
+ <entry>port</entry>
+ <entry>(number)</entry>
+ <entry>The tcp port the server will open. A zero value let the server
+ choose a free port provided from the underlaying operating system.
+ libdbus is able to retrieve the real used port from the server.
+ </entry>
+ </row>
+ <row>
+ <entry>family</entry>
+ <entry>(string)</entry>
+ <entry>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</entry>
+ </row>
+ <row>
+ <entry>noncefile</entry>
+ <entry>(path)</entry>
+ <entry>file location containing the secret</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect3>
+ </sect2>
+
</sect1>
<sect1 id="naming-conventions">
</glossary>
</article>
-