|
|
|
|
@ -1,217 +1,37 @@
|
|
|
|
|
// This file is under GNU General Public License 3.0
|
|
|
|
|
// see LICENSE.txt
|
|
|
|
|
|
|
|
|
|
/*
|
|
|
|
|
====================================
|
|
|
|
|
Engine/adapter/app KeySync interface
|
|
|
|
|
====================================
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Engine | Adapter | App
|
|
|
|
|
| |
|
|
|
|
|
. . . . . . . . . . . .|. . . . . . . . . . . . . . .|. . Attached session .
|
|
|
|
|
,---------, | |
|
|
|
|
|
,-| decrypt |<--------------------------------------- Incomming message
|
|
|
|
|
| | message | | |
|
|
|
|
|
| '---------' | |
|
|
|
|
|
| ,----------, | |
|
|
|
|
|
|-| myself |<-------------------------------------- Create new account
|
|
|
|
|
| | (keygen) | | |
|
|
|
|
|
| '----------' | |
|
|
|
|
|
| ,-----------, | |
|
|
|
|
|
|-| deliver |<------------------------------------------- Accept/reject
|
|
|
|
|
| | handshake | | KeySync | handshake
|
|
|
|
|
| | result | | Message |
|
|
|
|
|
| '-----------' | Queue |
|
|
|
|
|
| | ,---, |
|
|
|
|
|
'-----------------------inject_sync_msg---->| | |
|
|
|
|
|
. . . . . . . . . . . .|. . . . . . . . . . . |---| .|. . . . Sync session .
|
|
|
|
|
* * * * * * * * * * * * * * * *| |* |
|
|
|
|
|
| |---| |
|
|
|
|
|
* ,------------------retrieve_next_sync_msg-| |* |
|
|
|
|
|
,-v--------, | '---' |
|
|
|
|
|
* | Driver | | * |
|
|
|
|
|
'----------' | |
|
|
|
|
|
* ||'-event-----, | * |
|
|
|
|
|
|'--partner--,| | |
|
|
|
|
|
* '---extra---,|| | SYNC THREAD *<-------------- Start Sync
|
|
|
|
|
,---vvv---, | |
|
|
|
|
|
* ,----| FSM | | * |
|
|
|
|
|
| '---------' | |
|
|
|
|
|
* | ,-------, | * |
|
|
|
|
|
'->|actions|---------messageToSend-------------------> Send mail to self
|
|
|
|
|
* '-------' | * |
|
|
|
|
|
'-------------notifyHandshake-----------------> Ask for handshake
|
|
|
|
|
* | * | display group status
|
|
|
|
|
| |
|
|
|
|
|
* * * * * * * * |* * * * * * * * * * |
|
|
|
|
|
| |
|
|
|
|
|
|
|
|
|
|
Emails to self
|
|
|
|
|
--------------
|
|
|
|
|
|
|
|
|
|
With e-mail as a transport KeySync message handling is done when an incoming
|
|
|
|
|
email to self is passed to decrypt_message(), assuming that all incoming email
|
|
|
|
|
messages are passed to decrypt_massage().
|
|
|
|
|
|
|
|
|
|
In case of an email containing a KeySync paload, KeySync may consume or ignore
|
|
|
|
|
the message. decrypt_message() signals this to the app with decrypt flags
|
|
|
|
|
PEP_decrypt_flag_consume and PEP_decrypt_flag_ignore.
|
|
|
|
|
|
|
|
|
|
In case of PEP_decrypt_flag_consume, app should delete the message.
|
|
|
|
|
In case of PEP_decrypt_flag_ignore, app should ignore message.
|
|
|
|
|
In both cases, message should be hidden.
|
|
|
|
|
|
|
|
|
|
States, events, actions
|
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
|
|
In the engine, KeySync is implemented through a finite state machine (FSM) [1].
|
|
|
|
|
KeySync state machine is driven [2] by events, triggering actions [3] and
|
|
|
|
|
transitions to new states.
|
|
|
|
|
|
|
|
|
|
Events happen on :
|
|
|
|
|
|
|
|
|
|
- decryption of email messages
|
|
|
|
|
|
|
|
|
|
- key generation
|
|
|
|
|
|
|
|
|
|
- user interaction through the app
|
|
|
|
|
|
|
|
|
|
- timeout when staying too long in some particular states.
|
|
|
|
|
|
|
|
|
|
[1] sync/devicegroup.fsm , src/sync_fsm.c (generated)
|
|
|
|
|
[2] src/sync_driver.c (generated)
|
|
|
|
|
[3] src/sync_actions.c , src/sync_send_actions.c (generated)
|
|
|
|
|
|
|
|
|
|
Sync session, attached sessions
|
|
|
|
|
-------------------------------
|
|
|
|
|
|
|
|
|
|
To use KeySync, the adapter has to create a session dedicated to handle the
|
|
|
|
|
protocol, register some callbacks [4] to the engine, and then call protocol's
|
|
|
|
|
event consumer loop [5] in a dedicated thread. KeySync actions are executed as
|
|
|
|
|
callback invoked from that thread.
|
|
|
|
|
|
|
|
|
|
When a session is attached [6] to a KeySync session, decryption of pEp email
|
|
|
|
|
messages in the attached session may trigger operations in KeySync session. In
|
|
|
|
|
case of an adapter capable to serve multiple apps, each app is associated to a
|
|
|
|
|
different KeySync session, and sessions created for use in that app are
|
|
|
|
|
attached to that session.
|
|
|
|
|
|
|
|
|
|
Adapters present different approaches regarding session and client abstraction,
|
|
|
|
|
and may not propose to explicitely create or attach session or sync session.
|
|
|
|
|
|
|
|
|
|
[4] register_sync_callbacks()
|
|
|
|
|
[5] do_sync_protocol()
|
|
|
|
|
[6] attach_sync_session()
|
|
|
|
|
|
|
|
|
|
KeySync Messages and queue
|
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
|
|
KeySync messages [7], not to be confused with pEp (email) messages, are either
|
|
|
|
|
directly events to be processed by the state machine, or KeySync payloads
|
|
|
|
|
collected from decrypted messages.
|
|
|
|
|
|
|
|
|
|
KeySync messages can be emitted by different sessions, and could naturally come
|
|
|
|
|
from different threads. They must be serialized in a locked queue.
|
|
|
|
|
KeySync messages queue is implemented by adapter, along with thread handling
|
|
|
|
|
KeySync protocol.
|
|
|
|
|
|
|
|
|
|
Attached sessions inject [8] KeySync messages in the queue. Protocol loop
|
|
|
|
|
retrieves [9] them from the queue. KeySync message is received [10] by the
|
|
|
|
|
state machine, where event, partner and extra parameters are eventually deduced
|
|
|
|
|
from payload.
|
|
|
|
|
|
|
|
|
|
A state timeout event is a particular case. It doesn't traverse the queue, and
|
|
|
|
|
isn't emitted by a session. It is triggered by a timeout on the retrieve
|
|
|
|
|
operation. Value of the timeout is determined when entering a new state, and is
|
|
|
|
|
passed as a parameter of the call to the blocking queue retrieve operation on
|
|
|
|
|
next protocol loop iteraton.
|
|
|
|
|
|
|
|
|
|
[7] type sync_msg_t
|
|
|
|
|
[8] callback inject_sync_msg
|
|
|
|
|
[9] callback retrieve_next_sync_msg
|
|
|
|
|
[10] receive_sync_msg() (src/sync_impl.c)
|
|
|
|
|
|
|
|
|
|
Application callbacks
|
|
|
|
|
---------------------
|
|
|
|
|
|
|
|
|
|
Some Keysync actions require the application to act, through callbacks :
|
|
|
|
|
|
|
|
|
|
- messageToSend : send pEp messages through app's transport.
|
|
|
|
|
Messages are already encrypted and just need to be passed as-is to
|
|
|
|
|
transport for transmission, as for messages returned by encrypt_message().
|
|
|
|
|
|
|
|
|
|
- notifyHandshake : display KeySync status and handshake to the user.
|
|
|
|
|
notifyHandshake callback receives 2 identities, 'me' and 'partner', together
|
|
|
|
|
with a sync_handshake_signal enum :
|
|
|
|
|
// this module is for being used WITHOUT the Transport API in transport.h
|
|
|
|
|
// DO NOT USE IT WHEN USING Transport API!
|
|
|
|
|
|
|
|
|
|
SYNC_NOTIFY_INIT_ADD_OUR_DEVICE :
|
|
|
|
|
Device (me) is sole, about to enter a group (partner).
|
|
|
|
|
App displays trustwords, and requests user accept or reject
|
|
|
|
|
App calls deliverHandshakeResult with user's answer
|
|
|
|
|
#pragma once
|
|
|
|
|
|
|
|
|
|
SYNC_NOTIFY_INIT_ADD_OTHER_DEVICE :
|
|
|
|
|
Device (me) is grouped, another device (partner) wants to join group.
|
|
|
|
|
App displays trustwords, and requests user accept or reject
|
|
|
|
|
App calls deliverHandshakeResult with user's answer
|
|
|
|
|
#include "message.h"
|
|
|
|
|
|
|
|
|
|
SYNC_NOTIFY_INIT_FORM_GROUP :
|
|
|
|
|
Device (me) is forming a group, including another device (partner)
|
|
|
|
|
App displays trustwords, and requests user accept or reject
|
|
|
|
|
App calls deliverHandshakeResult with user's answer
|
|
|
|
|
#ifdef __cplusplus
|
|
|
|
|
extern "C" {
|
|
|
|
|
#endif
|
|
|
|
|
|
|
|
|
|
SYNC_NOTIFY_INIT_MOVE_OUR_DEVICE
|
|
|
|
|
Device (me) is grouped and will leave current group to join another
|
|
|
|
|
device's (partner) group.
|
|
|
|
|
App displays trustwords, and requests user accept or reject
|
|
|
|
|
App calls deliverHandshakeResult with user's answer
|
|
|
|
|
typedef enum _sync_handshake_signal {
|
|
|
|
|
SYNC_NOTIFY_UNDEFINED = 0,
|
|
|
|
|
|
|
|
|
|
// request show handshake dialog
|
|
|
|
|
SYNC_NOTIFY_INIT_ADD_OUR_DEVICE,
|
|
|
|
|
SYNC_NOTIFY_INIT_ADD_OTHER_DEVICE,
|
|
|
|
|
SYNC_NOTIFY_INIT_FORM_GROUP,
|
|
|
|
|
SYNC_NOTIFY_INIT_MOVE_OUR_DEVICE,
|
|
|
|
|
|
|
|
|
|
SYNC_NOTIFY_TIMEOUT :
|
|
|
|
|
KeySync operation timed out.
|
|
|
|
|
Identities are set reflecting peers involved in aborted operation.
|
|
|
|
|
App displays error message. No feedback to engine.
|
|
|
|
|
// handshake process timed out
|
|
|
|
|
SYNC_NOTIFY_TIMEOUT,
|
|
|
|
|
|
|
|
|
|
// handshake accepted by user
|
|
|
|
|
SYNC_NOTIFY_ACCEPTED_DEVICE_ADDED,
|
|
|
|
|
New device was added to group.
|
|
|
|
|
App displays message. No feedback to engine.
|
|
|
|
|
|
|
|
|
|
SYNC_NOTIFY_ACCEPTED_GROUP_CREATED
|
|
|
|
|
New group created.
|
|
|
|
|
App displays message. No feedback to engine.
|
|
|
|
|
|
|
|
|
|
SYNC_NOTIFY_ACCEPTED_DEVICE_MOVED
|
|
|
|
|
New device was moved from one group to another.
|
|
|
|
|
App displays message. No feedback to engine.
|
|
|
|
|
|
|
|
|
|
To deliver handshake result back to engine once user reacted,
|
|
|
|
|
deliver_handshake_result is used. Result can be :
|
|
|
|
|
|
|
|
|
|
SYNC_HANDSHAKE_CANCEL
|
|
|
|
|
Gives no answer. User doesn't know id TrustWord are good or bad.
|
|
|
|
|
For example in case peering device is away.
|
|
|
|
|
Handshake will re-appear later.
|
|
|
|
|
SYNC_NOTIFY_ACCEPTED_GROUP_CREATED,
|
|
|
|
|
SYNC_NOTIFY_ACCEPTED_DEVICE_MOVED,
|
|
|
|
|
|
|
|
|
|
SYNC_HANDSHAKE_ACCEPTED
|
|
|
|
|
Trustwords match with other device and user accepts handshake.
|
|
|
|
|
|
|
|
|
|
SYNC_HANDSHAKE_REJECTED
|
|
|
|
|
Trustwords do not match with any device and user rejects handshake.
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
#pragma once
|
|
|
|
|
|
|
|
|
|
#include "message.h"
|
|
|
|
|
#include "sync_fsm.h"
|
|
|
|
|
#include "sync_app.h"
|
|
|
|
|
|
|
|
|
|
// this module is for being used WITHOUT the Transport API in transport.h
|
|
|
|
|
// DO NOT USE IT WHEN USING Transport API!
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#ifdef __cplusplus
|
|
|
|
|
extern "C" {
|
|
|
|
|
#endif
|
|
|
|
|
// handshake dialog must be closed
|
|
|
|
|
SYNC_NOTIFY_OVERTAKEN
|
|
|
|
|
} sync_handshake_signal;
|
|
|
|
|
|
|
|
|
|
// messageToSend() - send a message
|
|
|
|
|
//
|
|
|
|
|
@ -262,7 +82,7 @@ typedef enum _sync_handshake_result {
|
|
|
|
|
|
|
|
|
|
DYNAMIC_API PEP_STATUS deliverHandshakeResult(
|
|
|
|
|
PEP_SESSION session,
|
|
|
|
|
Identity partner,
|
|
|
|
|
pEp_identity *partner,
|
|
|
|
|
sync_handshake_result result
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
|
Volker Birk
5 years ago