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, 0 insertions, 723 deletions
diff --git a/qt4/spec/Channel_Interface_SASL_Authentication.xml b/qt4/spec/Channel_Interface_SASL_Authentication.xml deleted file mode 100644 index 7985a6bd5..000000000 --- a/qt4/spec/Channel_Interface_SASL_Authentication.xml +++ /dev/null @@ -1,723 +0,0 @@ -<?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: --> |