Sync: more doc in sync.h
authorEdouard Tisserant <edouard@pep-project.org>
Mon, 16 Jan 2017 22:38:23 +0100
changeset 153828443c7edc0f
parent 1537 8e14b6f259ea
child 1540 b0810e1b8b19
Sync: more doc in sync.h
src/sync.h
     1.1 --- a/src/sync.h	Mon Jan 16 14:41:43 2017 +0100
     1.2 +++ b/src/sync.h	Mon Jan 16 22:38:23 2017 +0100
     1.3 @@ -6,34 +6,120 @@
     1.4  Engine/adapter/app KeySync interface 
     1.5  ====================================
     1.6  
     1.7 -In the engine, KeySync is implemented through a state machine [1]. KeySync
     1.8 -state machine is driven [2] by events, triggering actions [3] and transitions
     1.9 -to new states. Events happen on decryption of email messages, on key
    1.10 -generation, on user interaction through the app and in case of timeout when
    1.11 -staying too long in some particular states.
    1.12 +
    1.13 +         Engine         |          Adapter            |          App
    1.14 +                        |                             |
    1.15 + . . . . . . . . . . . .|. . . . . . . . . . . . . . .|. . Attached session .  
    1.16 +     ,---------,        |                             |
    1.17 +   ,-| decrypt |<--------------------------------------- Incomming message 
    1.18 +   | | message |        |                             |
    1.19 +   | '---------'        |                             |
    1.20 +   | ,----------,       |                             |
    1.21 +   |-| myself   |<-------------------------------------- Create new account
    1.22 +   | | (keygen) |       |                             |
    1.23 +   | '----------'       |                             |
    1.24 +   | ,-----------,      |                             |
    1.25 +   |-| deliver   |<------------------------------------------- Accept/reject
    1.26 +   | | handshake |      |                     KeySync |            handshake
    1.27 +   | | result    |      |                     Message |
    1.28 +   | '-----------'      |                      Queue  |
    1.29 +   |                    |                      ,---,  |
    1.30 +   '-----------------------inject_sync_msg---->|   |  |
    1.31 + . . . . . . . . . . . .|. . . . . . . . . . . |---| .|. . . . Sync session .  
    1.32 + °  °  °  °  °  °  °  °  °  °  °  °  °  °  °  °|   |° | 
    1.33 +                        |                      |---|  | 
    1.34 + °   ,------------------retrieve_next_sync_msg-|   |° | 
    1.35 +   ,-v--------,         |                      '---'  | 
    1.36 + ° | Driver   |         |                           ° |
    1.37 +   '----------'         |                             |
    1.38 + °  ||'-event-----,     |                           ° |
    1.39 +    |'--partner--,|     |                             |
    1.40 + °  '---extra---,||     |           SYNC THREAD     °<-------------- Start Sync
    1.41 +            ,---vvv---, |                             |
    1.42 + °     ,----|   FSM   | |                           ° |
    1.43 +       |    '---------' |                             |
    1.44 + °     |  ,-------,     |                           ° |
    1.45 +       '->|actions|---------messageToSend-------------------> Send mail to self
    1.46 + °        '-------'     |                           ° |
    1.47 +              '-------------notifyHandshake-----------------> Ask for handshake
    1.48 + °                      |                           ° |    display group status
    1.49 +                        |                             |
    1.50 + °  °  °  °  °  °  °  ° |°  °  °  °  °  °  °  °  °  ° |
    1.51 +                        |                             |
    1.52 +
    1.53 +Emails to self
    1.54 +--------------
    1.55 +
    1.56 +With e-mail as a transport KeySync message handling is done when an incoming 
    1.57 +email to self is passed to decrypt_message(), assuming that all incoming email
    1.58 +messages are passed to decrypt_massage(). 
    1.59 +
    1.60 +In case of an email containing a KeySync paload, KeySync may consume or ignore
    1.61 +the message. decrypt_message() signals this to the app with decrypt flags
    1.62 +PEP_decrypt_flag_consume and PEP_decrypt_flag_ignore.
    1.63 +
    1.64 +In case of PEP_decrypt_flag_consume, app should delete the message.
    1.65 +In case of PEP_decrypt_flag_ignore, app should ignore message.
    1.66 +In both cases, message should be hidden.
    1.67 +
    1.68 +States, events, actions
    1.69 +-----------------------
    1.70 +
    1.71 +In the engine, KeySync is implemented through a finite state machine (FSM) [1].
    1.72 +KeySync state machine is driven [2] by events, triggering actions [3] and
    1.73 +transitions to new states.
    1.74 +
    1.75 +Events happen on :
    1.76 +
    1.77 + - decryption of email messages
    1.78 +
    1.79 + - key generation
    1.80 +
    1.81 + - user interaction through the app 
    1.82 +
    1.83 + - timeout when staying too long in some particular states.
    1.84 +
    1.85 +[1] sync/devicegroup.fsm , src/sync_fsm.c (generated)
    1.86 +[2] src/sync_driver.c (generated)
    1.87 +[3] src/sync_actions.c , src/sync_send_actions.c (generated)
    1.88 +
    1.89 +Sync session, attached sessions
    1.90 +-------------------------------
    1.91  
    1.92  To use KeySync, the adapter has to create a session dedicated to handle the
    1.93  protocol, register some callbacks [4] to the engine, and then call protocol's
    1.94 -event consumer loop [5] in a dedicated thread. KeySync actions are executed
    1.95 -as callback invoked from that loop : send pEp messages through app's transport
    1.96 -and display KeySync status and handshake to the user.
    1.97 +event consumer loop [5] in a dedicated thread. KeySync actions are executed as
    1.98 +callback invoked from that thread.
    1.99  
   1.100 -When a session is attached [6] to a KeySync session, decryption of pEp (email)
   1.101 -messages in that session may trigger operations in attached KeySync session. In
   1.102 +When a session is attached [6] to a KeySync session, decryption of pEp email
   1.103 +messages in the attached session may trigger operations in KeySync session. In
   1.104  case of an adapter capable to serve multiple apps, each app is associated to a
   1.105  different KeySync session, and sessions created for use in that app are
   1.106  attached to that session.
   1.107  
   1.108 +Adapters present different approaches regarding session and client abstraction,
   1.109 +and may not propose to explicitely create or attach session or sync session.
   1.110 +
   1.111 +[4] register_sync_callbacks()
   1.112 +[5] do_sync_protocol()
   1.113 +[6] attach_sync_session()
   1.114 +
   1.115 +KeySync Messages and queue
   1.116 +--------------------------
   1.117 +
   1.118  KeySync messages [7], not to be confused with pEp (email) messages, are either
   1.119 -directly events to be processed by the state machine or KeySync payloads
   1.120 -collected from decrypted messages. They are jobs to be processed by the state
   1.121 -machine.
   1.122 +directly events to be processed by the state machine, or KeySync payloads
   1.123 +collected from decrypted messages. 
   1.124  
   1.125 -KeySync messages can be emitted by multiple sessions, and could naturally come
   1.126 -from different threads. They must be serialized in a locked queue. Attached
   1.127 -sessions inject [8] KeySync messages in the queue. Protocol loop retrieves [9]
   1.128 -them from the queue. KeySync message is received [10] by the state machine,
   1.129 -where event eventually deduced from payload.
   1.130 +KeySync messages can be emitted by different sessions, and could naturally come
   1.131 +from different threads. They must be serialized in a locked queue. 
   1.132 +KeySync messages queue is implemented by adapter, along with thread handling
   1.133 +KeySync protocol. 
   1.134 +
   1.135 +Attached sessions inject [8] KeySync messages in the queue. Protocol loop
   1.136 +retrieves [9] them from the queue. KeySync message is received [10] by the
   1.137 +state machine, where event, partner and extra parameters are eventually deduced
   1.138 +from payload.
   1.139  
   1.140  A state timeout event is a particular case. It doesn't traverse the queue, and
   1.141  isn't emitted by a session. It is triggered by a timeout on the retrieve
   1.142 @@ -41,17 +127,65 @@
   1.143  passed as a parameter of the call to the blocking queue retrieve operation on 
   1.144  next protocol loop iteraton.
   1.145  
   1.146 -[1] sync/devicegroup.fsm , src/sync_fsm.c (generated)
   1.147 -[2] src/sync_driver.c (generated)
   1.148 -[3] src/sync_actions.c , src/sync_send_actions.c (generated)
   1.149 -[4] register_sync_callbacks()
   1.150 -[5] do_sync_protocol()
   1.151 -[6] attach_sync_session()
   1.152  [7] type sync_msg_t
   1.153  [8] callback inject_sync_msg
   1.154  [9] callback retrieve_next_sync_msg
   1.155  [10] receive_sync_msg() (src/sync_impl.c)
   1.156  
   1.157 +Application callbacks
   1.158 +---------------------
   1.159 +
   1.160 +Some Keysync actions require the application to act, through callbacks :
   1.161 +
   1.162 + - messageToSend : send pEp messages through app's transport. 
   1.163 +   Messages are already encrypted and just need to be passed as-is to
   1.164 +   transport for transmission, as for messages returned by encrypt_message().
   1.165 +
   1.166 + - notifyHandshake : display KeySync status and handshake to the user.
   1.167 +   notifyHandshake callback receives 2 identities, 'me' and 'partner', together
   1.168 +   with a sync_handshake_signal enum :
   1.169 +
   1.170 +    SYNC_NOTIFY_INIT_ADD_OUR_DEVICE :
   1.171 +        Device (me) is sole, about to enter a group (partner).
   1.172 +        App displays trustwords, and requests user accept or reject
   1.173 +        App calls deliverHandshakeResult with user's answer
   1.174 +
   1.175 +    SYNC_NOTIFY_INIT_ADD_OTHER_DEVICE :
   1.176 +        Device (me) is grouped, another device (partner) wants to join group.
   1.177 +        App displays trustwords, and requests user accept or reject
   1.178 +        App calls deliverHandshakeResult with user's answer
   1.179 +
   1.180 +    SYNC_NOTIFY_INIT_FORM_GROUP :
   1.181 +        Device (me) is forming a group, including another device (partner)
   1.182 +        App displays trustwords, and requests user accept or reject
   1.183 +        App calls deliverHandshakeResult with user's answer
   1.184 +
   1.185 +    SYNC_NOTIFY_TIMEOUT :
   1.186 +        KeySync operation timed out.
   1.187 +        Identities are set reflecting peers involved in aborted operation.
   1.188 +        App displays error message. No feedback to engine.
   1.189 +
   1.190 +    SYNC_NOTIFY_ACCEPTED_DEVICE_ADDED,
   1.191 +        New device was added to group.
   1.192 +        App displays message. No feedback to engine.
   1.193 +
   1.194 +    SYNC_NOTIFY_ACCEPTED_GROUP_CREATED
   1.195 +        New group created.
   1.196 +        App displays message. No feedback to engine.
   1.197 +
   1.198 +   To deliver handshake result back to engine once user reacted,
   1.199 +   deliver_handshake_result is used. Result can be :
   1.200 +
   1.201 +    SYNC_HANDSHAKE_CANCEL
   1.202 +        Gives no answer. User doesn't know id TrustWord are good or bad.
   1.203 +        For example in case peering device is away.
   1.204 +        Handshake will re-appear later.
   1.205 +
   1.206 +    SYNC_HANDSHAKE_ACCEPTED
   1.207 +        Trustwords match with other device and user accepts handshake.
   1.208 +
   1.209 +    SYNC_HANDSHAKE_REJECTED
   1.210 +        Trustwords do not match with any device and user rejects handshake.
   1.211  */
   1.212  
   1.213  #pragma once