Merge pull request #78 from nextleap-project/new-diagram

initial sequence diagram for verified contact flow

images/contact.seq

@@ -0,0 +1,24 @@
+# This is a sequence diagram for the dkim section
+# I used https://bramp.github.io/js-sequence-diagrams/
+# to render it to svg and then save it in images folder
+
+participant Alice as Ua
+participant Bob as Ub
+
+Ua --> Ub: 1.a) bootstrap code
+Note over Ua: 1.b) track bootstrap per INVITENUMBER
+Note over Ub: 2.a) check for exising key
+Ub ->> Ua: 2.b) vc-request message with INVITENUMBER
+Note over Ua: 3.a) look up bootstrap by INVITENUMBER
+Note over Ua: 3.b) abort if invite expired
+Note over Ua: 3.c) process AC header
+Ua -> Ub: 3.d) vc-auth-required message with AC header
+Note over Ub: 4.a) abort if key does not match FP from bootstrap
+Ub -> Ua: 4.b) vc-request-with-auth with Bob_FP and AUTH
+Note over Ua: 5.a) verify AUTH and key
+Note over Ua: 5.b) on failure alert user and abort
+Note over Ua: 6.a) signal success to user
+Ua -> Ub: 6.b) vc-contact-confirm message
+Note over Ua: 6.c) clear bootstrap data for INVITECODE
+Note over Ub: 7. signal success to user
+

source/new.rst

@@ -144,6 +144,11 @@ or else both get an error message.
 The protocol is safe against active attackers that can modify, create and delete
 messages.
 
+.. figure:: ../images/secure_channel_foto.jpg
+   :width: 200px
+
+   Setup Contact protocol step 2 with https://delta.chat.
+
 The protocol follows a single simple UI workflow:
 A peer "shows" bootstrap data
 that is then "read" by the other peer through a second channel.
@@ -173,13 +178,19 @@ An attacker who can compromise both channels
 can inject wrong key material
 and convince the peer to verify it.
 
+.. figure:: ../images/contact.*
+   :alt: Sequence diagram of UI and administrative message flow
+
+   UI and administrative message flow of contact setup
+
 Here is a conceptual step-by-step example
 of the proposed UI and administrative message workflow
 for establishing a secure contact between two contacts,
 Alice and Bob.
 
 1. Alice sends a bootstrap code to Bob via the second channel.
-   The bootstrap code consists of:
+
+   a) The bootstrap code consists of:
 
    - Alice's Openpgp4 public key fingerprint ``Alice_FP``,
      which acts as a commitment to the
@@ -204,7 +215,7 @@ Alice and Bob.
 
    - optionally add metadata such as ``INVITE-TO=groupname``
 
-   Per ``INVITENUMBER`` Alices device will keep track of:
+   b) Per ``INVITENUMBER`` Alices device will keep track of:
    - the associated ``AUTH`` secret
    - the time the contact verification was initiated.
    - the metadata provided.
@@ -222,18 +233,22 @@ Alice and Bob.
 
 3. Alice's device receives the "vc-request" message.
 
-   If she recognizes the ``INVITENUMBER`` from step 1
+   a) She looks up the bootstrap data for the ``INVITENUMBER``.
+   If the ``INVITENUMBER`` does not match
+   then Alice terminates the protocol.
+
+   b) If she recognizes the ``INVITENUMBER`` from step 1
    she checks that the invite has not expired.
    If the timestamp associated with the ``INVITENUMBER``
-   is not longer ago than a given time
-   she processes Bob's Autocrypt key.
-   Then, she uses this key
+   is longer ago than a given time
+   Alice terminates the protocol.
+
+   c) She then processes Bob's Autocrypt key.
+
+   d) She uses this key
    to create an encrypted "vc-auth-required" message
    containing her own Autocrypt key, which she sends to Bob.
 
-   If the ``INVITENUMBER`` does not match
-   then Alice terminates the protocol.
-
 4. Bob receive the "vc-auth-required" message,
    decrypts it,
    and verifies that Alice's Autocrypt key matches ``Alice_FP``.
@@ -249,21 +264,24 @@ Alice and Bob.
       Bob's own key fingerprint ``Bob_FP``
       and the second challenge ``AUTH`` from step 1.
 
-5. Alice decrypts Bob's 'vc-request-with-auth' message,
-   and verifies
-   that Bob's Autocrypt key matches ``Bob_FP``
+5. Alice decrypts Bob's 'vc-request-with-auth' message
+
+   a) and verifies that Bob's Autocrypt key matches ``Bob_FP``
    that the invite has not expired
    and that the transferred ``AUTH`` matches the one from step 1.
 
-   If any verification fails,
+   b) If any verification fails,
    Alice's device signals
    "Could not establish secure connection to Bob"
    and the protocol terminates.
 
-6. If the verification succeeds on Alice's device it shows
-   "Secure contact with Bob <bob-adr> established".
-   In addition it sends Bob a "vc-contact-confirm" message.
-   The device also removes the data associated with ``INVITECODE``.
+6. If the verification succeeds on Alice's device
+
+   a) shows "Secure contact with Bob <bob-adr> established".
+
+   b) sends Bob a "vc-contact-confirm" message.
+
+   c) also removes the data associated with ``INVITECODE``.
 
 7. Bob's device receives "vc-contact-confirm" and shows
    "Secure contact with Alice <alice-adr> established".
@@ -276,12 +294,6 @@ Moreover,
 Bob has learned and validated the contact information and Autocrypt key of Alice,
 the person who sent the bootstrap code to Bob.
 
-.. figure:: ../images/secure_channel_foto.jpg
-   :width: 200px
-
-   Setup Contact protocol step 2 with https://delta.chat.
-
-
 Requirements for the underlying encryption scheme
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~