D-Bus Specification

The D-Bus protocol is frozen (only compatible extensions are allowed) as of November 8, 2006. However, this specification could still use a fair bit of work to make interoperable reimplementation possible without reference to the D-Bus reference implementation. Thus, this specification is not marked 1.0. To mark it 1.0, we'd like to see someone invest significant effort in clarifying the specification language, and growing the specification to cover more aspects of the reference implementation's behavior.

Until this work is complete, any attempt to reimplement D-Bus will probably require looking at the reference implementation and/or asking questions on the D-Bus mailing list about intended behavior. Questions on the list are very welcome.

Nonetheless, this document should be a useful starting point and is to our knowledge accurate, though incomplete.

The D-Bus protocol does not include type tags in the marshaled data; a block of marshaled values must have a known type signature. The type signature is made up of type codes. A type code is an ASCII character representing the type of a value. Because ASCII characters are used, the type signature will always form a valid ASCII string. A simple string compare determines whether two type signatures are equivalent.

As a simple example, the type code for 32-bit integer (INT32) is the ASCII character 'i'. So the signature for a block of values containing a single INT32 would be:

          "i"
        

A block of values containing two INT32 would have this signature:

          "ii"
        

All basic types work like INT32 in this example. To marshal and unmarshal basic types, you simply read one value from the data block corresponding to each type code in the signature. In addition to basic types, there are four container types: STRUCT, ARRAY, VARIANT, and DICT_ENTRY.

STRUCT has a type code, ASCII character 'r', but this type code does not appear in signatures. Instead, ASCII characters '(' and ')' are used to mark the beginning and end of the struct. So for example, a struct containing two integers would have this signature:

          "(ii)"
        

Structs can be nested, so for example a struct containing an integer and another struct:

          "(i(ii))"
        

The value block storing that struct would contain three integers; the type signature allows you to distinguish "(i(ii))" from "((ii)i)" or "(iii)" or "iii".

The STRUCT type code 'r' is not currently used in the D-Bus protocol, but is useful in code that implements the protocol. This type code is specified to allow such code to interoperate in non-protocol contexts.

ARRAY has ASCII character 'a' as type code. The array type code must be followed by a single complete type. The single complete type following the array is the type of each array element. So the simple example is:

          "ai"
        

which is an array of 32-bit integers. But an array can be of any type, such as this array-of-struct-with-two-int32-fields:

          "a(ii)"
        

Or this array of array of integer:

          "aai"
        

The phrase single complete type deserves some definition. A single complete type is a basic type code, a variant type code, an array with its element type, or a struct with its fields. So the following signatures are not single complete types:

          "aa"
        

          "(ii"
        

          "ii)"
        

And the following signatures contain multiple complete types:

          "ii"
        

          "aiai"
        

          "(ii)(ii)"
        

Note however that a single complete type may contain multiple other single complete types.

VARIANT has ASCII character 'v' as its type code. A marshaled value of type VARIANT will have the signature of a single complete type as part of the value. This signature will be followed by a marshaled value of that type.

A DICT_ENTRY works exactly like a struct, but rather than parentheses it uses curly braces, and it has more restrictions. The restrictions are: it occurs only as an array element type; it has exactly two single complete types inside the curly braces; the first single complete type (the "key") must be a basic type rather than a container type. Implementations must not accept dict entries outside of arrays, must not accept dict entries with zero, one, or more than two fields, and must not accept dict entries with non-basic-typed keys. A dict entry is always a key-value pair.

The first field in the DICT_ENTRY is always the key. A message is considered corrupt if the same key occurs twice in the same array of DICT_ENTRY. However, for performance reasons implementations are not required to reject dicts with duplicate keys.

In most languages, an array of dict entry would be represented as a map, hash table, or dict object.

The following table summarizes the D-Bus types.

Given a type signature, a block of bytes can be converted into typed values. This section describes the format of the block of bytes. Byte order and alignment issues are handled uniformly for all D-Bus types.

A block of bytes has an associated byte order. The byte order has to be discovered in some way; for D-Bus messages, the byte order is part of the message header as described in the section called “Message Format”. For now, assume that the byte order is known to be either little endian or big endian.

Each value in a block of bytes is aligned "naturally," for example 4-byte values are aligned to a 4-byte boundary, and 8-byte values to an 8-byte boundary. To properly align a value, alignment padding may be necessary. The alignment padding must always be the minimum required padding to properly align the following value; and it must always be made up of nul bytes. The alignment padding must not be left uninitialized (it can't contain garbage), and more padding than required must not be used.

Given all this, the types are marshaled on the wire as follows:

A message consists of a header and a body. The header is a block of values with a fixed signature and meaning. The body is a separate block of values, with a signature specified in the header.

The length of the header must be a multiple of 8, allowing the body to begin on an 8-byte boundary when storing the entire message in a single buffer. If the header does not naturally end on an 8-byte boundary up to 7 bytes of nul-initialized alignment padding must be added.

The message body need not end on an 8-byte boundary.

The maximum length of a message, including header, header alignment padding, and body is 2 to the 27th power or 134217728. Implementations must not send or accept messages exceeding this size.

The signature of the header is:

          "yyyyuua(yv)"
        

Written out more readably, this is:

          BYTE, BYTE, BYTE, BYTE, UINT32, UINT32, ARRAY of STRUCT of (BYTE,VARIANT)
        

These values have the following meanings:

Message types that can appear in the second byte of the header are:

Flags that can appear in the third byte of the header:

The various names in D-Bus messages have some restrictions.

There is a maximum name length of 255 which applies to bus names, interfaces, and members.

Each of the message types (METHOD_CALL, METHOD_RETURN, ERROR, and SIGNAL) has its own expected usage conventions and header fields. This section describes these conventions.

            org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags,
                                                     out UINT32 resultcode)
          

            unsigned int org::freedesktop::DBus::StartServiceByName (const char  *name,
                                                                     unsigned int flags);
          

            void org::freedesktop::DBus::StartServiceByName (const char   *name, 
                                                             unsigned int  flags,
                                                             unsigned int *resultcode);
          

            org.freedesktop.DBus.NameLost (STRING name)
          

For security reasons, the D-Bus protocol should be strictly parsed and validated, with the exception of defined extension points. Any invalid protocol or spec violations should result in immediately dropping the connection without notice to the other end. Exceptions should be carefully considered, e.g. an exception may be warranted for a well-understood idiosyncrasy of a widely-deployed implementation. In cases where the other end of a connection is 100% trusted and known to be friendly, skipping validation for performance reasons could also make sense in certain cases.

Generally speaking violations of the "must" requirements in this spec should be considered possible attempts to exploit security, and violations of the "should" suggestions should be considered legitimate (though perhaps they should generate an error in some cases).

The following extension points are built in to D-Bus on purpose and must not be treated as invalid protocol. The extension points are intended for use by future versions of this spec, they are not intended for third parties. At the moment, the only way a third party could extend D-Bus without breaking interoperability would be to introduce a way to negotiate new feature support as part of the auth protocol, using EXTENSION_-prefixed commands. There is not yet a standard way to negotiate features.

The protocol is a line-based protocol, where each line ends with \r\n. Each line begins with an all-caps ASCII command name containing only the character range [A-Z_], a space, then any arguments for the command, then the \r\n ending the line. The protocol is case-sensitive. All bytes must be in the ASCII character set. Commands from the client to the server are as follows:

From server to client are as follows:

Unofficial extensions to the command set must begin with the letters "EXTENSION_", to avoid conflicts with future official commands. For example, "EXTENSION_COM_MYDOMAIN_DO_STUFF".

Immediately after connecting to the server, the client must send a single nul byte. This byte may be accompanied by credentials information on some operating systems that use sendmsg() with SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain sockets. However, the nul byte must be sent even on other kinds of socket, and even on operating systems that do not require a byte to be sent in order to transmit credentials. The text protocol described in this document begins after the single nul byte. If the first byte received from the client is not a nul byte, the server may disconnect that client.

A nul byte in any context other than the initial byte is an error; the protocol is ASCII-only.

The credentials sent along with the nul byte may be used with the SASL mechanism EXTERNAL.

If an AUTH command has no arguments, it is a request to list available mechanisms. The server must respond with a REJECTED command listing the mechanisms it understands, or with an error.

If an AUTH command specifies a mechanism, and the server supports said mechanism, the server should begin exchanging SASL challenge-response data with the client using DATA commands.

If the server does not support the mechanism given in the AUTH command, it must send either a REJECTED command listing the mechanisms it does support, or an error.

If the [initial-response] argument is provided, it is intended for use with mechanisms that have no initial challenge (or an empty initial challenge), as if it were the argument to an initial DATA command. If the selected mechanism has an initial challenge and [initial-response] was provided, the server should reject authentication by sending REJECTED.

If authentication succeeds after exchanging DATA commands, an OK command must be sent to the client.

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.

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.

At any time up to sending the BEGIN command, the client may send a CANCEL command. On receiving the CANCEL command, the server must send a REJECTED command and abort the current authentication exchange.

The DATA command may come from either client or server, and simply contains a hex-encoded block of data to be interpreted according to the SASL mechanism in use.

Some SASL mechanisms support sending an "empty string"; FIXME we need some way to do this.

The BEGIN command acknowledges that the client has received an OK command from the server, and that the stream of messages is about to begin.

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.

The REJECTED command indicates that the current authentication exchange has failed, and further exchange of DATA is inappropriate. The client would normally try another mechanism, or try providing different responses to challenges.

Optionally, the REJECTED command has a space-separated list of available auth mechanisms as arguments. If a server ever provides a list of supported mechanisms, it must provide the same list each time it sends a REJECTED message. Clients are free to ignore all lists received after the first.

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 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.

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.

The OK command has one argument, which is the GUID of the server. See the section called “Server Addresses” for more on server GUIDs.

The ERROR command indicates that either server or client did not know a command, does not accept the given command in the current context, or did not understand the arguments to the command. This allows the protocol to be extended; a client or server can send a command present or permitted only in new protocol versions, and if an ERROR is received instead of an appropriate response, fall back to using some other technique.

If an ERROR is sent, the server or client that sent the error must continue as if the command causing the ERROR had never been received. However, the the server or client receiving the error should try something other than whatever caused the error; if only canceling/rejecting the authentication.

If the D-Bus protocol changes incompatibly at some future time, applications implementing the new protocol would probably be able to check for support of the new protocol by sending a new command and receiving an ERROR from applications that don't understand it. Thus the ERROR feature of the auth protocol is an escape hatch that lets us negotiate extensions or changes to the D-Bus protocol in the future.

This section documents the auth protocol in terms of a state machine for the client and the server. This is probably the most robust way to implement the protocol.

This section describes some new authentication mechanisms. D-Bus also allows any standard SASL mechanism of course.

Unix domain sockets can be either paths in the file system or on Linux kernels, they can be abstract which are similar to paths but do not show up in the file system.

When a socket is opened by the D-Bus library it truncates the path name right before the first trailing Nul byte. This is true for both normal paths and abstract paths. Note that this is a departure from previous versions of D-Bus that would create sockets with a fixed length path name. Names which were shorter than the fixed length would be padded by Nul bytes.

The org.freedesktop.DBus.Peer interface has two methods:

          org.freedesktop.DBus.Peer.Ping ()
          org.freedesktop.DBus.Peer.GetMachineId (out STRING machine_uuid)
        

On receipt of the METHOD_CALL message org.freedesktop.DBus.Peer.Ping, an application should do nothing other than reply with a METHOD_RETURN as usual. It does not matter which object path a ping is sent to. The reference implementation handles this method automatically.

On receipt of the METHOD_CALL message org.freedesktop.DBus.Peer.GetMachineId, an application should reply with a METHOD_RETURN containing a hex-encoded UUID representing the identity of the machine the process is running on. This UUID must be the same for all processes on a single system at least until that system next reboots. It should be the same across reboots if possible, but this is not always possible to implement and is not guaranteed. It does not matter which object path a GetMachineId is sent to. The reference implementation handles this method automatically.

The UUID is intended to be per-instance-of-the-operating-system, so may represent a virtual machine running on a hypervisor, rather than a physical machine. Basically if two processes see the same UUID, they should also see the same shared memory, UNIX domain sockets, process IDs, and other features that require a running OS kernel in common between the processes.

The UUID is often used where other programs might use a hostname. Hostnames can change without rebooting, however, or just be "localhost" - so the UUID is more robust.

the section called “UUIDs” explains the format of the UUID.

This interface has one method:

          org.freedesktop.DBus.Introspectable.Introspect (out STRING xml_data)
        

Objects instances may implement Introspect which returns an XML description of the object, including its interfaces (with signals and methods), objects below it in the object path tree, and its properties.

the section called “Introspection Data Format” describes the format of this XML string.

Many native APIs will have a concept of object properties or attributes. These can be exposed via the org.freedesktop.DBus.Properties interface.

              org.freedesktop.DBus.Properties.Get (in STRING interface_name,
                                                   in STRING property_name,
                                                   out VARIANT value);
              org.freedesktop.DBus.Properties.Set (in STRING interface_name,
                                                   in STRING property_name,
                                                   in VARIANT value);
              org.freedesktop.DBus.Properties.GetAll (in STRING interface_name,
                                                      out DICT<STRING,VARIANT> props);
        

The available properties and whether they are writable can be determined by calling org.freedesktop.DBus.Introspectable.Introspect, see the section called “org.freedesktop.DBus.Introspectable”.

An empty string may be provided for the interface name; in this case, if there are multiple properties on an object with the same name, the results are undefined (picking one by according to an arbitrary deterministic rule, or returning an error, are the reasonable possibilities).

The message bus accepts connections from one or more applications. Once connected, applications can exchange messages with other applications that are also connected to the bus.

In order to route messages among connections, the message bus keeps a mapping from names to connections. Each connection has one unique-for-the-lifetime-of-the-bus name automatically assigned. Applications may request additional names for a connection. Additional names are usually "well-known names" such as "org.freedesktop.TextEditor". When a name is bound to a connection, that connection is said to own the name.

The bus itself owns a special name, org.freedesktop.DBus. This name routes messages to the bus, allowing applications to make administrative requests. For example, applications can ask the bus to assign a name to a connection.

Each name may have queued owners. When an application requests a name for a connection and the name is already in use, the bus will optionally add the connection to a queue waiting for the name. If the current owner of the name disconnects or releases the name, the next connection in the queue will become the new owner.

This feature causes the right thing to happen if you start two text editors for example; the first one may request "org.freedesktop.TextEditor", and the second will be queued as a possible owner of that name. When the first exits, the second will take over.

Messages may have a DESTINATION field (see the section called “Header Fields”). If the DESTINATION field is present, it specifies a message recipient by name. Method calls and replies normally specify this field.

Signals normally do not specify a destination; they are sent to all applications with message matching rules that match the message.

When the message bus receives a method call, if the DESTINATION 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 org.freedesktop.DBus.Peer.Ping message with no DESTINATION will cause the message bus itself to reply to the ping immediately; the message bus will not make this message visible to other applications.

Continuing the org.freedesktop.DBus.Peer.Ping example, if the ping message were sent with a DESTINATION name of com.yoyodyne.Screensaver, then the ping would be forwarded, and the Yoyodyne Corporation screensaver application would be expected to reply to the ping.

Each connection has at least one name, assigned at connection time and returned in response to the org.freedesktop.DBus.Hello method call. This automatically-assigned name is called the connection's unique name. Unique names are never reused for two different connections to the same bus.

Ownership of a unique name is a prerequisite for interaction with the message bus. It logically follows that the unique name is always the first name that an application comes to own, and the last one that it loses ownership of.

Unique connection names must begin with the character ':' (ASCII colon character); bus names that are not unique names must not begin with this character. (The bus must reject any attempt by an application to manually request a name beginning with ':'.) This restriction categorically prevents "spoofing"; messages sent to a unique name will always go to the expected connection.

When a connection is closed, all the names that it owns are deleted (or transferred to the next connection in the queue if any).

A connection can request additional names to be associated with it using the org.freedesktop.DBus.RequestName message. the section called “Bus names” describes the format of a valid name. These names can be released again using the org.freedesktop.DBus.ReleaseName message.

            UINT32 RequestName (in STRING name, in UINT32 flags)
          

            UINT32 ReleaseName (in STRING name)
          

FIXME

The message bus can start applications on behalf of other applications. In CORBA terms, this would be called activation. An application that can be started in this way is called a service.

With D-Bus, starting a service is normally done by name. That is, applications ask the message bus to start some program that will own a well-known name, such as org.freedesktop.TextEditor. This implies a contract documented along with the name org.freedesktop.TextEditor for which objects the owner of that name will provide, and what interfaces those objects will have.

To find an executable corresponding to a particular name, the bus daemon looks for service description files. Service description files define a mapping from names to executables. Different kinds of message bus will look for these files in different places, see the section called “Well-known Message Bus Instances”.

[FIXME the file format should be much better specified than "similar to .desktop entries" esp. since desktop entries are already badly-specified. ;-)] Service description files have the ".service" file extension. The message bus will only load service description files ending with .service; all other files will be ignored. The file format is similar to that of desktop entries. All service description files must be in UTF-8 encoding. To ensure that there will be no name collisions, service files must be namespaced using the same mechanism as messages and service names.

            # Sample service description file
            [D-BUS Service]
            Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
            Exec=/usr/libexec/gconfd-2
          

When an application asks to start a service by name, the bus daemon tries to find a service that will own that name. It then tries to spawn the executable associated with it. If this fails, it will report an error. [FIXME what happens if two .service files offer the same service; what kind of error is reported, should we have a way for the client to choose one?]

The executable launched will have the environment variable DBUS_STARTER_ADDRESS set to the address of the message bus so it can connect and request the appropriate names.

The executable being launched may want to know whether the message bus starting it is one of the well-known message buses (see the section called “Well-known Message Bus Instances”). To facilitate this, the bus must also set the DBUS_STARTER_BUS_TYPE environment variable if it is one of the well-known buses. The currently-defined values for this variable are system for the systemwide message bus, and session for the per-login-session message bus. The new executable must still connect to the address given in DBUS_STARTER_ADDRESS, but may assume that the resulting connection is to the well-known bus.

[FIXME there should be a timeout somewhere, either specified in the .service file, by the client, or just a global value and if the client being activated fails to connect within that timeout, an error should be sent back.]

Two standard message bus instances are defined here, along with how to locate them and where their service files live.

The special message bus name org.freedesktop.DBus responds to a number of additional messages.

            STRING Hello ()
          

            ARRAY of STRING ListNames ()
          

            ARRAY of STRING ListActivatableNames ()
          

            BOOLEAN NameHasOwner (in STRING name)
          

            NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
          

            NameLost (STRING name)
          

            NameAcquired (STRING name)
          

            UINT32 StartServiceByName (in STRING name, in UINT32 flags)
          

            STRING GetNameOwner (in STRING name)
          

            UINT32 GetConnectionUnixUser (in STRING connection_name)
          

            AddMatch (in STRING rule)
          

            RemoveMatch (in STRING rule)
          

            GetId (out STRING id)