Update to spec 0.21.5's stable version of ServerAuthentication etc.

Reviewed-by: Jonny Lamb <jonny.lamb@collabora.co.uk>

4 files changed, 63 insertions, 36 deletions

diff --git a/extensions/Channel_Interface_SASL_Authentication.xml b/extensions/Channel_Interface_SASL_Authentication.xml
index 355b7ce35..38568b1dd 100644
--- a/extensions/Channel_Interface_SASL_Authentication.xml
+++ b/extensions/Channel_Interface_SASL_Authentication.xml
@@ -17,21 +17,20 @@ Lesser General Public License for more details.</p>
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
   </tp:license>
-  <interface name="org.freedesktop.Telepathy.Channel.Interface.SASLAuthentication.DRAFT2"
-      tp:causes-havoc="experimental">
-    <tp:added version="0.21.UNRELEASED">(draft 2)</tp:added>
+  <interface name="org.freedesktop.Telepathy.Channel.Interface.SASLAuthentication">
+    <tp:added version="0.21.5">(as stable API)</tp:added>
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>A channel interface for SASL authentication,
         as defined by
         <a href="http://tools.ietf.org/html/rfc4422">RFC 4422</a>.
         When this interface appears on a <tp:dbus-ref
-          namespace="ofdT.Channel.Type">ServerAuthentication.DRAFT2</tp:dbus-ref>
+          namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
         channel, it represents authentication with the server. In future,
         it could also be used to authenticate with secondary services,
         or even to authenticate end-to-end connections with contacts. As a result,
         this interface does not REQUIRE <tp:dbus-ref namespace="ofdT.Channel.Type"
-        >ServerAuthentication.DRAFT2</tp:dbus-ref> to allow for a potential future
+        >ServerAuthentication</tp:dbus-ref> to allow for a potential future
         Channel.Type.PeerAuthentication interface.</p>
 
       <p>In any protocol that requires a password, the connection manager can
@@ -126,17 +125,25 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <p>To make it possible to implement a very simple password-querying
           user interface without knowledge of any particular SASL mechanism,
           implementations of this interface MUST implement the
-          pseudo-mechanism <code>X-TELEPATHY-PASSWORD</code>.</p>
+          pseudo-mechanism <code>X-TELEPATHY-PASSWORD</code>, unless none
+          of the available mechanisms use a password at all.</p>
       </tp:docstring>
     </property>
 
     <property name="HasInitialData" tp:name-for-bindings="Has_Initial_Data"
       type="b" access="read" tp:immutable="yes">
-      <tp:docstring>
-        If true, <tp:member-ref>StartMechanismWithData</tp:member-ref>
-        can be expected to work (this is the case in most, but not all,
-        protocols). If false, <tp:member-ref>StartMechanism</tp:member-ref>
-        must be used instead.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>If true, <tp:member-ref>StartMechanismWithData</tp:member-ref>
+          can be expected to work for SASL mechanisms not starting with
+          <code>X-TELEPATHY-</code> (this is the case in most, but not all,
+          protocols). If false, <tp:member-ref>StartMechanism</tp:member-ref>
+          must be used instead.</p>
+
+        <p>This property does not affect the <code>X-TELEPATHY-</code>
+          pseudo-mechanisms such as <code>X-TELEPATHY-PASSWORD</code>,
+          which can use
+          <tp:member-ref>StartMechanismWithData</tp:member-ref> regardless
+          of the value of this property.</p>
       </tp:docstring>
     </property>
 
@@ -182,7 +189,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           <tp:error-ref>ServiceConfused</tp:error-ref>.</p>
 
         <p>If this interface appears on a <tp:dbus-ref
-            namespace="ofdT.Channel.Type">ServerAuthentication.DRAFT2</tp:dbus-ref>
+            namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
           channel, and connection to the server fails with an authentication
           failure, this error code SHOULD be copied into the
           <tp:dbus-ref
@@ -203,7 +210,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
             namespace="ofdT">Connection.ConnectionError</tp:dbus-ref>.</p>
 
         <p>If this interface appears on a <tp:dbus-ref
-            namespace="ofdT.Channel.Type">ServerAuthentication.DRAFT2</tp:dbus-ref>
+            namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
           channel, and connection to the server fails with an authentication
           failure, these details SHOULD be copied into the
           <tp:dbus-ref
@@ -374,7 +381,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <tp:rationale>
           <p>This method is appropriate for mechanisms where the client
             cannot send anything until it receives a challenge from the
-            server, such as <code>DIGEST-MD5</code>.</p>
+            server, such as
+            <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code>
+            in "initial authentication" mode.</p>
         </tp:rationale>
       </tp:docstring>
 
@@ -421,12 +430,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           <a href="http://tools.ietf.org/html/rfc4422#section-3.3">RFC 4422
             §3.3</a>.</p>
 
-        <p>If the underlying protocol does not make it possible to send
-          initial data, this method will fail.</p>
-
         <tp:rationale>
           <p>This method is appropriate for mechanisms where the client may
-            send data first, such as <code>PLAIN</code>.</p>
+            send data first, such as <code>PLAIN</code>, or must send data
+            first, such as
+            <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code>
+            in "subsequent authentication" mode.</p>
 
           <p>Having two methods allows any mechanism where it makes a difference
             to distinguish between the absence of an initial response
@@ -434,6 +443,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
             initial response (StartMechanismWithData, with Initial_Data
             empty).</p>
         </tp:rationale>
+
+        <p>If the <tp:member-ref>HasInitialData</tp:member-ref>
+          property is false, this indicates that the underlying protocol
+          does not make it possible to send initial data. In such protocols,
+          this method may only be used for the <code>X-TELEPATHY-</code>
+          pseudo-mechanisms (such as <code>X-TELEPATHY-PASSWORD</code>),
+          and will fail if used with an ordinary SASL mechanism.</p>
+
+        <tp:rationale>
+          <p>For instance, the IRC SASL extension implemented in Charybdis and
+            Atheme does not support initial data - the first message in the
+            exchange only carries the mechanism. This is significant if using
+            <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code>,
+            which cannot be used in the faster "subsequent authentication"
+            mode on a protocol not supporting initial data.</p>
+        </tp:rationale>
       </tp:docstring>
 
       <tp:possible-errors>
@@ -502,7 +527,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <p>In mechanisms where the server authenticates itself to the client,
           calling this method indicates that the client considers this to have
           been successful. In the case of <tp:dbus-ref
-            namespace="ofdT.Channel.Type">ServerAuthentication.DRAFT2</tp:dbus-ref>
+            namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
           channels, this means that the connection manager MAY continue to
           connect, and MAY advance the <tp:dbus-ref
             namespace="ofdT">Connection.Status</tp:dbus-ref> to Connected.</p>
diff --git a/extensions/Channel_Interface_Securable.xml b/extensions/Channel_Interface_Securable.xml
index fbf882b28..d9d971394 100644
--- a/extensions/Channel_Interface_Securable.xml
+++ b/extensions/Channel_Interface_Securable.xml
@@ -20,10 +20,8 @@
       USA.</p>
   </tp:license>
 
-  <interface
-    name="org.freedesktop.Telepathy.Channel.Interface.Securable.DRAFT"
-    tp:causes-havoc="experimental">
-    <tp:added version="0.21.UNRELEASED">as a draft</tp:added>
+  <interface name="org.freedesktop.Telepathy.Channel.Interface.Securable">
+    <tp:added version="0.21.5">as stable API</tp:added>
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -32,14 +30,14 @@
         properties are sometimes immutable and can be used to make
         decisions on how cautious to be about transferring sensitive
         data. The special case of <tp:dbus-ref
-        namespace="ofdT.Channel.Type">ServerAuthentication.DRAFT2</tp:dbus-ref>
+        namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
         channels is one example of where the two properties are
         immutable.</p>
 
       <p>For example, clients MAY use these properties to decide
         whether the <code>PLAIN</code> mechanism is acceptable for a
         <tp:dbus-ref
-        namespace="ofdT.Channel.Interface">SASLAuthentication.DRAFT2</tp:dbus-ref>
+        namespace="ofdT.Channel.Interface">SASLAuthentication</tp:dbus-ref>
         channel.</p>
     </tp:docstring>
 
diff --git a/extensions/Channel_Type_Server_Authentication.xml b/extensions/Channel_Type_Server_Authentication.xml
index e394b4e3d..76599aa35 100644
--- a/extensions/Channel_Type_Server_Authentication.xml
+++ b/extensions/Channel_Type_Server_Authentication.xml
@@ -16,9 +16,8 @@ Lesser General Public License for more details.</p>
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
   </tp:license>
-  <interface name="org.freedesktop.Telepathy.Channel.Type.ServerAuthentication.DRAFT2"
-    tp:causes-havoc="experimental">
-    <tp:added version="0.21.UNRELEASED">(draft 2)</tp:added>
+  <interface name="org.freedesktop.Telepathy.Channel.Type.ServerAuthentication">
+    <tp:added version="0.21.5">(as stable API)</tp:added>
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -27,7 +26,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         the additional interface named in
         <tp:member-ref>AuthenticationMethod</tp:member-ref>,
         such as <tp:dbus-ref namespace="ofdT"
-          >Channel.Interface.SASLAuthentication.DRAFT2</tp:dbus-ref>.</p>
+          >Channel.Interface.SASLAuthentication</tp:dbus-ref>.</p>
 
       <p>Future authentication steps also supported by this channel type might
         include solving a captcha and/or agreeing to an EULA or terms-of-use
@@ -35,9 +34,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         type, but a different
         <tp:member-ref>AuthenticationMethod</tp:member-ref>.</p>
 
-      <p>Channels of this type SHOULD be signalled and dispatched while the
-        <tp:dbus-ref namespace="ofdT">Connection</tp:dbus-ref> owning them is in
-        the CONNECTING state. Normally, only one channel of this type will
+      <p>Channels of this type will normally be be signalled and dispatched
+        while the <tp:dbus-ref namespace="ofdT">Connection</tp:dbus-ref>
+        owning them is in the CONNECTING state. They MAY also appear on a
+        Connection in the CONNECTED state, for instance if periodic
+        re-authentication is required.</p>
+
+      <p>Normally, only one channel of this type will
         exist on a given Connection; if there is more than one, the handler
         must complete authentication with each of them in turn.</p>
 
@@ -52,12 +55,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
         = 0.</p>
 
-      <p>The Connection MUST NOT proceed with connection, or signal
+      <p>While it is CONNECTING, the Connection MUST NOT proceed with
+        connection, or signal
         <tp:dbus-ref namespace="ofdT.Connection">StatusChanged</tp:dbus-ref>
         to the CONNECTED state, until each channel of this type has either
         been accepted as having a positive result (for instance, on SASL
         channels this is done with the <tp:dbus-ref
-          namespace="ofdT.Channel.Interface.SASLAuthentication.DRAFT2"
+          namespace="ofdT.Channel.Interface.SASLAuthentication"
           >AcceptSASL</tp:dbus-ref> method), or closed with the <tp:dbus-ref
           namespace="ofdT.Channel">Close</tp:dbus-ref> method.</p>
 
@@ -108,7 +112,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
         <p>The initially-defined interface that can be used here is
           <tp:dbus-ref namespace="ofdT"
-            >Channel.Interface.SASLAuthentication.DRAFT2</tp:dbus-ref>.</p>
+            >Channel.Interface.SASLAuthentication</tp:dbus-ref>.</p>
       </tp:docstring>
     </property>
 
diff --git a/extensions/Connection_Interface_Power_Saving.xml b/extensions/Connection_Interface_Power_Saving.xml
index d96903251..571bf6d51 100644
--- a/extensions/Connection_Interface_Power_Saving.xml
+++ b/extensions/Connection_Interface_Power_Saving.xml
@@ -20,7 +20,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
   </tp:license>
   <interface
     name="org.freedesktop.Telepathy.Connection.Interface.PowerSaving">
-    <tp:added version="0.21.UNRELEASED">(as stable API)</tp:added>
+    <tp:added version="0.21.5">(as stable API)</tp:added>
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>Some protocols support mechanisms for reducing bandwidth usage—and
         hence power usage, on mobile devices—when the user is not directly