[Telepathy] RFC SASL Authentication channels

[Sjoerd Simons]

Hi,

  Based on all the various discussions earlier on the list, i think (hope) me
  and Eitan are going in basically the same way. Basically this is a rough (but
  i think complete sketch) how i'd do this, with a specific Channel Type and a
  Interface purely geared towards SASL

  org.freedesktop.Telepathy.Channel.Type.ServerAuthentication

    Channel type for a user authenticating against the chat server, during
    login. This kind of channel can only occur during the CONNECTING phase, but
    multiple channels of this type can happen sequentially. For example when
    during login one first has to respond to a Captcha challenge and after that
    has to login using a SASL method.

  + Immutable property: AuthenticationMethod, Enum (SASL, CAPTCHA, EULA, TLS?)

    This property defines the Method used for the current authentication step.
    The method also defines which Interfaces the channel implements. For
    exmaple if for the SASL method the SaslAuthentication interface needs to be
    implemented.

  org.freedesktop.Telepathy.Channel.Interface.SaslAuthentication

  + Immutable Property: AvailableMechanisms, as
    Example: [ "PLAIN", "DIGEST-MD5", "SCRAM-SHA-1" ]

    The SASL mechanisms as offered by the server.

  + Property: CurrentChallenge: ay
    The current challenge from the server. change notification via
    NewChallenge. The handler either needs to respond by calling Response (if
    it needs to send reply data), Accept (If the challenge contained final
    data) or Abort (in case of errors)

  + Property: CurrentState: (enum: State,
                             DBus_Error_Name: Reason,
                             s: DebugMessage)
    The current state of the authentication: enum includes:
      NOT_STARTED, /* Seems obvious, need to call StartMechanism to start */
      IN_PROGRESS, /* Challenge/Response cycle in progress */
      SERVER_SUCCEEDED, /* Server indicated successful authentication, handler
                           needs to Accept or Abort */
      CLIENT_ACCEPTED,  /* Handler indicates that from its perspective the
                           authentication has successfully finished */
      SUCCEEDED, /* Everyone is happy (server sent success, client sent Accept),                    up to the handler to close the channel */
      SERVER_FAILED, /* Server indicated an authentication failure,
                        Authentication can be restarted by calling
                        StartMechanism again or completely aborted by Closing
                        the channel */
      CLIENT_FAILED, /* Client indicated an authentication failure,
                        Authentication can be restarted by calling
                        StartMechanism again or completely aborted by Closing
                        the channel */

    Change notification via StateChanged signal

  + Signal: StateChanged: (enum, DBus_Error_Name, string)
    Same arguments as the property, normal state changing stuff applies

  + method: StartMechanism (String: Mechanism, ay: InitialData)
    Start an authentication try using Mechanism. If the choosen SASL
    mechanism is client-first then the first data must be passed in
    InitialData, otherwise InitialData must be an empty array.

  + signal: NewChallenge (ay: ChallengeData)
    A new challenge from the server.

  + method: Response (ay: ResponseData)
    Our response to the CurrentChallenge if required.

  + method: Accept()
    Handler accepts the authentication as finished. Can be called whenever the
    Handler considered the authentication process to be (successfully) finished
    from its part.

  + method: Abort(enum: Reason,
      DBus_Error_Name: DetailedReason, s: DebugMessage)
    Abort the current authentication try. Reasons include the server sending us
    an invalid challenge, server user aborting the method, etc etc.

  Sjoerd
-- 
Any circuit design must contain at least one part which is obsolete, two parts
which are unobtainable, and three parts which are still under development.