<article id="index">
<articleinfo>
<title>D-Bus Specification</title>
- <releaseinfo>Version 0.17</releaseinfo>
- <date>2011-06-01</date>
+ <releaseinfo>Version 0.19</releaseinfo>
+ <date>UNRELEASED</date>
<authorgroup>
<author>
<firstname>Havoc</firstname>
<revremark></revremark>
</revision>
<revision>
+ <revnumber>0.18</revnumber>
+ <date>29 July 2011</date>
+ <authorinitials>smcv</authorinitials>
+ <revremark>define eavesdropping, unicast, broadcast; add eavesdrop
+ match keyword; promote type system to a top-level section</revremark>
+ </revision>
+ <revision>
<revnumber>0.17</revnumber>
<date>1 June 2011</date>
<authorinitials>smcv/davidz</authorinitials>
</para>
<para>
- Messages may have a <literal>DESTINATION</literal> field (see <xref
- linkend="message-protocol-header-fields"/>). If the
- <literal>DESTINATION</literal> field is present, it specifies a message
- recipient by name. Method calls and replies normally specify this field.
- The message bus must send messages (of any type) with the
- <literal>DESTINATION</literal> field set to the specified recipient,
- regardless of whether the recipient has set up a match rule matching
- the message.
- </para>
-
- <para>
- Signals normally do not specify a destination; they are sent to all
- applications with <firstterm>message matching rules</firstterm> that
- match the message.
- </para>
-
- <para>
- When the message bus receives a method call, if the
- <literal>DESTINATION</literal> field is absent, the call is taken to be
- a standard one-to-one message and interpreted by the message bus
- itself. For example, sending an
- <literal>org.freedesktop.DBus.Peer.Ping</literal> message with no
- <literal>DESTINATION</literal> will cause the message bus itself to
- reply to the ping immediately; the message bus will not make this
- message visible to other applications.
- </para>
-
- <para>
- Continuing the <literal>org.freedesktop.DBus.Peer.Ping</literal> example, if
- the ping message were sent with a <literal>DESTINATION</literal> name of
- <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
- forwarded, and the Yoyodyne Corporation screensaver application would be
- expected to reply to the ping.
+ Applications may send <firstterm>unicast messages</firstterm> to
+ a specific recipient or to the message bus itself, or
+ <firstterm>broadcast messages</firstterm> to all interested recipients.
+ See <xref linkend="message-bus-routing"/> for details.
</para>
</sect2>
<sect2 id="message-bus-routing">
<title>Message Bus Message Routing</title>
+
<para>
- FIXME
+ Messages may have a <literal>DESTINATION</literal> field (see <xref
+ linkend="message-protocol-header-fields"/>), resulting in a
+ <firstterm>unicast message</firstterm>. If the
+ <literal>DESTINATION</literal> field is present, it specifies a message
+ recipient by name. Method calls and replies normally specify this field.
+ The message bus must send messages (of any type) with the
+ <literal>DESTINATION</literal> field set to the specified recipient,
+ regardless of whether the recipient has set up a match rule matching
+ the message.
+ </para>
+
+ <para>
+ When the message bus receives a signal, if the
+ <literal>DESTINATION</literal> field is absent, it is considered to
+ be a <firstterm>broadcast signal</firstterm>, and is sent to all
+ applications with <firstterm>message matching rules</firstterm> that
+ match the message. Most signal messages are broadcasts.
</para>
+
+ <para>
+ Unicast signal messages (those with a <literal>DESTINATION</literal>
+ field) are not commonly used, but they are treated like any unicast
+ message: they are delivered to the specified receipient,
+ regardless of its match rules. One use for unicast signals is to
+ avoid a race condition in which a signal is emitted before the intended
+ recipient can call <xref linkend="bus-messages-add-match"/> to
+ receive that signal: if the signal is sent directly to that recipient
+ using a unicast message, it does not need to add a match rule at all,
+ and there is no race condition. Another use for unicast signals,
+ on message buses whose security policy prevents eavesdropping, is to
+ send sensitive information which should only be visible to one
+ recipient.
+ </para>
+
+ <para>
+ When the message bus receives a method call, if the
+ <literal>DESTINATION</literal> field is absent, the call is taken to be
+ a standard one-to-one message and interpreted by the message bus
+ itself. For example, sending an
+ <literal>org.freedesktop.DBus.Peer.Ping</literal> message with no
+ <literal>DESTINATION</literal> will cause the message bus itself to
+ reply to the ping immediately; the message bus will not make this
+ message visible to other applications.
+ </para>
+
+ <para>
+ Continuing the <literal>org.freedesktop.DBus.Peer.Ping</literal> example, if
+ the ping message were sent with a <literal>DESTINATION</literal> name of
+ <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
+ forwarded, and the Yoyodyne Corporation screensaver application would be
+ expected to reply to the ping.
+ </para>
+
+ <para>
+ Message bus implementations may impose a security policy which
+ prevents certain messages from being sent or received.
+ When a message cannot be sent or received due to a security
+ policy, the message bus should send an error reply, unless the
+ original message had the <literal>NO_REPLY</literal> flag.
+ </para>
+
+ <sect3 id="message-bus-routing-eavesdropping">
+ <title>Eavesdropping</title>
+ <para>
+ Receiving a unicast message whose <literal>DESTINATION</literal>
+ indicates a different recipient is called
+ <firstterm>eavesdropping</firstterm>. On a message bus which acts as
+ a security boundary (like the standard system bus), the security
+ policy should usually prevent eavesdropping, since unicast messages
+ are normally kept private and may contain security-sensitive
+ information.
+ </para>
+
+ <para>
+ Eavesdropping is mainly useful for debugging tools, such as
+ the <literal>dbus-monitor</literal> tool in the reference
+ implementation of D-Bus. Tools which eavesdrop on the message bus
+ should be careful to avoid sending a reply or error in response to
+ messages intended for a different client.
+ </para>
+
+ <para>
+ Clients may attempt to eavesdrop by adding match rules
+ (see <xref linkend="message-bus-routing-match-rules"/>) containing
+ the <literal>eavesdrop='true'</literal> match. If the message bus'
+ security policy does not allow eavesdropping, the match rule can
+ still be added, but will not have any practical effect. For
+ compatibility with older message bus implementations, if adding such
+ a match rule results in an error reply, the client may fall back to
+ adding the same rule with the <literal>eavesdrop</literal> match
+ omitted.
+ </para>
+ </sect3>
+
<sect3 id="message-bus-routing-match-rules">
<title>Match Rules</title>
<para>
- An important part of the message bus routing protocol is match
- rules. Match rules describe what messages can be sent to a client
- based on the contents of the message. When a message is routed
- through the bus it is compared to clients' match rules. If any
- of the rules match, the message is dispatched to the client.
- If none of the rules match the message never leaves the bus. This
- is an effective way to control traffic over the bus and to make sure
- only relevant message need to be processed by the client.
+ An important part of the message bus routing protocol is match
+ rules. Match rules describe the messages that should be sent to a
+ client, based on the contents of the message. Broadcast signals
+ are only sent to clients which have a suitable match rule: this
+ avoids waking up client processes to deal with signals that are
+ not relevant to that client.
+ </para>
+ <para>
+ Messages that list a client as their <literal>DESTINATION</literal>
+ do not need to match the client's match rules, and are sent to that
+ client regardless. As a result, match rules are mainly used to
+ receive a subset of broadcast signals.
+ </para>
+ <para>
+ Match rules can also be used for eavesdropping
+ (see <xref linkend="message-bus-routing-eavesdropping"/>),
+ if the security policy of the message bus allows it.
</para>
<para>
Match rules are added using the AddMatch bus method
</para>
</entry>
</row>
+ <row>
+ <entry><literal>eavesdrop</literal></entry>
+ <entry><literal>'true'</literal>, <literal>'false'</literal></entry>
+ <entry>Since D-Bus 1.5.6, match rules do not
+ match messages which have a <literal>DESTINATION</literal>
+ field unless the match rule specifically
+ requests this
+ (see <xref linkend="message-bus-routing-eavesdropping"/>)
+ by specifying <literal>eavesdrop='true'</literal>
+ in the match rule. <literal>eavesdrop='false'</literal>
+ restores the default behaviour. Messages are
+ delivered to their <literal>DESTINATION</literal>
+ regardless of match rules, so this match does not
+ affect normal delivery of unicast messages.
+ If the message bus has a security policy which forbids
+ eavesdropping, this match may still be used without error,
+ but will not have any practical effect.
+ In older versions of D-Bus, this match was not allowed
+ in match rules, and all match rules behaved as if
+ <literal>eavesdrop='true'</literal> had been used.
+ </entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
projects / platform / upstream / dbus.git / blobdiff