1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
|
<?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: -->
|
