<?xml version="1.0" ?>
<node name="/Channel_Type_Server_TLS_Connection"
    xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright> Copyright © 2010 Collabora Limited </tp:copyright>
  <tp:license>
    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.

    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.

    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.
  </tp:license>

  <interface name="org.freedesktop.Telepathy.Channel.Type.ServerTLSConnection">
    <tp:added version="0.19.13">(as stable API)</tp:added>

    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>A channel type that carries a TLS certificate between a server
      and a client connecting to it.</p>
      <p>Channels of this kind always have <tp:dbus-ref
      namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> = False,
      <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
      = None and <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
      = 0, and cannot be requested with methods such as <tp:dbus-ref
      namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>.
      Also, they SHOULD be dispatched while the
      <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
      owning them is in the CONNECTING state.</p>
      <p>In this case, handlers SHOULD accept or reject the certificate, using
      the relevant methods on the provided object, or MAY just <tp:dbus-ref
      namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> the channel before doing so, to fall
      back to a non-interactive verification process done inside the CM.</p>
      <p>For example, channels of this kind can pop up while a client is
      connecting to an XMPP server.</p>
    </tp:docstring>

    <property name="ServerCertificate" type="o" access="read"
              tp:name-for-bindings="Server_Certificate"
              tp:immutable='yeah'>
      <tp:docstring>
        <p>A <tp:dbus-ref
        namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate</tp:dbus-ref>
        containing the certificate chain as sent by the server,
        and other relevant information.</p>
      </tp:docstring>
    </property>

    <property name="Hostname" type="s" access="read"
              tp:name-for-bindings="Hostname"
              tp:immutable='sharks'>
      <tp:added version="0.19.12"/>
      <tp:docstring>
        <p>The hostname or domain that the user expects to connect to. Clients
        SHOULD use the <tp:member-ref>ReferenceIdentities</tp:member-ref>
        property to verify the identity of the certificate. Clients MAY display
        this hostname to the user as the expected identity. Clients SHOULD use
        this property to lookup pinned certificates or other user preferences
        for the connection.</p>
      </tp:docstring>
    </property>

    <property name="ReferenceIdentities" type="as" access="read"
              tp:name-for-bindings="Reference_Identities"
              tp:immutable='plz'>
      <tp:added version="0.21.10">
        If this property is not present, clients SHOULD use the
        <tp:member-ref>Hostname</tp:member-ref> property as the reference
        identity to validate server certificates against.
      </tp:added>

      <tp:docstring>
        <p>The identities of the server we expect
        <tp:member-ref>ServerCertificate</tp:member-ref> to certify; clients
        SHOULD verify that <tp:member-ref>ServerCertificate</tp:member-ref>
        matches one of these identities when checking its validity.</p>

        <p>This property MUST NOT be the empty list; it MUST
        contain the value of the <tp:member-ref>Hostname</tp:member-ref>
        property. All other identities included in this property MUST be derived from
        explicit user input or choices, such as <tp:dbus-ref
        namespace='ofdT.Account'>Parameters</tp:dbus-ref> passed to
        <tp:dbus-ref
        namespace='ofdT.ConnectionManager'>RequestConnection</tp:dbus-ref>.</p>

        <tp:rationale>
          <p>The primary use for this property is for XMPP services hosted by
            <a href='http://www.google.com/apps/intl/en/business/gmail.html'>Google
            Apps</a>. When connecting to Google Talk using an
            <tt>@gmail.com</tt> JID, the server correctly presents a
            certificate for <tt>gmail.com</tt>; however, for domains hosted via
            Google Apps, a certificate for <tt>talk.google.com</tt> is
            offered, due to unresolved technical limitations.</p>

          <p>If the user has explicitly chosen to create a <q>Google Talk</q>
            account, then trusting a certificate for <tt>talk.google.com</tt>
            is reasonable. To handle this case, the connection manager may add
            the values of any or all of the <tt>server</tt>,
            <tt>fallback-server</tt> and <tt>extra-identities</tt> parameters;
            the Google Talk account creation user interface may set these
            parameters appropriately, or the user may set them for accounts
            with other services.</p>
        </tp:rationale>
      </tp:docstring>
    </property>

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