From 869291ea5a98485183bbe1a4d2cdab9eb97fbb0d Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 20 May 2009 03:01:37 +0200 Subject: doc: document Unix FD passing in the specification --- doc/dbus-specification.xml | 141 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 125 insertions(+), 16 deletions(-) diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 9b22c84a..8d10aade 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -415,6 +415,10 @@ DICT_ENTRY 101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') Entry in a dict or map (array of key-value pairs) + + UNIX_FD + 104 (ASCII 'h') + Unix file descriptor @@ -579,6 +583,15 @@ 8 + + UNIX_FD + 32-bit unsigned integer in the message's byte + order. The actual file descriptors need to be + transferred out-of-band via some platform specific + mechanism. On the wire, values of this type store the index to the + file descriptor in the array of file descriptors that + accompany the message. + 4 @@ -999,6 +1012,22 @@ If omitted, it is assumed to be the empty signature "" (i.e. the body must be 0-length). + + UNIX_FDS + 9 + UINT32 + optional + The number of Unix file descriptors that + accompany the message. If omitted, it is assumed + that no Unix file descriptors accompany the + message. The actual file descriptors need to be + transferred via platform specific mechanism + out-of-band. They must be sent at the same time as + part of the message itself. They may not be sent + before the first byte of the message itself is + transferred or after the last byte of the message + itself. + @@ -1410,6 +1439,7 @@ BEGIN DATA <data in hex encoding> ERROR [human-readable error explanation] + NEGOTIATE_UNIX_FD From server to client are as follows: @@ -1419,6 +1449,7 @@ OK <GUID in hex> DATA <data in hex encoding> ERROR + AGREE_UNIX_FD @@ -1479,16 +1510,17 @@ 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. + + If BEGIN is received by the server, 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. + CANCEL Command @@ -1542,20 +1574,24 @@ 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 OK command indicates that the client has been + authenticated. The client may now proceed with negotiating + Unix file descriptor passing. To do that it shall send + NEGOTIATE_UNIX_FD to the server. - 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. + Otherwise, 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 BEGIN command has been + received. Further communication will be a stream of D-Bus + messages (optionally encrypted, as negotiated) rather than + this protocol. - 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. + If a client sends BEGIN 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 OK command has one argument, which is the GUID of the server. @@ -1589,6 +1625,56 @@ negotiate extensions or changes to the D-Bus protocol in the future. + + NEGOTIATE_UNIX_FD Command + + The NEGOTIATE_UNIX_FD command indicates that the client + supports Unix file descriptor passing. This command may only + be sent after the connection is authenticated, i.e. after OK + was received by the client. This command may only be sent on + transports that support Unix file descriptor passing. + + + On receiving NEGOTIATE_UNIX_FD the server must respond with + either AGREE_UNIX_FD or ERROR. It shall respond the former if + the transport chosen supports Unix file descriptor passing and + the server supports this feature. It shall respond the latter + if the transport does not support Unix file descriptor + passing, the server does not support this feature, or the + server decides not to enable file descriptor passing due to + security or other reasons. + + + + AGREE_UNIX_FD Command + + The AGREE_UNIX_FD command indicates that the server supports + Unix file descriptor passing. This command may only be sent + after the connection is authenticated, and the client sent + NEGOTIATE_UNIX_FD to enable Unix file descriptor passing. This + command may only be sent on transports that support Unix file + descriptor passing. + + + On receiving AGREE_UNIX_FD the client must respond with BEGIN, + followed by its stream of messages, or by disconnecting. The + server must not accept additional commands using this protocol + after the BEGIN command has been received. Further + communication will be a stream of D-Bus messages (optionally + encrypted, as negotiated) rather than this protocol. + + + + Future Extensions + + Future extensions to the authentication and negotiation + protocol are possible. For that new commands may be + introduced. If a client or server receives an unknown command + it shall respond with ERROR and not consider this fatal. New + commands may be introduced both before, and after + authentication, i.e. both before and after the OK command. + + Authentication examples @@ -1669,6 +1755,30 @@ C: BEGIN +
+ Example of successful magic cookie authentication with successful negotiation of Unix FD passing + + (MAGIC_COOKIE is a made up mechanism) + + C: AUTH MAGIC_COOKIE 3138363935333137393635383634 + S: OK 1234deadbeef + C: NEGOTIATE_UNIX_FD + S: AGREE_UNIX_FD + C: BEGIN + +
+
+ Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing + + (MAGIC_COOKIE is a made up mechanism) + + C: AUTH MAGIC_COOKIE 3138363935333137393635383634 + S: OK 1234deadbeef + C: NEGOTIATE_UNIX_FD + S: ERROR + C: BEGIN + +
@@ -4078,4 +4188,3 @@ - -- cgit