diff options
author | Andre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk> | 2011-11-21 12:16:32 -0200 |
---|---|---|
committer | Andre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk> | 2011-11-21 12:16:36 -0200 |
commit | 668ea7945473598671fa9bfc886470def4e9ba05 (patch) | |
tree | 91761edb5619d74f3616f6453829a04d5256fa00 /spec | |
parent | 10f6aa5bdd4dee7aa44e27e845eaf96c66b551c4 (diff) | |
parent | 080c79ee1fc94afddd1213e19515cead86606a76 (diff) |
Merge remote-tracking branch 'smcv/protocol-addressing'
Reviewed-by: Andre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk>
Diffstat (limited to 'spec')
-rw-r--r-- | spec/spec/Channel_Interface_Tube.xml | 53 | ||||
-rw-r--r-- | spec/spec/Channel_Type_DBus_Tube.xml | 12 | ||||
-rw-r--r-- | spec/spec/Protocol_Interface_Addressing.xml | 57 |
3 files changed, 101 insertions, 21 deletions
diff --git a/spec/spec/Channel_Interface_Tube.xml b/spec/spec/Channel_Interface_Tube.xml index 858a15dd9..f31ab2138 100644 --- a/spec/spec/Channel_Interface_Tube.xml +++ b/spec/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> diff --git a/spec/spec/Channel_Type_DBus_Tube.xml b/spec/spec/Channel_Type_DBus_Tube.xml index 961576319..74e659514 100644 --- a/spec/spec/Channel_Type_DBus_Tube.xml +++ b/spec/spec/Channel_Type_DBus_Tube.xml @@ -174,7 +174,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A list of the access control types that are supported with this channel. Note that only Socket_Access_Control_Localhost and - Socket_Access_Control_Credentials can be used with D-Bus tubes.</p> + Socket_Access_Control_Credentials can be used with D-Bus tubes. + Using Socket_Access_Control_Credentials is recommended.</p> + + <tp:rationale> + <p>Socket_Access_Control_Credentials is easy to implement for a + D-Bus tube, because typical D-Bus library implementations like + libdbus and GDBus already have to support it to be able to + connect to the system or session bus, and usually enable it + by default; so there's typically no good reason to relax + access control to Localhost.</p> + </tp:rationale> <p>When requesting a channel with <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, diff --git a/spec/spec/Protocol_Interface_Addressing.xml b/spec/spec/Protocol_Interface_Addressing.xml index 3722c3b81..ad406c8df 100644 --- a/spec/spec/Protocol_Interface_Addressing.xml +++ b/spec/spec/Protocol_Interface_Addressing.xml @@ -24,6 +24,7 @@ name="org.freedesktop.Telepathy.Protocol.Interface.Addressing.DRAFT" tp:causes-havoc="experimental"> <tp:added version="0.19.12">(as draft)</tp:added> + <tp:changed version="0.25.UNRELEASED">(renamed NormalizeURI)</tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An interface for protocols that support multiple forms of addressing contacts, for example through vCard addresses and URIs.</p> @@ -217,7 +218,8 @@ AddressableURISchemes=tel;sip; <arg direction="in" name="VCard_Address" type="s"> <tp:docstring> - The address to normalize. + The address to normalize, which is assumed to belong to a + contact (and not, for instance, a chatroom or server). </tp:docstring> </arg> @@ -243,8 +245,9 @@ AddressableURISchemes=tel;sip; </tp:possible-errors> </method> - <method name="NormalizeURI" - tp:name-for-bindings="Normalize_URI"> + <method name="NormalizeContactURI" + tp:name-for-bindings="Normalize_Contact_URI"> + <tp:added version="0.25.UNRELEASED">(renamed from NormalizeURI)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Attempt to normalize the given contact URI. Where possible, this SHOULD return an address that would appear in the @@ -258,8 +261,28 @@ AddressableURISchemes=tel;sip; namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, this method SHOULD perform a best-effort normalization.</p> - <p>Example: <code>xmpp:eitan@EXAMPLE.COM</code> would be normalized to - <code>xmpp:eitan@example.com</code>.</p> + <p>If the URI has extra information beyond what's necessary to + identify a particular contact, such as an XMPP resource or an + action to carry out, this extra information SHOULD be removed. + If all URIs in a scheme contain a verb or action + (like <code>aim</code>, <code>ymsgr</code> and + <code>msnim</code> URIs), then the verb SHOULD be replaced + with the one specified in + <tp:member-ref>AddressableURISchemes</tp:member-ref>.</p> + + <tp:rationale> + <p>This method is intended to normalize URIs stored in address + books, for instance. In protocols like XMPP, if you + vary the resource or action (query string), the URI still + refers to the same high-level contact.</p> + </tp:rationale> + + <p>For instance, + <code>xmpp:romeo@Example.Com/Empathy?message;body=Hello</code> + would be normalized to <code>xmpp:romeo@example.com</code>, + and <code>aim:goim?screenname=Romeo%20M&message=Hello</code> + would be normalized to + <code>aim:addbuddy?screenname=romeom</code>.</p> <p>This method MAY simply raise NotImplemented on some protocols, if it has no use.</p> @@ -267,9 +290,18 @@ AddressableURISchemes=tel;sip; <arg direction="in" name="URI" type="s"> <tp:docstring> - The URI to normalize. The URI's scheme (i.e. the part before - the first colon) MUST appear in - <tp:member-ref>AddressableURISchemes</tp:member-ref>. + <p>The URI to normalize, which is assumed to refer to a contact + (as opposed to, for instance, a chatroom or a server).</p> + + <tp:rationale> + <p>In some protocols, like XMPP, there is no way to tell whether + a given URI refers to a contact or a chatroom by looking at + its syntax.</p> + </tp:rationale> + + <p>The URI's scheme (i.e. the part before + the first colon) MUST appear in + <tp:member-ref>AddressableURISchemes</tp:member-ref>.</p> </tp:docstring> </arg> @@ -289,7 +321,14 @@ AddressableURISchemes=tel;sip; <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> <tp:docstring> - The URI is syntactically incorrect. + <p>The URI is syntactically incorrect or cannot be interpreted + as a reference to a contact.</p> + + <tp:rationale> + <p>For instance, <code>aim:!?</code> is not a valid AIM URI, + while <code>aim:goaway?message=Absent</code> is a + valid AIM URI, but not a contact.</p> + </tp:rationale> </tp:docstring> </tp:error> </tp:possible-errors> |