diff options
Diffstat (limited to 'qt4/spec/Channel_Interface_SASL_Authentication.xml')
| -rw-r--r-- | qt4/spec/Channel_Interface_SASL_Authentication.xml | 723 |
1 files changed, 723 insertions, 0 deletions
diff --git a/qt4/spec/Channel_Interface_SASL_Authentication.xml b/qt4/spec/Channel_Interface_SASL_Authentication.xml new file mode 100644 index 000000000..7985a6bd5 --- /dev/null +++ b/qt4/spec/Channel_Interface_SASL_Authentication.xml @@ -0,0 +1,723 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_SASL_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.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</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</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 + use this channel to let a user interface carry out a simple SASL-like + handshake with it, as a way to get the user's credentials + interactively. This can be used to connect to protocols that may + require a password, without requiring that the password is saved in + the <tp:dbus-ref + namespace="ofdT">Account.Parameters</tp:dbus-ref>.</p> + + <p>In some protocols, such as XMPP, authentication with the server + is also carried out using SASL. In these protocols, a channel with this + interface can provide a simple 1:1 mapping of the SASL negotiations + taking place in the protocol, allowing more advanced clients to + perform authentication via SASL mechanisms not known to the + connection manager.</p> + + <tp:rationale> + <p>By providing SASL directly when the protocol supports it, we can + use mechanisms like Kerberos or Google's <code>X-GOOGLE-TOKEN</code> + without specific support in the connection manager.</p> + </tp:rationale> + + <p>For channels managed by a + <tp:dbus-ref namespace="ofdT">ChannelDispatcher</tp:dbus-ref>, + only the channel's <tp:dbus-ref + namespace="ofdT.Client">Handler</tp:dbus-ref> may call the + methods on this interface. Other clients MAY observe the + authentication process by watching its signals and properties.</p> + + <tp:rationale> + <p>There can only be one Handler, which is a good fit for SASL's + 1-1 conversation between a client and a server.</p> + </tp:rationale> + </tp:docstring> + + <tp:simple-type name="SASL_Mechanism" type="s" + array-name="SASL_Mechanism_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A SASL mechanism, as defined by + <a href="http://tools.ietf.org/html/rfc4422">RFC 4422</a> + and registered in + <a href="http://www.iana.org/assignments/sasl-mechanisms">the + IANA registry of SASL mechanisms</a>, or an unregistered + SASL mechanism such as <code>X-GOOGLE-TOKEN</code> used in the + same contexts.</p> + + <p>As a special case, pseudo-mechanisms starting with + <code>X-TELEPATHY-</code> are defined by this specification. + Use of these pseudo-mechanisms indicates that the user's credentials + are to be passed to the connection manager, which will then use + them for authentication with the service, either by implementing + the client side of some SASL mechanisms itself or by using a + non-SASL protocol. The only such pseudo-mechanism currently + defined is <code>X-TELEPATHY-PASSWORD</code>.</p> + + <p>The <code>X-TELEPATHY-PASSWORD</code> mechanism is extremely + simple:</p> + + <ul> + <li>The client MUST call + <tp:member-ref>StartMechanismWithData</tp:member-ref>, with + Initial_Data set to the password encoded in UTF-8. + For simplicity, calling <tp:member-ref>StartMechanism</tp:member-ref> + followed by calling <tp:member-ref>Respond</tp:member-ref> is not + allowed in this mechanism.</li> + + <li>The connection manager uses the password, together with + authentication details from the Connection parameters, to + authenticate itself to the server.</li> + + <li>When the connection manager finishes its attempt to authenticate + to the server, the channel's state changes to + either SASL_Status_Server_Succeeded or + SASL_Status_Server_Failed as appropriate.</li> + </ul> + </tp:docstring> + </tp:simple-type> + + <property name="AvailableMechanisms" + tp:name-for-bindings="Available_Mechanisms" + type="as" tp:type="SASL_Mechanism[]" + access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The SASL mechanisms as offered by the server, plus any + pseudo-SASL mechanisms supported by the connection manager for + credentials transfer. For instance, in a protocol that + natively uses SASL (like XMPP), this might be + <code>[ "X-TELEPATHY-PASSWORD", "PLAIN", "DIGEST-MD5", + "SCRAM-SHA-1" ]</code>.</p> + + <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>, 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 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> + + <property name="CanTryAgain" tp:name-for-bindings="Can_Try_Again" + type="b" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, <tp:member-ref>StartMechanism</tp:member-ref> and (if + supported) <tp:member-ref>StartMechanismWithData</tp:member-ref> + can be expected to work when in one of the Failed states. If + false, the only thing you can do after failure is to close the + channel.</p> + + <tp:rationale> + <p>Retrying isn't required to work, although some protocols and + implementations allow it.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property type="u" tp:type="SASL_Status" access="read" + name="SASLStatus" tp:name-for-bindings="SASL_Status"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The current status of this channel. + Change notification is via the + <tp:member-ref>SASLStatusChanged</tp:member-ref> signal. + </tp:docstring> + </property> + + <property type="s" tp:type="DBus_Error_Name" access="read" + name="SASLError" tp:name-for-bindings="SASL_Error"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The reason for the <tp:member-ref>SASLStatus</tp:member-ref>, or + an empty string if the state is neither + Server_Failed nor Client_Failed.</p> + + <p>In particular, an ordinary authentication failure (as would + be produced for an incorrect password) SHOULD be represented by + <tp:error-ref>AuthenticationFailed</tp:error-ref>, + cancellation by the user's request SHOULD be represented + by <tp:error-ref>Cancelled</tp:error-ref>, and + cancellation by a local process due to inconsistent or invalid + challenges from the server SHOULD be represented by + <tp:error-ref>ServiceConfused</tp:error-ref>.</p> + + <p>If this interface appears on a <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 + namespace="ofdT">Connection.ConnectionError</tp:dbus-ref> + signal.</p> + </tp:docstring> + </property> + + <property name="SASLErrorDetails" + tp:name-for-bindings="SASL_Error_Details" + access="read" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If <tp:member-ref>SASLError</tp:member-ref> is non-empty, + any additional information about the last + disconnection; otherwise, the empty map. The keys and values are + the same as for the second argument of + <tp:dbus-ref + namespace="ofdT">Connection.ConnectionError</tp:dbus-ref>.</p> + + <p>If this interface appears on a <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 + namespace="ofdT">Connection.ConnectionError</tp:dbus-ref> + signal.</p> + </tp:docstring> + </property> + + <property name="AuthorizationIdentity" + tp:name-for-bindings="Authorization_Identity" + type="s" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The identity for which authorization is being attempted, + typically the 'account' from the <tp:dbus-ref + namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref> + parameters, normalized and formatted according to the + conventions used for SASL in this protocol.</p> + + <tp:rationale> + <p>The normalization used for SASL might not be the same + normalization used elsewhere: for instance, in a protocol + with email-like identifiers such as XMPP or SIP, the user + "juliet@example.com" might have to authenticate to the + example.com server via SASL PLAIN as "juliet".</p> + </tp:rationale> + + <p>This is usually achieved by using the authorization identity for + authentication, but an advanced Handler could offer the option + to authenticate under a different identity.</p> + + <p>The terminology used here is that the authorization identity + is who you want to act as, and the authentication identity is + used to prove that you may do so. For instance, if Juliet is + authorized to access a role account, "sysadmin@example.com", + and act on its behalf, it might be possible to authenticate + as "juliet@example.com" with her own password, but request to + be authorized as "sysadmin@example.com" instead of her own + account. See + <a href="http://tools.ietf.org/html/rfc4422#section-3.4.1">RFC + 4422 §3.4.1</a> for more details.</p> + + <tp:rationale> + <p>In SASL the authorization identity is normally guessed from + the authentication identity, but the information available + to the connection manager is the identity for which + authorization is required, such as the desired JID in XMPP, + so that's what we signal to UIs; it's up to the UI to + choose whether to authenticate as the authorization identity + or some other identity.</p> + + <p>As a concrete example, the "sysadmin" XMPP account mentioned + above would have <code>{ 'account': 'sysadmin@example.com' }</code> + in its Parameters, and this property would also be + 'sysadmin@example.com'. A simple Handler would + merely prompt for sysadmin@example.com's password, + and use that JID as both the authorization and authentication + identity, which might result in SASL PLAIN authentication with the + initial response + '\000sysadmin@example.com\000root'.</p> + + <p>A more advanced Handler might also ask for an authentication + identity, defaulting to 'sysadmin@example.com'; if Juliet + provided authentication identity 'juliet@example.com' and + password 'romeo', the Handler might perform SASL PLAIN + authentication using the initial response + 'sysadmin@example.com\000juliet@example.com\000romeo'.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="DefaultUsername" + tp:name-for-bindings="Default_Username" + type="s" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The default username for use with SASL mechanisms that deal + with a "simple username" (as defined in <a + href="http://tools.ietf.org/html/rfc4422">RFC 4422</a>). If + such a SASL mechanism is in use, clients SHOULD default to + using the DefaultUsername; also, if the client uses + the DefaultUsername, it SHOULD assume that the authorization + identity <tp:member-ref>AuthorizationIdentity</tp:member-ref> + will be derived from it by the server.</p> + + <tp:rationale> + <p>In XMPP, <a href="http://trac.tools.ietf.org/wg/xmpp/trac/ticket/49"> + servers typically expect</a> "user@example.com" to + authenticate with username "user"; this was a SHOULD in <a + href="http://tools.ietf.org/html/rfc3920">RFC 3920</a>.</p> + + <p><a + href="http://tools.ietf.org/html/draft-ietf-xmpp-3920bis-19">3920bis</a> + weakens that SHOULD to "in the absence of local information + provided by the server, an XMPP client SHOULD assume that + the authentication identity for such a SASL mechanism is the + combination of a user name and password, where the simple + user name is the localpart of the user's JID".</p> + </tp:rationale> + + <p>For example, in the simple case, if the user connects with + <tp:dbus-ref + namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>({ + account: "<tt>user@example.com</tt>" }) and use PLAIN with + password "password", he or she should authenticate like so: + "<tt>\0user\0password</tt>" and the channel will look like + this:</p> + +<blockquote><pre>{ "...<tp:member-ref>DefaultUsername</tp:member-ref>": "user", + "...<tp:member-ref>AuthorizationIdentity</tp:member-ref>": "user@example.com } +</pre></blockquote> + + <p>In the complex case, if the same user is using his or her + sysadmin powers to log in as the "announcements" role address, + he or she would connect with <tp:dbus-ref + namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>({ + account: "<tt>announcements@example.com</tt>" }) and the SASL + channel would look like this:</p> + +<blockquote><pre>{ "...<tp:member-ref>DefaultUsername</tp:member-ref>": "announcements", + "...<tp:member-ref>AuthorizationIdentity</tp:member-ref>": "announcements@example.com } +</pre></blockquote> + + <p>A sufficiently elaborate UI could give the opportunity + to override the username from "announcements" to "user". + The user's simple username is still "user", and the password is + still "password", but this time he or she is trying to authorize + to act as <tt>announcements@example.com</tt>, so the UI would + have to perform SASL PLAIN with this string: + "<tt>announcements@example.com\0user\0password</tt>", where + "announcements@example.com" is the + <tp:member-ref>AuthorizationIdentity</tp:member-ref>.</p> + </tp:docstring> + </property> + + <property name="DefaultRealm" tp:name-for-bindings="Default_Realm" + type="s" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The default realm (as defined in + <a href="http://tools.ietf.org/html/rfc2831#section-2.1.1">RFC + 2831</a>) to use for authentication, if the server does not + supply one.</p> + + <tp:rationale> + <p>The server is not required to provide a realm; if it doesn't, + the client is expected to ask the user or provide a sensible + default, typically the requested DNS name of the server. + In some implementations of <code>DIGEST-MD5</code>, the + server does not specify a realm, but expects that the client + will choose a particular default, and authentication will + fail if the client's default is different. Connection + managers for protocols where this occurs are more easily able + to work around these implementations than a generic client + would be.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="MaySaveResponse" tp:name-for-bindings="May_Save_Response" + type="b" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Whether or not the client can save the authentication response and + re-use it to automate future authentication challenges.</p> + + <p>If this property is <code>False</code>, the client SHOULD NOT attempt + to cache the authentication response in its own keyring.</p> + + <p>If this property is not specified, it should be treated as if it were + <code>True</code>.</p> + + <tp:rationale>Some protocols or services may have terms and conditions + that prohibit caching a user's credentials.</tp:rationale> + + </tp:docstring> + </property> + + + <method name="StartMechanism" tp:name-for-bindings="Start_Mechanism"> + <arg direction="in" name="Mechanism" type="s" tp:type="SASL_Mechanism"> + <tp:docstring> + The chosen mechanism. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Start an authentication try using <var>Mechanism</var>, without + sending initial data (an "initial response" as defined in RFC + 4422).</p> + + <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><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code> + in "initial authentication" mode.</p> + </tp:rationale> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The channel is not in a state where starting authentication makes + sense (i.e. SASL_Status_Not_Started, or (if + <tp:member-ref>CanTryAgain</tp:member-ref> is true) + SASL_Status_Server_Failed or + SASL_Status_Client_Failed). You should call + <tp:member-ref>AbortSASL</tp:member-ref> and wait for + SASL_Status_Client_Failed before starting another attempt. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The server or connection manager doesn't implement the given + SASL mechanism. Choose a SASL mechanism from + <tp:member-ref>AvailableMechanisms</tp:member-ref>, or abort + authentication if none of them are suitable. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="StartMechanismWithData" + tp:name-for-bindings="Start_Mechanism_With_Data"> + <arg direction="in" name="Mechanism" type="s" tp:type="SASL_Mechanism"> + <tp:docstring> + The chosen mechanism. + </tp:docstring> + </arg> + <arg direction="in" name="Initial_Data" type="ay"> + <tp:docstring> + Initial data (an "initial response" in RFC 4422's terminology) to send + with the mechanism. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Start an authentication try using <var>Mechanism</var>, and send + <var>Initial_Data</var> as the "initial response" defined in + <a href="http://tools.ietf.org/html/rfc4422#section-3.3">RFC 4422 + §3.3</a>.</p> + + <tp:rationale> + <p>This method is appropriate for mechanisms where the client may + 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 + (<tp:member-ref>StartMechanism</tp:member-ref>) and a zero-byte + 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> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The channel is not in a state where starting authentication makes + sense (i.e. SASL_Status_Not_Started, or (if + <tp:member-ref>CanTryAgain</tp:member-ref> is true) + SASL_Status_Server_Failed or + SASL_Status_Client_Failed). You should call + <tp:member-ref>AbortSASL</tp:member-ref> and wait for + SASL_Status_Client_Failed before starting another attempt. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The server or connection manager doesn't implement the given + SASL mechanism (choose one from + <tp:member-ref>AvailableMechanisms</tp:member-ref>, or abort + authentication if none of them are suitable), or doesn't allow + initial data to be sent (as indicated by + <tp:member-ref>HasInitialData</tp:member-ref>; call + <tp:member-ref>StartMechanism</tp:member-ref> instead). + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Respond" tp:name-for-bindings="Respond"> + <arg direction="in" name="Response_Data" type="ay"> + <tp:docstring> + The response data. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Send a response to the the last challenge received via + <tp:member-ref>NewChallenge</tp:member-ref>.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + Either the state is not In_Progress, or no challenge has been + received yet, or you have already responded to the last challenge. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <method name="AcceptSASL" tp:name-for-bindings="Accept_SASL"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If the channel's status is SASL_Status_Server_Succeeded, + this method confirms successful authentication and advances + the status of the channel to SASL_Status_Succeeded.</p> + + <p>If the channel's status is SASL_Status_In_Progress, calling this + method indicates that the last + <tp:member-ref>NewChallenge</tp:member-ref> signal was in fact + additional data sent after a successful SASL negotiation, and + declares that from the client's point of view, authentication + was successful. This advances the state of the channel to + SASL_Status_Client_Accepted.</p> + + <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</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> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + Either the state is neither In_Progress nor Server_Succeeded, or no + challenge has been received yet, or you have already responded to + the last challenge. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <method name="AbortSASL" tp:name-for-bindings="Abort_SASL"> + <arg direction="in" name="Reason" type="u" tp:type="SASL_Abort_Reason"> + <tp:docstring> + Reason for abort. + </tp:docstring> + </arg> + <arg direction="in" name="Debug_Message" type="s"> + <tp:docstring> + Debug message for abort. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Abort the current authentication try.</p> + + <p>If the current status is SASL_Status_Server_Failed or + SASL_Status_Client_Failed, this method returns successfully, but has + no further effect. If the current status is SASL_Status_Succeeded + or SASL_Status_Client_Accepted then NotAvailable is raised. + Otherwise, it changes the channel's state to + SASL_Status_Client_Failed, with an appropriate error name and + reason code.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The current state is either Succeeded or Client_Accepted. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="SASLStatusChanged" tp:name-for-bindings="SASL_Status_Changed"> + <tp:docstring> + Emitted when the status of the channel changes. + </tp:docstring> + <arg type="u" tp:type="SASL_Status" name="Status"> + <tp:docstring> + The new value of <tp:member-ref>SASLStatus</tp:member-ref>. + </tp:docstring> + </arg> + <arg type="s" tp:type="DBus_Error_Name" name="Reason"> + <tp:docstring> + The new value of <tp:member-ref>SASLError</tp:member-ref>. + </tp:docstring> + </arg> + <arg type="a{sv}" tp:type="String_Variant_Map" name="Details"> + <tp:docstring> + The new value of <tp:member-ref>SASLErrorDetails</tp:member-ref>. + </tp:docstring> + </arg> + </signal> + + <signal name="NewChallenge" tp:name-for-bindings="New_Challenge"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a new challenge is received from the server, or when + a message indicating successful authentication and containing + additional data is received from the server.</p> + + <p>When the channel's handler is ready to proceed, it should respond + to the challenge by calling <tp:member-ref>Respond</tp:member-ref>, + or respond to the additional data by calling + <tp:member-ref>AcceptSASL</tp:member-ref>. Alternatively, it may call + <tp:member-ref>AbortSASL</tp:member-ref> to abort authentication.</p> + </tp:docstring> + <arg name="Challenge_Data" type="ay"> + <tp:docstring> + The challenge data or additional data from the server. + </tp:docstring> + </arg> + </signal> + + <tp:enum name="SASL_Abort_Reason" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A reason why SASL authentication was aborted by the client.</p> + </tp:docstring> + + <tp:enumvalue suffix="Invalid_Challenge" value="0"> + <tp:docstring> + The server sent an invalid challenge or data. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="User_Abort" value="1"> + <tp:docstring> + The user aborted the authentication. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="SASL_Status" type="u" plural="SASL_Statuses"> + <tp:enumvalue suffix="Not_Started" value="0"> + <tp:docstring> + The initial state. The Handler SHOULD either + call <tp:member-ref>AbortSASL</tp:member-ref>, or connect to the + <tp:member-ref>NewChallenge</tp:member-ref> signal then call + <tp:member-ref>StartMechanism</tp:member-ref> or + <tp:member-ref>StartMechanismWithData</tp:member-ref>. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="In_Progress" value="1"> + <tp:docstring> + The challenge/response exchange is in progress. The Handler SHOULD + call either <tp:member-ref>Respond</tp:member-ref> or + <tp:member-ref>AcceptSASL</tp:member-ref> exactly once per emission + of <tp:member-ref>NewChallenge</tp:member-ref>, or call + <tp:member-ref>AbortSASL</tp:member-ref> at any time. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Server_Succeeded" value="2"> + <tp:docstring> + The server has indicated successful authentication, and the + connection manager is waiting for confirmation from the Handler. + The Handler must call either <tp:member-ref>AcceptSASL</tp:member-ref> or + <tp:member-ref>AbortSASL</tp:member-ref> to indicate whether it + considers authentication to have been successful. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Client_Accepted" value="3"> + <tp:docstring> + The Handler has indicated successful authentication, and the + connection manager is waiting for confirmation from the server. + The state will progress to either Succeeded or Server_Failed when + confirmation is received. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Succeeded" value="4"> + <tp:docstring> + Everyone is happy (the server sent success, and the client has called + <tp:member-ref>AcceptSASL</tp:member-ref>). Connection to the server + will proceed as soon as this state is reached. The Handler SHOULD + call <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> + to close the channel. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Server_Failed" value="5"> + <tp:docstring> + The server has indicated an authentication failure. + If <tp:member-ref>CanTryAgain</tp:member-ref> is true, + the client may try to authenticate again, by calling + <tp:member-ref>StartMechanism</tp:member-ref> or + <tp:member-ref>StartMechanismWithData</tp:member-ref> again. + Otherwise, it should give up completely, by calling <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> + on the channel. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Client_Failed" value="6"> + <tp:docstring> + The client has indicated an authentication failure. The + possible actions are the same as for Server_Failed. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |