<?xml version="1.0" ?>
<node name="/Channel_Type_Server_Authentication" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright> Copyright © 2010 Collabora Limited </tp:copyright>
  <tp:license xmlns="http://www.w3.org/1999/xhtml">
    <p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.</p>

<p>This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.</p>

<p>You should have received a copy of the GNU Lesser General Public
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">
    <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>The type for a channel representing an authentication step with the
        server. The actual authentication functionality is implemented by
        the additional interface named in
        <tp:member-ref>AuthenticationMethod</tp:member-ref>,
        such as <tp:dbus-ref namespace="ofdT"
          >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
        document; each of these would be represented by a channel with this
        type, but a different
        <tp:member-ref>AuthenticationMethod</tp:member-ref>.</p>

      <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>

      <p>Channels of this type cannot be requested with methods such as
        <tp:dbus-ref
          namespace="ofdT.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>.
        They always have <tp:dbus-ref
          namespace="ofdT.Channel">Requested</tp:dbus-ref> = False,
        <tp:dbus-ref
          namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref> = None
        and <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
        = 0.</p>

      <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"
          >AcceptSASL</tp:dbus-ref> method), or closed with the <tp:dbus-ref
          namespace="ofdT.Channel">Close</tp:dbus-ref> method.</p>

      <tp:rationale>
        <p>ServerAuthentication channels normally represent the client
          authenticating itself to the server, but can also be used for the
          server to authenticate itself to the client (i.e. prove that it is
          in fact the desired server and not an imposter). Until the
          authentication handler has confirmed this, connection should not
          continue.</p>
      </tp:rationale>

      <p>If a channel of this type is closed with the <tp:dbus-ref
            namespace="ofdT.Channel">Close</tp:dbus-ref> method before
        authentication has succeeded, this indicates that the Handler has
        given up its attempts to authenticate or that no Handler is
        available.</p>

      <p>If this occurs, the connection manager MAY attempt to continue
        connection (for instance, performing SASL authentication by using any
        credentials passed to <tp:dbus-ref
          namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>,
        for instance from the <tp:dbus-ref
          namespace="ofdT">Account.Parameters</tp:dbus-ref>). If this fails
        or has already been tried, the <tp:dbus-ref
          namespace="ofdT">Connection</tp:dbus-ref> will
        disconnect.</p>

      <tp:rationale>
        <p>In particular, the <tp:dbus-ref
            namespace="ofdT">ChannelDispatcher</tp:dbus-ref> will close the
          channel if it cannot find a handler.</p>
      </tp:rationale>

      <p>When the connection is done with the channel and it is no
        longer needed, it is left open until either the connection state
        turns to DISCONNECTED or the handler closes the channel. The
        channel SHOULD NOT close itself once finished with.</p>
    </tp:docstring>

    <property name="AuthenticationMethod"
              tp:name-for-bindings="Authentication_Method"
              type="s" tp:type="DBus_Interface" access="read">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>This property defines the method used for the authentication step
          represented by this channel, which MUST be one of this channel's
          <tp:dbus-ref namespace="ofdT.Channel">Interfaces</tp:dbus-ref>.</p>

        <p>The initially-defined interface that can be used here is
          <tp:dbus-ref namespace="ofdT"
            >Channel.Interface.SASLAuthentication</tp:dbus-ref>.</p>
      </tp:docstring>
    </property>

  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
