Add tube access control

20070823121556-53eee-7753b09e0522023c5830c39baa0d3705c20d8638.gz

1 files changed, 121 insertions, 3 deletions

diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml
index 9eb1c50c..04022602 100644
--- a/spec/Channel_Type_Tubes.xml
+++ b/spec/Channel_Type_Tubes.xml
@@ -125,6 +125,81 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
     </tp:enum>
 
+    <tp:enum name="Tube_Access_Control">
+      <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 contain the Boolean value
+          FALSE.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Port" value="1">
+        <tp:docstring>
+          May only be used on IP sockets. The associated variant must contain
+          a struct with signature (sq) containing the string form of an
+          IP address of the appropriate version, and a port number.
+          The socket can only be accessed if the connecting process has that
+          address and port number; all other connections will be rejected.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Netmask" value="2">
+        <tp:docstring>
+          May only be used on IP sockets. The associated variant must contain
+          a struct with signature (sy) containing the string form of an
+          IP address of the appropriate version, and a prefix length "n".
+          The socket can only be accessed if the first n bits of the
+          connecting address match the first n bits of the given address.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Credentials" value="3">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The connecting process must send a single zero (NUL) 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>
+
+          <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>The associated variant must contain the Boolean value FALSE.</p>
+        </tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
+    <method name="GetAvailableStreamTubeTypes">
+      <tp:docstring>List the available address types and access-control types
+        for stream tubes.</tp:docstring>
+      <arg direction="out" type="a{uau}">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>A mapping from address types (members of Tube_Address_Type) to
+          arrays of access-control type (members of Tube_Access_Control)
+          that the connection manager supports for stream tubes with that
+          address type. For simplicity, if a CM supports offering a
+          particular type of tube, it is assumed to support accepting it.</p>
+
+          <p>A typical value for a host without IPv6 support:</p>
+
+          <pre>
+            {
+              Tube_Address_Type_IPv4:
+                [Tube_Access_Control_Localhost, Tube_Access_Control_Port,
+                 Tube_Access_Control_Netmask],
+              Tube_Address_Type_Unix:
+                [Tube_Access_Control_Localhost, Tube_Access_Control_Credentials]
+            }
+          </pre>
+
+          <p>If stream tubes are not supported, this will be an empty
+            dictionary.</p>
+        </tp:docstring>
+      </arg>
+    </method>
+
     <method name="GetAvailableTubeTypes">
       <arg direction="out" type="au" tp:type="Tube_Type[]">
         <tp:docstring>
@@ -229,6 +304,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           address_type.
         </tp:docstring>
       </arg>
+      <arg direction="in" name="access_control" type="u" tp:type="Tube_Access_Control">
+        <tp:docstring>
+          The access control the local service applies to the local socket,
+          specified so the connection manager can behave appropriately
+          when it connects.
+        </tp:docstring>
+      </arg>
+      <arg direction="in" name="access_control_param" type="v">
+        <tp:docstring>
+          A parameter for the access control type, to be interpreted as
+          specified in the documentation for the Tube_Access_Control enum.
+        </tp:docstring>
+      </arg>
       <arg direction="out" type="u">
         <tp:docstring>
           The ID of the new tube.
@@ -244,7 +332,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
           <tp:docstring>
-            The connection manager doesn't support stream tubes.
+            The connection manager doesn't support stream tubes, or
+            does not support the given address type or access-control type.
           </tp:docstring>
         </tp:error>
       </tp:possible-errors>
@@ -305,7 +394,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         </tp:docstring>
       </arg>
       <tp:possible-errors>
-        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument" />
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            The given tube ID is invalid or does not refer to a D-Bus
+            tube.
+          </tp:docstring>
+        </tp:error>
       </tp:possible-errors>
     </method>
 
@@ -326,6 +420,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           The type of address the connection manager should listen on.
         </tp:docstring>
       </arg>
+      <arg direction="in" name="access_control" type="u" tp:type="Tube_Access_Control">
+        <tp:docstring>
+          The type of access control the connection manager should apply to
+          the socket.
+        </tp:docstring>
+      </arg>
+      <arg direction="in" name="access_control_param" type="v">
+        <tp:docstring>
+          A parameter for the access control type, to be interpreted as
+          specified in the documentation for the Tube_Access_Control enum.
+        </tp:docstring>
+      </arg>
       <arg direction="out" name="address" type="v">
         <tp:docstring>
           The address on which the connection manager will listen for
@@ -333,10 +439,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           to the address until the tube is open.
         </tp:docstring>
       </arg>
+
       <tp:possible-errors>
-        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument" />
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            The given tube ID is invalid or does not refer to a stream
+            tube.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+          <tp:docstring>
+            The given address type or access-control mechanism is not supported.
+          </tp:docstring>
+        </tp:error>
       </tp:possible-errors>
     </method>
+
     <signal name="TubeStateChanged">
       <tp:docstring>
         Emitted when the state of a tube changes.