diff options
| -rw-r--r-- | spec/Channel_Interface_Tube.xml | 53 |
1 files changed, 42 insertions, 11 deletions
diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml index 858a15dd..f31ab213 100644 --- a/spec/Channel_Interface_Tube.xml +++ b/spec/Channel_Interface_Tube.xml @@ -204,15 +204,24 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. array-name="Socket_Access_Control_List"> <tp:enumvalue suffix="Localhost" value="0"> <tp:docstring> - The IP or Unix socket can be accessed by any local user (e.g. - a Unix socket that accepts all local connections, or an IP socket - listening on 127.0.0.1 (or ::1) or rejecting connections not from - that address). The associated variant must be ignored. + <p>The IP or Unix socket can be accessed by any local user (e.g. + a Unix socket that accepts all local connections, or an IP socket + listening on 127.0.0.1 (or ::1) or rejecting connections not from + that address). The associated variant must be ignored.</p> + + <p>For a D-Bus tube, this means that the "same user" access + control typically provided by default in D-Bus implementations + SHOULD be disabled. If the socket is only available to local users + (e.g. a Unix socket, an IPv4 socket bound to 127.0.0.1, or an + IPv6 socket bound to ::1), the <code>ANONYMOUS</code> + authentication mechanism MAY be enabled.</p> </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Port" value="1"> <tp:docstring> - May only be used on IP sockets. The associated variant must contain + May only be used on IP sockets, and only for Stream tubes. + <!-- ... and maybe Datagram tubes, one day... --> + The associated variant must contain a struct Socket_Address_IPv4 (or Socket_Address_IPv6) containing the string form of an IP address of the appropriate version, and a port number. The socket can only be accessed if the @@ -235,19 +244,41 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:enumvalue> <tp:enumvalue suffix="Credentials" value="3"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>May only be used on UNIX sockets. + <p>The high-level meaning of this access control type is that + only the same user (e.g. same numeric Unix uid) is allowed to + interact with the tube. Exactly how this is achieved varies by + channel type.</p> + + <p>For <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" + >StreamTube</tp:dbus-ref> channels, this access control type + may only be used on UNIX sockets. The connecting process must send a byte when it first connects, which is not considered to be part of the data stream. If the operating system uses sendmsg() with SCM_CREDS or SCM_CREDENTIALS to pass credentials over sockets, the connecting process must do so if possible; if not, it must still send the - byte.</p> + byte, without any attached credentials. (This mechanism is + very similar to the first byte of a D-Bus connection, except that + in D-Bus the byte is always zero, whereas in Tubes it can be + nonzero.)</p> + + <p>For <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" + >DBusTube</tp:dbus-ref> channels, this access control type + may be used on any type of socket, and there is no extra byte + added by Telepathy at the beginning of the stream: all bytes in + the stream are part of the D-Bus tube connection. The connecting + process should prove its identity via any of the SASL + authentication mechanisms usually used for D-Bus (in typical + D-Bus implementations this involves either sending and receiving + credentials as above, or demonstrating the ability to write to a + file in the user's home directory).</p> - <p>The listening process will disconnect the connection unless it - can determine by OS-specific means that the connecting process - has the same user ID as the listening process.</p> + <p>In either case, the listening process will disconnect the + connection unless it can determine by OS-specific means that + the connecting process has the same user ID as the listening + process.</p> - <p>The associated variant must be ignored.</p> + <p>In either tube type, the associated variant must be ignored.</p> </tp:docstring> </tp:enumvalue> </tp:enum> |