diff options
Diffstat (limited to 'doc/dbus-specification.xml')
| -rw-r--r-- | doc/dbus-specification.xml | 235 |
1 files changed, 174 insertions, 61 deletions
diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 4bd0cb32..282fb3b0 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -78,6 +78,13 @@ <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> @@ -264,27 +271,13 @@ </sect1> - <sect1 id="message-protocol"> - <title>Message Protocol</title> - - <para> - A <firstterm>message</firstterm> consists of a - <firstterm>header</firstterm> and a <firstterm>body</firstterm>. If you - think of a message as a package, the header is the address, and the body - contains the package contents. The message delivery system uses the header - information to figure out where to send the message and how to interpret - it; the recipient interprets the body of the message. - </para> - - <para> - The body of the message is made up of zero or more - <firstterm>arguments</firstterm>, which are typed values, such as an - integer or a byte array. - </para> + <sect1 id="type-system"> + <title>Type System</title> <para> - Both header and body use the same type system and format for - serializing data. Each type of value has a wire format. + D-Bus has a type system, in which values of various types can be + serialized into a sequence of bytes referred to as the + <firstterm>wire format</firstterm> in a standard way. Converting a value from some other representation into the wire format is called <firstterm>marshaling</firstterm> and converting it back from the wire format is <firstterm>unmarshaling</firstterm>. @@ -843,6 +836,31 @@ </sect2> + </sect1> + + <sect1 id="message-protocol"> + <title>Message Protocol</title> + + <para> + A <firstterm>message</firstterm> consists of a + <firstterm>header</firstterm> and a <firstterm>body</firstterm>. If you + think of a message as a package, the header is the address, and the body + contains the package contents. The message delivery system uses the header + information to figure out where to send the message and how to interpret + it; the recipient interprets the body of the message. + </para> + + <para> + The body of the message is made up of zero or more + <firstterm>arguments</firstterm>, which are typed values, such as an + integer or a byte array. + </para> + + <para> + Both header and body use the D-Bus <link linkend="type-system">type + system</link> and format for serializing data. + </para> + <sect2 id="message-protocol-messages"> <title>Message Format</title> @@ -3374,39 +3392,10 @@ </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> @@ -3840,20 +3829,122 @@ <sect2 id="message-bus-routing"> <title>Message Bus Message Routing</title> + + <para> + 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> - FIXME + 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 @@ -4031,6 +4122,28 @@ </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> |