[Telepathy] Telepathy Encryption spec draft

[Cosimo Cecchi]

Hi everyone,

I pushed a branch of telepathy-spec [1] implementing some of the ideas
for end to end encryption we discussed on this list.

Here's an overview of the interface:

org.freedesktop.Telepathy.Channel.Interface.Encryption

Methods:
      * Proceed (s: Password) → nothing
      * This method lets the encryption process proceed with the
        verification of the credentials. A
        Channel.Type.ContactVerification channel will be emitted by the
        connection manager, for a client to accept or reject the
        credentials provided by the remote endpoint. The optional
        password argument should be used when the remote endpoint
        signals that a password is needed to verify the initiator's
        fingerprint.

Signals:
      * EncryptionStateChanged (u: State)
      * Signals that the encryption state for this channel has changed

Properties:
      * LocalFingerprint — s (Read/Write)
      * Contains the fingerprint of the certificate we want to use for
        this encrypted channel.
      * RemoteFingerprint — s (Read)
      * Contains the fingerprint of the certificate the remote end wants
        to use for this encrypted channel.
      * RemotePassword — b (Read) 
      * Whether the remote endpoint signals that a password is needed in
        order to verify the local fingerprint.
      * EncryptionRequired — b (Read/Write)
      * Indicates whether the channel is requiring encryption.
      * EncryptionState — u (Encryption_State) (Read)
      * Indicates which stage of the encryption we're in.

Types:
      * Encryption_State — u
      * None (0): No encryption is taking place on the channel.
      * Awaiting_Remote_Response (1): Awaiting remote response or
        fingerprint.
      * Awaiting_Local_Response (2): Awaiting local call to Proceed().
      * Verification_Pending (3): Verification handshakes are taking
        places.
      * Encrypted (4): Channel is encrypted.
      * Failed (5): Encryption request has failed.

The idea is to request an encrypted channel, by setting the
EncryptionRequired property to TRUE in the request along with our
LocalFingerprint property.

When the channel states goes to Awaiting_Local_Response, there can be
three cases:
      * RemotePassword = TRUE; RemoteFingerprint is empty. This means
        the remote endpoint thinks he's not able to verify our cert (as
        for the XTLS spec [2]) and does not want to accept any mean of
        authentication other than an interactive one (SRP). In this
        case, the client should call Proceed() with a previously
        (out-of-band) exchanged password, or the request will fail.
      * RemotePassword = TRUE; RemoteFingerprint is not empty. This
        means the remote endpoint thinks he's not able to verify our
        cert, but he's willing to accept either SRP or do a leap of
        faith. It's up to the client to decide whether to call Proceed()
        with a password or not.
      * RemotePassword = FALSE; RemoteFingerprint MUST not be empty
        (happy path). This means the remote endpoint thinks he's able to
        verify our cert, and the client MUST call Proceed() without a
        password.

At this point, the state could either go to Failed or to
Verification_Pending; in the latter case, verification of the channel
should proceed as specified in Eitan's Verification branch and, if
successful, the channel state should go to Encrypted.

Problems: this spec is quite tailored on the XTLS spec; I think we
should make it a bit more general in order to support other cipher
algorithms, such as OTR.
The obvious idea is to have a "Protocol" property (a bit like
TpFileHashType) enumerating the supported protocols; the
Proceed(password) method should work nice to support OTR as well in that
case.

As usual, feedback welcome!

[1]
http://git.collabora.co.uk/?p=user/cosimoc/telepathy-spec.git;a=shortlog;h=refs/heads/encryption
[2] http://xmpp.org/extensions/inbox/jingle-xtls.html#proto

Cheers,

Cosimo