[Telepathy] telepathy-spec vs. XTLS: round 2

[Cosimo Cecchi]

Hi,

in the last week I have been working again on a proposal for adding
interfaces in the telepathy spec for XTLS and authentication support,
following up on latest Sjoerd's SASL design.

I set up a telepathy-spec branch here [1], the full HTML of the spec
proposal can be found here [2].

Here's a quick summary of the new channels/interfaces and a bit of
background on the design.

------------------------------------------------------------------

= org.freedesktop.Telepathy.Channel.Type.ClientAuthentication =

The idea of this channel type is similar to Sjoerd's
org.freedesktop.Telepathy.Channel.Type.ServerAuthentication proposal.
In this case, ClientAuthenticationMethod contains the specific method
used for the authentication step, and defines which interface the
channel supports.
The TargetAdded/TargetRemoved/TargetChannels signals/property contain a
variable list of channels waiting on this authentication, and might be
empty.

Signals
        TargetAdded (o: Channel, ao: TargetChannels) 	
        TargetRemoved (o: Channel, ao: TargetChannels) 	
        
Properties
        ClientAuthenticationMethod u (Read only) [ XTLS, OTR, ... ]
        TargetChannels 	ao (Read only)
        
= org.freedesktop.Telepathy.Channel.Interface.XTLSAuthentication =

This is the inteface that a channel of type ClientAuthentication needs
supports if it's using XTLS for authentication.
Its design is based to what Eitan and me drafted in Cambridge with the
NegotiateVerification channel, but it also has a fundamental change,
which is to split authentication method candidates in a separate,
transient object, similar to CodecOffer.

The API is symmetric for both the initiator and the receiver, and
clients are supposed to call SendMechanisms() with a list of the
authentication methods they support. The a{sv} of properties specified
in that call, will eventually populate the [Local/Remote]Parameters
properties in the transient object (more on this later).

Once the clients sent their lists, the 'NewProposals' signal will be
emitted, containing a list of possible matches for authentication, each
one in a separate transient
org.freedesktop.Telepathy.Authentication.Proposal object. The first
object that is accepted (as in the client called Accept() on it), will
be the one used for the actual handshake.
Clients can also reject all the proposals in a single run, using Abort()
on this interface.

Methods
        SendMechanisms (a(sa{sv}): Mechanism_List) → nothing
        Abort () → nothing
Signals
        AuthenticationStateChanged (u: State, u: Reason) 
        NewProposals (ao: Proposals) 
Properties
        AuthenticationProposals	ao (Read only)
        XTLSAuthenticationState u (Read only)
        * Not_Started (0)
                The XTLS handshake is not started yet. Clients have to
                callSendMechanisms in order to get to the next state.
        * Local_Mechanisms_Sent (1)
                The client sent its local choice for XTLS negotiation
                mechanisms, and is waiting for the remote client to do
                the same.
        * Remote_Mechanisms_Received (2)
                The remote client sent its local choice for XTLS
                negotiation mechanisms, and is waiting for the approval
                of one of them, or for their rejection.
        * Succeeded (3)
                The XTLS authentication has been successfully completed.
        * Failed (4)
                The XTLS authentication has failed.
                
= org.freedesktop.Telepathy.Authentication.Proposal =

I stole the org.fd.Tp.Authentication namespace for this object, which is
the representation of an authentication proposal, which a client can
accept or reject. This can probably also be useful outside of XTLS.

The {Local, Remote}Parameters dictionaries should give clients enough
freedom on which information should be exposed without cluttering the Tp
API too much (i.e. this could contain a fingerprint if used with XTLS
+X.509 and a password if used with XTLS+SRP).

Methods
        Reject () → nothing 
        Accept () → nothing 
Properties
        LocalMethod s (Read only)
        RemoteMethod s (Read only)
        LocalParameters	a{sv} (Read only)
        RemoteParameters a{sv} (Read only)
        
------------------------------------------------------------------
        
*** Notes ***

This proposal still lacks TLS certificate validation, which is also a
required step for XTLS.
I will send another proposal for it, and for the integration with these
interfaces next week, but the basic idea would be:

        - add another state to XTLSAuthentication, which would happen
        after the negotiation steps are successfully completed, and
        would indicate that we're waiting on the verification of a TLS
        certificate.
        - add another property/signal to XTLSAuthentication, which would
        act like the AuthenticationProposals/NewProposals couple, which
        contain a path to the certificate exchange channel.
        - add another channel type for TLS certificate exchange.
        - add another transient object under 'Authentication',
        representing the bulk TLS Certificate.

A nice side-effect of this design is that we could re-use the TLS
certificate exchange channel for the Client2Server case. Also, the
object references in the XTLSAuthentication channel would tie
authentication objects' lifetime to the actual authentication process,
which is a good thing for clients.

[1]
http://git.collabora.co.uk/?p=user/cosimoc/telepathy-spec.git;a=shortlog;h=refs/heads/xtls-proposal
[2] http://people.collabora.co.uk/~cosimoc/xtls-proposal-spec/


Cheers,

Cosimo