From 108fdc542a898987f54a3d043c8b56a024cf48a3 Mon Sep 17 00:00:00 2001 From: Anders Carlsson Date: Mon, 17 Feb 2003 11:04:18 +0000 Subject: 2003-02-17 Anders Carlsson * doc/dbus-specification.sgml: Specification updates. --- ChangeLog | 5 + doc/dbus-specification.sgml | 261 +++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 264 insertions(+), 2 deletions(-) diff --git a/ChangeLog b/ChangeLog index f339ef3b..a309338c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2003-02-17 Anders Carlsson + + * doc/dbus-specification.sgml: + Specification updates. + 2003-02-17 Anders Carlsson * bus/activation.c: (bus_activation_init), (child_setup), diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml index 6412bf5b..b7d315e9 100644 --- a/doc/dbus-specification.sgml +++ b/doc/dbus-specification.sgml @@ -413,10 +413,267 @@ and maps fairly directly from the SASL specification. - [move the dbus-sasl-profile.txt stuff into here and clean it up] + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. - + + Protocol Overview + +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: + + + AUTH [mechanism] [initial-response] + CANCELBEGIN + DATA <data in base 64 encoding> + ERROR [human-readable error explanation] + + +From server to client are as follows: + + + REJECTED <space-separated list of mechanism names> + OK + DATA <data in base 64 encoding> + ERROR + + + + + Special credentials-passing nul byte + +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. + + + + + 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. + + + 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 SHOULD send a REJECTED command listing the mechanisms + it does support. + + + 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 authentication succeeds after exchanging DATA commands, + an OK command should 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. + + + + 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 + send a REJECTED command and abort the current authentication + exchange. + + + + DATA Command + + The DATA command may come from either client or server, and simply + contains a base64-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. + + + + BEGIN Command + + 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. + + + + REJECTED Command + + 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. + + + + OK Command + + 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. + + + + ERROR Command + + 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 MUST continue as if the + command causing the ERROR had never been received. + + + + Authentication examples + + +
+ Example of successful magic cookie authentication + +(MAGIC_COOKIE is a made up mechanism) + C: AUTH MAGIC_COOKIE BsAY3g4gBNo= + S: OK + C: BEGIN + +
+
+ Example of finding out mechanisms then picking one + + C: AUTH + S: REJECTED KERBEROS_V4 SKEY + C: AUTH SKEY bW9yZ2Fu + S: DATA OTUgUWE1ODMwOA== + C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA== + S: OK + C: BEGIN + +
+
+ Example of client sends unknown command then falls back to regular auth + + C: FOOBAR + S: ERROR + C: AUTH MAGIC_COOKIE BsAY3g4gBNo= + S: OK + C: BEGIN + +
+
+ Example of server doesn't support initial auth mechanism + + C: AUTH MAGIC_COOKIE BsAY3g4gBNo= + S: REJECTED KERBEROS_V4 SKEY + C: AUTH SKEY bW9yZ2Fu + S: DATA OTUgUWE1ODMwOA== + C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA== + S: OK + C: BEGIN + +
+
+ Example of wrong password or the like followed by successful retry + + C: AUTH MAGIC_COOKIE BsAY3g4gBNo= + S: REJECTED KERBEROS_V4 SKEY + C: AUTH SKEY bW9yZ2Fu + S: DATA OTUgUWE1ODMwOA== + C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA== + S: REJECTED + C: AUTH SKEY bW9yZ2Fu + S: DATA OTUgUWE1ODMwOA== + C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA== + S: OK + C: BEGIN + +
+
+ Example of skey cancelled and restarted + + C: AUTH MAGIC_COOKIE BsAY3g4gBNo= + S: REJECTED KERBEROS_V4 SKEY + C: AUTH SKEY bW9yZ2Fu + S: DATA OTUgUWE1ODMwOA== + C: CANCEL + S: REJECTED + C: AUTH SKEY bW9yZ2Fu + S: DATA OTUgUWE1ODMwOA== + C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA== + S: OK + C: BEGIN + +
+ + + Server Addresses -- cgit