From bf75b24d26fdc9deb856bac1918fa4853c594b03 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Mon, 7 Feb 2005 05:44:57 +0000 Subject: 2005-02-07 Havoc Pennington * doc/dbus-specification.xml: some more language cleanups; add stuff about how to deal with invalid protocol and extension points; add _ to allowed chars in auth commands; add EXTENSION_ auth command prefix --- doc/dbus-specification.xml | 169 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 130 insertions(+), 39 deletions(-) (limited to 'doc') diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 9fc7b0f9..ad78f0a0 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -119,6 +119,14 @@ spec and the reference implementation probably will not incorporate features that interfere with the core use cases. + + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119. However, the + document could use a serious audit to be sure it makes sense to do + so. Also, they are not capitalized. + @@ -696,14 +704,14 @@ 2nd BYTE - Message type. Unknown types MUST be ignored. + Message type. Unknown types must be ignored. Currently-defined types are described below. 3rd BYTE Bitwise OR of flags. Unknown flags - MUST be ignored. Currently-defined flags are described below. + must be ignored. Currently-defined flags are described below. @@ -711,7 +719,7 @@ Major protocol version of the sending application. If the major protocol version of the receiving application does not match, the applications will not be able to communicate and the - D-BUS connection MUST be disconnected. The major protocol + D-BUS connection must be disconnected. The major protocol version for this version of the specification is 0. FIXME this field is stupid and pointless to put in every message. @@ -759,8 +767,7 @@ INVALID 0 - This is an invalid type, if seen in a message - the connection should be dropped immediately. + This is an invalid type. METHOD_CALL @@ -805,13 +812,15 @@ This message does not expect method return replies or error replies; the reply can be omitted as an optimization. However, it is compliant with this specification - to return the reply despite this flag. + to return the reply despite this flag and the only harm + from doing so is extra network traffic. + NO_AUTO_START 0x2 - This message should not automatically launch an owner - for the destination name. + The bus must not launch an owner + for the destination name in response to this message. @@ -835,18 +844,18 @@ Again, if an implementation sees a header field code that it does not - expect, it MUST ignore that field, as it will be part of a new + expect, it must ignore that field, as it will be part of a new (but compatible) version of this specification. This also applies to known header fields appearing in unexpected messages, for - example if a signal has a reply serial that should be ignored + example: if a signal has a reply serial it must be ignored even though it has no meaning as of this version of the spec. However, implementations must not send or accept known header fields - with the wrong type stored in the field value. So for example - a message with an INTERFACE field of type UINT32 would be considered - corrupt. + with the wrong type stored in the field value. So for example a + message with an INTERFACE field of type + UINT32 would be considered corrupt. @@ -917,7 +926,7 @@ 6 STRING optional - The name of the connection this message should be routed to. + The name of the connection this message is intended for. Only used in combination with the message bus, see . @@ -1212,6 +1221,82 @@ + + Invalid Protocol and Spec Extensions + + + 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 idiosyncracy 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. + + + + In the authentication protocol (see ) unknown + commands result in an ERROR rather than a disconnect. This enables + future extensions to the protocol. Commands starting with EXTENSION_ are + reserved for third parties. + + + + + The authentication protocol supports pluggable auth mechanisms. + + + + + The address format (see ) supports new + kinds of transport. + + + + + Messages with an unknown type (something other than + METHOD_CALL, METHOD_RETURN, + ERROR, SIGNAL) are ignored. + Unknown-type messages must still be well-formed in the same way + as the known messages, however. They still have the normal + header and body. + + + + + Header fields with an unknown or unexpected field code must be ignored, + though again they must still be well-formed. + + + + + New standard interfaces (with new methods and signals) can of course be added. + + + + + + + @@ -1232,7 +1317,7 @@ 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 + 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. @@ -1255,6 +1340,11 @@ ERROR + + 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". + Special credentials-passing nul byte @@ -1263,7 +1353,7 @@ 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 + 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 @@ -1283,38 +1373,39 @@ AUTH command If an AUTH command has no arguments, it is a request to list - available mechanisms. The server SHOULD respond with a REJECTED - command listing the mechanisms it understands. + 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 + 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 SHOULD send a REJECTED command listing the mechanisms - it does support. + 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, the - server should reject authentication by sending REJECTED. + 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 should be sent to the client. + 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 + 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 + command from the client must be the first octet of the authenticated/encrypted stream of D-BUS messages. @@ -1322,7 +1413,7 @@ CANCEL Command At any time up to sending the BEGIN command, the client may send a - CANCEL command. On receiving the CANCEL command, the server MUST + CANCEL command. On receiving the CANCEL command, the server must send a REJECTED command and abort the current authentication exchange. @@ -1348,7 +1439,7 @@ 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 + command from the client must be the first octet of the authenticated/encrypted stream of D-BUS messages. @@ -1362,7 +1453,7 @@ 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 + 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. @@ -1376,13 +1467,13 @@ The first octet received by the client after the \r\n of the OK - command MUST be the first octet of the authenticated/encrypted + 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 + 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 + The server must not accept additional commands using this protocol after the OK command has been sent. @@ -1399,7 +1490,7 @@ 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 + 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. @@ -2194,8 +2285,8 @@ Only the root <node> element can omit the node name, as it's known to be the object that was introspected. If the root - <node> does have a name attribute, it should be an absolute - object path. If child <node> have object paths, they should be + <node> does have a name attribute, it must be an absolute + object path. If child <node> have object paths, they must be relative. @@ -2568,7 +2659,7 @@ The executable being launched may want to know whether the message bus starting it is one of the well-known message buses (see ). To facilitate this, the bus MUST also set + linkend="message-bus-types"/>). 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, -- cgit