Interface org.freedesktop.Telepathy.Channel.Interface.SASLAuthentication.DRAFT

Interface Index (Compact) | Summary | Description | Methods | Signals | Properties | Types

Methods

StartMechanism (s: Mechanism, ay: Initial_Data) → nothing
Respond (ay: Response_Data) → nothing
Accept () → nothing
Abort (u: Reason, s: Debug_Message) → nothing

Signals

StateChanged (u: Status, s: Reason, s: Debug_Message)
NewChallenge (ay: Challenge_Data)

Properties

AvailableMechanisms as (SASL_Mechanism_List) Read only
Secure b Read only
CurrentChallenge ay Read only
CurrentState (uss) (SASL_State) Read only

Types

SASL_Mechanism Simple Type s
Abort_Reason Enum u
SASL_Status Enum u
SASL_State Struct (uss)
WARNING: This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Do not include this interface in libraries that care about compatibility.
Objects implementing this interface must also implement:

Description

A channel interface for SASL authentication, as defined by RFC 4422.

In some protocols, such as XMPP, authentication with the server is 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.

In other protocols, the connection manager can require that a user interface authenticate with it via SASL as a way to get the user's credentials interactively. In particular, this can be used to connect to protocols that may require a password, without requiring that the password is saved in the Account.Parameters.

By providing SASL directly when the protocol supports it, we can use mechanisms like Kerberos or Google's X-GOOGLE-TOKEN without specific support in the connection manager.

Protocols where SASL is not used typically have a simple username/password-based authentication mechanism. In these protocols, we can use the same authentication client to query the user's password (either interactively, or from a storage mechanism like gnome-keyring), by having the connection manager implement the server side of a simple SASL mechanism like PLAIN.

Methods

(Permalink)

StartMechanism (s: Mechanism, ay: Initial_Data) → nothing

Parameters

  • Mechanism — s (SASL_Mechanism)
    • The chosen mechanism.
  • Initial_Data — ay
    • Initial data to send with the mechanism.
Start an authentication try using Mechanism. If the choosen SASL mechanism is client-first then the first data must be passed in Initial_Data, otherwise Initial_Data must be an empty array.
(Permalink)

Respond (ay: Response_Data) → nothing

Parameters

  • Response_Data — ay
    • The response data.
Send our response to the the CurrentChallenge, if required.
(Permalink)

Accept () → nothing

Handler accepts the authentication as finished. Can be called whenever the Handler considered the authentication process to be (successfully) finished from its point of view.
(Permalink)

Abort (u: Reason, s: Debug_Message) → nothing

Parameters

  • Reason — u (Abort_Reason)
    • Reason for abort.
  • Debug_Message — s
    • Debug message for abort.
Abort the current authentication try.

Signals

(Permalink)

StateChanged (u: Status, s: Reason, s: Debug_Message)

Parameters

  • Status — u (SASL_Status)
    • The status of the state.
  • Reason — s (DBus_Error_Name)
    • The reason for the state.
  • Debug_Message — s
    • A non-localized debug message.
Notifies of CurrentState changing
(Permalink)

NewChallenge (ay: Challenge_Data)

Parameters

  • Challenge_Data — ay
    • The challenge data from the server.
Recieved a new challenge from the server.

Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

AvailableMechanisms — as (SASL_Mechanism_List)

Read only
The SASL mechanisms as offered by the server, such as [ "PLAIN", "DIGEST-MD5", "SCRAM-SHA-1" ].
(Permalink)

Secure — b

Read only
Is this exchange secure (ie. TLS)? Good to know if you need to take a calculated risk with plaintext.
(Permalink)

CurrentChallenge — ay

Read only
The current challenge from the server. change notification via NewChallenge. The handler either needs to respond by calling Respond (if it needs to send reply data), Accept (If the challenge contained final data) or Abort (in case of errors).
(Permalink)

CurrentState — (uss) (SASL_State)

Read only
The current state of the authentication. Change notification is via the StateChanged signal.

Types

Simple Type (Permalink)

SASL_Mechanism — s

A SASL mechanism, as defined by RFC 4422 and registered in the IANA registry of SASL mechanisms, or an unregistered SASL mechanism such as X-GOOGLE-TOKEN used in the same contexts.

Enum (Permalink)

Abort_Reason — u

  • Invalid_Challenge (0)
    • Server sent an invalid challenge or data.
  • User_Abort (1)
    • User aborted the authentication.
Enum (Permalink)

SASL_Status — u

  • Not_Started (0)
    • Need to call StartMechanism to start.
  • In_Progress (1)
    • Challenge/Response cycle in progress
  • Server_Succeeded (2)
    • Server indicated successful authentication, handler needs to call Accept or Abort to complete the authentication process.
  • Client_Accepted (3)
    • Handler indicates that from its perspective the authentication has successfully finished.
  • Succeeded (4)
    • Everyone is happy (the server sent success, and the client has called Accept); it is up to the handler to Close the channel when it wishes.
  • Server_Failed (5)
    • Server indicated an authentication failure, Authentication can be restarted by calling StartMechanism again or completely aborted by calling Close on the channel.
  • Client_Failed (6)
    • Client indicated an authentication failure, Authentication can be restarted by calling StartMechanism again or completely aborted by calling Close on the channel.
Struct (Permalink)

SASL_State — (uss)

  • Status — u (SASL_Status)
    • The status of the state.
  • Reason — s (DBus_Error_Name)
    • The reason for the state.
  • Debug_Message — s
    • A non-localized debug message.