major keysync revisions (KRB)
authorkelly <kelly@pep-project.org>
Wed, 16 Oct 2019 11:49:35 -0400
changeset 110309ac7d80068f
parent 1102 51637b3ceedf
child 1104 57b597e4508c
major keysync revisions (KRB)
pep-keysync/draft-hoeneisen-pep-keysync.mkd
     1.1 --- a/pep-keysync/draft-hoeneisen-pep-keysync.mkd	Wed Oct 16 12:57:34 2019 +0200
     1.2 +++ b/pep-keysync/draft-hoeneisen-pep-keysync.mkd	Wed Oct 16 11:49:35 2019 -0400
     1.3 @@ -3,7 +3,7 @@
     1.4  
     1.5  title: "pretty Easy privacy (pEp): Key Synchronization Protocol"
     1.6  abbrev: pretty Easy privacy (pEp) KeySync
     1.7 -docname: draft-hoeneisen-pep-keysync-01
     1.8 +docname: draft-hoeneisen-pep-KeySync-01
     1.9  category: std
    1.10  
    1.11  stand_alone: yes
    1.12 @@ -32,10 +32,22 @@
    1.13    I-D.marques-pep-handshake:
    1.14  #  I-D.luck-lamps-pep-header-protection:
    1.15  
    1.16 -#   I-D.hoeneisen-pep-keysync:
    1.17 +#   I-D.hoeneisen-pep-KeySync:
    1.18  {::include ../shared/references/isoc-btn.mkd}
    1.19  # {::include ../shared/references/implementation-status.mkd}
    1.20  
    1.21 +<!-- TODOs:
    1.22 +      - diagrams for the simplified FSM section, if we keep it
    1.23 +      - cross reference links to various sections
    1.24 +      - double check existing reference links
    1.25 +      - change New Device to new device (no need to capitalize)
    1.26 +      - find all instances of 2 spaces after a period and change to 1
    1.27 +      - clean up " vs ' (should be single quotes)
    1.28 +      - Everything in FSM from state Grouped onward is still being
    1.29 +              written, please do not review yet
    1.30 +
    1.31 +-->
    1.32 +
    1.33  --- abstract
    1.34  
    1.35  Modern users of messaging systems usually have multiple devices, and
    1.36 @@ -53,52 +65,17 @@
    1.37  use and deployment of secure end-to-end interpersonal messaging. These
    1.38  include, but are not limited to, key management, key discovery, and
    1.39  private key handling.
    1.40 -   
    1.41 +
    1.42  --- middle
    1.43  
    1.44 -<!--
    1.45 -
    1.46 -* New Device vs. new device
    1.47 -* Active/Passive Capitalized?
    1.48 -* Code Snippets in actions (replace by references?)
    1.49 -
    1.50 --->
    1.51 -
    1.52 -
    1.53 -<!--
    1.54 -TODO:
    1.55 -
    1.56 -**[nk] general comment: the draft reads well and
    1.57 -overall to me is understandable. Related to section 1.3: the
    1.58 -synchronization process plus secure key exchange (and choice) are the
    1.59 -two main challenges. It would find it better if these two challenges
    1.60 -were addressed more explicitly in the further description of the state
    1.61 -machine. I think going through all states and options of the FSM is
    1.62 -good and necessary, but as i wrote in the IRC already a better
    1.63 -bundling of what the described processes deliver for the results of
    1.64 -KeySync would help the reader getting into the concept better. Thus,
    1.65 -one idea could be to continue after section 2 with explaining the
    1.66 -central facts about security and which keys to be chosen and their
    1.67 -handling (cf. comments further down section: 3.1.2.24. and 4). Compare
    1.68 -with for example what Volker says here: 1:19ff:
    1.69 -https://media.ccc.de/v/cosin-22-p_p_sync#t=4526
    1.70 -
    1.71 -**[nk] When the full state machine is described further down, the
    1.72 -handshake is named phase 1 and phase 2 which from section 3 on occurs
    1.73 -relatively often, but this wording was not used earlier. it might be
    1.74 -good to mention phase 1 and 2 in the graphics/section2 already (even if
    1.75 -the reader can derive from the content of the text, what it means).
    1.76 -
    1.77 --->
    1.78 -
    1.79  # Introduction
    1.80  
    1.81  This document specifies the pEp Key Synchronization (KeySync)
    1.82  Protocol, a means for secure peer-to-peer synchronization of private
    1.83 -keys across devices belonging to the same user. <!-- The pEp KeySync
    1.84 -protocol is a critical part of the broader pEp Sync protocol, and
    1.85 +keys across devices belonging to the same user. The pEp KeySync
    1.86 +protocol is a critical part of the broader pEp Sync protocol family, and
    1.87  establishes a basis for the synchronization of other user data, such
    1.88 -as the public keys and corresponding trust information on peers. -->
    1.89 +as the public keys and corresponding trust information on peers.
    1.90  
    1.91  This part of the pretty Easy privacy (pEp) protocols {{I-D.birk-pep}}
    1.92  presents a way to synchronize private key material in a decentralized
    1.93 @@ -106,8 +83,6 @@
    1.94  a finite-state machine (FSM) along with the exchange of specific
    1.95  KeySync messages.
    1.96  
    1.97 -<!-- TODO: Consider FSM to definitions -->
    1.98 -
    1.99  For pEp implementations, pEp KeySync for key synchronization is a
   1.100  critical part of the broader pEp Sync protocol, which is designed to
   1.101  be extensible to allow for the synchronization of additional user
   1.102 @@ -140,30 +115,27 @@
   1.103  
   1.104  The basic approach to solving the multiple-device decryption problem
   1.105  is to synchronize private keys among the devices of a user in a secure
   1.106 -manner. pEp aims to do this by using Trustword confirmation
   1.107 -(cf. {{I-D.birk-pep-trustwords}}) between any two devices at a time
   1.108 -for pairing purposes. Simply put, a user needs to manually compare and
   1.109 -confirm Trustwords before the automatic and security-sensitive
   1.110 -transfer of private key information can occur.
   1.111 -
   1.112 -<!-- TODO [HM]: Should we refer to pep-handshake as opposed to
   1.113 -trustwords -->
   1.114 +manner. pEp achieves this by having a user form a Device Group among
   1.115 +their devices. During this process, a Handshake process occurs, and the
   1.116 +user will be presented with a Trustwords dialog between any two devices
   1.117 +at a time for pairing purposes. (cf. {{I-D.birk-pep-trustwords}})
   1.118 +Simply put, a user MUST manually complete the Trustwords dialog before
   1.119 +the automatic and security-sensitive transfer of private key information can occur.
   1.120  
   1.121  
   1.122  ## Main Challenge
   1.123  
   1.124 -The main challenge, that pEp KeySync is designed to overcome, is to
   1.125 +The main challenge that pEp KeySync is designed to overcome is to
   1.126  perform the synchronization in a secure manner so that private keys
   1.127  are not leaked or exposed to theft.
   1.128  
   1.129 -Note: The case of an adversary getting access to the device itself is
   1.130 -beyond the scope of this document.
   1.131 -
   1.132 -<!-- TODO: [KRB] I would clarify the adversary access note as being physical
   1.133 -access.  -->
   1.134 +Note: The case of an adversary getting physical access to the device
   1.135 +itself is beyond the scope of this document.
   1.136  
   1.137  {::include ../shared/text-blocks/key-words-rfc2119.mkd}
   1.138  
   1.139 +## Terminology
   1.140 +
   1.141  {::include ../shared/text-blocks/terms-intro.mkd}
   1.142  
   1.143  {::include ../shared/text-blocks/handshake.mkd}
   1.144 @@ -171,30 +143,19 @@
   1.145     Note: In pEp KeySync, the handshake is used to authenticate own
   1.146     devices (the user normally compares the Trustwords directly by
   1.147     looking at the screens of the devices involved).
   1.148 -   
   1.149 +
   1.150  {::include ../shared/text-blocks/trustwords.mkd}
   1.151  {::include ../shared/text-blocks/tofu.mkd}
   1.152  {::include ../shared/text-blocks/mitm.mkd}
   1.153  {::include ../shared/text-blocks/identity.mkd}
   1.154  
   1.155 -* Device Group: All devices that are grouped to share data like
   1.156 -  cryptographic keys, trust information, calendar, configuration and
   1.157 -  other data. The data is synchronized through a common channel for a
   1.158 -  given identity, e.g., an identity can be an email address and the
   1.159 -  common channel a mailbox in email.
   1.160 -  <!-- TODO: suggestion KRB:
   1.161 -  All of a user's devices which have successfully completed the
   1.162 +* Device Group: All of a user's devices which have successfully completed the
   1.163    KeySync process, and are now configured to share user data, such as
   1.164    cryptographic keys, trust information, calendars, configurations,
   1.165 -  and other data as a result.  This data is synchronized through a
   1.166 +  and other data as a result of that process. This data is synchronized through a
   1.167    common channel for a given identity. For example, an identity might
   1.168    be a specific email address, and the common channel would be a
   1.169    mailbox for that email address.
   1.170 -  -->
   1.171 -
   1.172 -* Group Key: A key pair primarily used by a Device Group for a certain
   1.173 -  identity. A Device Group has a Group Key for each of a user's
   1.174 -  identities.
   1.175  
   1.176  * Sole Device: A device which is not part of a Device Group.
   1.177  
   1.178 @@ -207,61 +168,93 @@
   1.179    this Beacon in order to initiate negotiation for the formation of a
   1.180    Device Group.
   1.181  
   1.182 +* Transaction ID (TID): A UUID version 4, variant 1 number generated by
   1.183 +  each device during the pEp KeySync process in order to identify the
   1.184 +  respective devices involved.
   1.185 +
   1.186 +* Default Key: A key which is actually used for a given identity.
   1.187 +
   1.188 +* Own Key: A Default Key for an own identity.
   1.189 +
   1.190 +<!-- Just leaving this here for reference, if confusion persists.
   1.191 +23:51 <fdik> a default key is an actually used key for an identity
   1.192 +23:52 <fdik> an own key is a default key for an own identity
   1.193 +23:52 <fdik> users are able to select which own identities they want to sync and which not
   1.194 +23:53 <fdik> in the apps it's mainly accounts which are in sync and some, which may be not
   1.195 +-->
   1.196 +
   1.197  
   1.198  # General Description
   1.199 -
   1.200 -This section describes an ideal-condition use case for pEp KeySync.
   1.201 -It focuses on the main procedures and on the scenarios where
   1.202 +<!-- NOTE: Much of this is paraphrased from VB's Sync presentation at cosin. -->
   1.203 +
   1.204 +The pEp KeySync protocol allows a user to securely synchronize private
   1.205 +key data across devices for multiple identities across multiple devices.
   1.206 +This synchronization process is decentralized and performed as a
   1.207 +two-phase commit protocol structure for greatest security.
   1.208 +
   1.209 +The synchronization is accomplished through the implementation of a Finite-State
   1.210 +Machine (FSM) on each pEp-enabled device. This FSM not only sends and
   1.211 +receives network traffic, which allows devices to communicate with each
   1.212 +other throughout the KeySync process, but also interacts with the pEp
   1.213 +Engine itself.
   1.214 +
   1.215 +Once activated, the pEp KeySync protocol initiates the formation of a
   1.216 +Device Group, and the user is guided through a Handshake process on
   1.217 +their respective devices. A user can choose to Reject or Cancel
   1.218 +this process at any time, from either device, and private key data is
   1.219 +not exchanged until the group formation process is verified on both devices.
   1.220 +
   1.221 +Once a Device Group is formed, a user can add additional devices to their
   1.222 +group through the same joining procedure. Upon adding the new
   1.223 +device to the existing Device Group, key data is synchronized
   1.224 +among all grouped devices, allowing a user to communicate privately
   1.225 +from any of their secure identities. <!-- add TrustSync blurb and ref when draft is ready. -->
   1.226 +
   1.227 +
   1.228 +## Use Cases for pEp KeySync
   1.229 +
   1.230 +This section describes ideal-condition use cases for pEp KeySync.
   1.231 +The focus is on the core procedures and on the scenarios where
   1.232  everything works. Unexpected user behavior, error handling, race
   1.233 -conditions and the like are mostly omitted from this section in order
   1.234 -to facilitate a better understanding of the general concepts of pEp
   1.235 -KeySync. Additional use cases will be discussed in further detail
   1.236 -throughout {{reference-implementation}}.
   1.237 -
   1.238 -
   1.239 -## Use Cases for pEp KeySync
   1.240 +conditions, etc., are generally omitted from this section in order
   1.241 +to focus on the general concepts of pEp KeySync. Additional use cases
   1.242 +will be discussed in further detail throughout {{reference-implementation}}.
   1.243  
   1.244  ### Form Device Group
   1.245  
   1.246  Our user, Alice, has two devices that are configured with
   1.247  pEp-implementing messaging clients and share the same identity for her
   1.248 -preferred communication channel (in our example: a communication
   1.249 -channel with an email address).  Let us call these devices Alice_R and
   1.250 -Alice_O. Each device already has its own key pair, which was
   1.251 +preferred communication channel. In our example, this is a communication
   1.252 +channel with an email address. Let us call these devices Alice_Mobile and
   1.253 +Alice_Tablet. Each device already has its own key pair, which was
   1.254  automatically generated by the pEp protocol. Neither device knows
   1.255  anything about the other.
   1.256  
   1.257 -<!-- TODO: [KRB] It may further help to call the devices Alice_cell,
   1.258 -   Alice_tablet, and Alice_laptop or even Alice_1, Alice_2,
   1.259 -   Alice_3. The letters are too random. We need something more
   1.260 -   recognizable, to ground the reader in what we are proposing.
   1.261 --->
   1.262 -
   1.263  Alice wants full communication capability from both of her devices,
   1.264  but currently cannot do so, as the devices do not know about each
   1.265 -other. Alice will use pEp Keysync to form a Device Group and add her
   1.266 +other. Alice will use pEp KeySync to form a Device Group and add her
   1.267  devices to it. This allows for the exchange of private key data among
   1.268  its devices, allowing Alice to have full communication capability on
   1.269  both of her devices.
   1.270  
   1.271  ### Add New Device to Existing Device Group
   1.272  
   1.273 -Sometime after devices Alice_R and Alice_O have formed a Device Group
   1.274 -(cf. {{form-device-group}}), Alice buys another device, Alice_J,
   1.275 +Sometime after devices Alice_Mobile and Alice_Tablet have formed a Device Group
   1.276 +(cf. {{form-device-group}}), Alice buys another device, Alice_Laptop,
   1.277  which is also configured with pEp-implementing messaging clients and
   1.278  shares the same identity for her preferred communication channel (the
   1.279 -aforementioned email address). Alice_J also has a key pair, which was
   1.280 +aforementioned email address). Alice_Laptop also has a key pair, which was
   1.281  automatically generated by the pEp protocol, just as the Grouped
   1.282 -Devices Alice_R and Alice_O have. But while the Grouped Devices know
   1.283 -each other and have exchanged private keys, Alice_J and the Grouped
   1.284 -Devices don't know anything each other. Thus, Alice does not have full
   1.285 +Devices Alice_Mobile and Alice_Tablet have. But while the Grouped Devices know
   1.286 +each other and have exchanged private keys, Alice_Laptop and the Grouped
   1.287 +Devices don't know each other. Thus, Alice does not have full
   1.288  communication capability across the three devices.
   1.289  
   1.290  <!-- Editorial NOTE: Reference form-device-group may change due to
   1.291  auto numbering, ensure it is pointing to the one in this section -->
   1.292  
   1.293 -As before with devices Alice_R and Alice_O, Alice will use pEp Keysync
   1.294 -to add device Alice_J to the existing Device Group, allowing all three
   1.295 +As before with devices Alice_Mobile and Alice_Tablet, Alice will use pEp KeySync
   1.296 +to add device Alice_Laptop to the existing Device Group, allowing all three
   1.297  devices to exchange private key information, and Alice to have access
   1.298  to her messages from any of them.
   1.299  
   1.300 @@ -269,15 +262,14 @@
   1.301  ### Exchange Private Keys
   1.302  
   1.303  All devices from Alice are part of a Device Group
   1.304 -(cf. {{form-device-group}} and
   1.305 -{{add-new-device-to-existing-device-group}}). However, as keys may
   1.306 -expire or get reset<!-- TODO: Key Reset Reference, when out -->,
   1.307 -occasionally new key pairs are generated. For Alice to be able to read
   1.308 -all encrypted messages on all devices, any new private key needs to be
   1.309 -shared with the other devices in the device group. All devices in
   1.310 -Alice's Device Group will share the latest private keys as they are
   1.311 -generated, keeping all of her devices up to date and functioning as
   1.312 -desired.
   1.313 +(cf. {{form-device-group}} and {{add-new-device-to-existing-device-group}}).
   1.314 +However, as keys may expire or get reset <!-- (cf. {{I-D.marques-pep-keyreset}}) -->,
   1.315 +it is inevitable that new key pairs will be generated. For Alice to maintain
   1.316 +her ability to read all encrypted messages on all devices, any new
   1.317 +private key needs to be shared with the other devices in the device group.
   1.318 +All devices in Alice's Device Group will share the latest private keys
   1.319 +as they are generated, keeping all of her devices up to date and
   1.320 +functioning as desired.
   1.321  
   1.322  <!-- Editorial NOTE: References form-device-group /
   1.323  add-new-device-to-existing-device-group may change due to
   1.324 @@ -286,46 +278,29 @@
   1.325  
   1.326  ### Leave Device Group
   1.327  
   1.328 -<!--**[KRB] I'm not clear on the distinction between Leave and Remove
   1.329 -in this context. -->
   1.330 -
   1.331 -Alice may decide that one of her devices (e.g., her mobile phone)
   1.332 -should no longer have access to all private keys of the Device Group.
   1.333 -Alice can manually tell that device to leave the Device Group. The
   1.334 -Device Group will ensure that further communication among the
   1.335 -remaining Grouped Devices is private.
   1.336 -
   1.337 -<!-- HB: this is too much detail for use case description:
   1.338 -
   1.339 -     by issuing new Group Keys for all identities affected.
   1.340 --->
   1.341 -
   1.342 -<!-- TODO: Key Reset reference, when out. -->
   1.343 +Alice decides that her mobile phone, Alice_Mobile, should no longer have
   1.344 +access to all private keys of the Device Group. Alice can manually tell
   1.345 +her mobile phone to leave the Device Group by turning off the pEp Sync
   1.346 +feature on her device, which deactivates KeySync. The Device Group is
   1.347 +dissolved, and Sync is disabled on her mobile phone.
   1.348 +This action also initiates the pEp KeyReset protocol, which resets
   1.349 +keys for all own identities. <!-- NOTE: Only add the ref when KeyReset is ready (cf. {{I-D.marques-pep-keyreset}}). -->
   1.350 +
   1.351 +In the future, if Alice desires, she can re-add her mobile phone to
   1.352 +a Device Group, but she will first have to re-enable Sync, and then
   1.353 +initiate the joining procedure again (cf. {{form-device-group}}
   1.354 +and {{add-new-device-to-existing-device-group}}).
   1.355 +
   1.356 +
   1.357  
   1.358  ### Remove other Device from Device Group
   1.359  
   1.360 -<!--**[KRB] As noted above, I'm not clear on the distinction between
   1.361 -Leave and Remove in this context. -->
   1.362 -
   1.363  One of Alice's devices may be stolen or become otherwise compromised.
   1.364  She needs to ensure that the affected device no longer receives
   1.365  updates to private keys from the other devices in her Device Group.
   1.366 -Alice can initiate actions to mitigate the damage, including the
   1.367 -revocation of her private keys<!-- TODO: Key Reset Reference, when out
   1.368 --->, as well as forcibly removing the compromised device from her
   1.369 -Device Group.
   1.370 -
   1.371 -<!-- TODO: verify term: "forcibly remove" -->
   1.372 -
   1.373 -<!-- HB: Too much detail for use case description plus enters rat-hole
   1.374 -of device security:
   1.375 -
   1.376 -From one of her other remaining Grouped Devices the process to issue
   1.377 -new Group Keys for all identities affected can be started, such as to
   1.378 -mitigate the damage to the extent that an attacker able to unlock the
   1.379 -end-device might be able to read all past messages.
   1.380 -
   1.381 --->
   1.382 +Using one of her remaining Grouped Devices, Alice can disable pEp Sync
   1.383 +(and thus KeySync) on her remaining devices. This action dissolves
   1.384 +the Device Group and initiates the pEp KeyReset protocol. <!-- NOTE: add when ready: (cf. {{I-D.marques-pep-keyreset}}). -->
   1.385  
   1.386  <!--
   1.387  
   1.388 @@ -358,6 +333,19 @@
   1.389  skipped here for the sake of readability. Descriptions of the
   1.390  interactions are included after each diagram.
   1.391  
   1.392 +Each pEp-enabled device runs its own Finite-State Machine (FSM), which
   1.393 +interact with each other throughout the KeySync process, and drive the
   1.394 +UI options presented to the user. All messages are 'broadcast' between
   1.395 +devices. The TIDs added to each message allow the identification of
   1.396 +received messages which pertain to the ongoing transaction and its sender.
   1.397 +
   1.398 +For events requiring user interaction in order to proceed, it does not
   1.399 +matter which device has the specified option chosen first unless
   1.400 +otherwise indicated. For example, if an event states that the 'Offerer'
   1.401 +chooses 'Accept' to continue, the process will be unaffected if the
   1.402 +'Requester' device does so first. The only difference is that the order
   1.403 +of the roles for the remainder of the given scenario will be swapped.
   1.404 +
   1.405  <vspace blankLines="50" />
   1.406  
   1.407  ### Form Device Group
   1.408 @@ -378,36 +366,23 @@
   1.409  are defined during the start sequence, which is necessary for the FSM
   1.410  to work as intended.
   1.411  
   1.412 -During initialization of pEp KeySync, each device generates a UUID
   1.413 -version 4, variant 1 number, which is called a Transaction-ID (TID).
   1.414 +During initialization of pEp KeySync, each device generates a Transaction-ID (TID).
   1.415  These TIDs are sent as a challenge in a Beacon over the mutual
   1.416  channel, and the device roles of 'Offerer' and 'Requester' are
   1.417  determined by the numeric value of each device's unique TID.
   1.418  
   1.419 -
   1.420 -<!-- TODO: Consider adding TID to Terms section -->
   1.421 -
   1.422 -Note: All messages are 'broadcast'. The TIDs added to each message
   1.423 -allow the identification of received messages which pertain to the
   1.424 -ongoing transaction and its sender.
   1.425 -
   1.426 -
   1.427  1. Every device sends a Beacon message containing a challenge
   1.428     TID. Upon receipt of a Beacon message from another device, the
   1.429     received challenge TID is compared with the device's own
   1.430 -   challenge TID.  The device which has a TID with a lower numerical
   1.431 +   challenge TID. The device which has a TID with a lower numerical
   1.432     value is assigned as the 'Requester', and the other device is
   1.433     automatically assigned as the 'Offerer'.
   1.434  
   1.435 -   Note: The 'Offerer' device MUST NOT start a Negotiation. Thus, it
   1.436 -   re-sends its own Beacon (for robustness in case earlier Beacon
   1.437 -   message got lost) and waits. Message 1(r) depicts the Beacon
   1.438 +   Note: The 'Offerer' device MUST NOT start a Negotiation. In the event the
   1.439 +   earlier Beacon message is lost, the 'Offerer' device re-sends its
   1.440 +   own Beacon and waits for a response. Message 1(r) depicts the Beacon
   1.441     message sent by the 'Requester' device and is not required for the
   1.442     process to continue.
   1.443 -   
   1.444 -   <!-- [KRB] Minor rewording of second sentence: "In the event the
   1.445 -    earlier Beacon message is lost, the 'Offerer' device re-sends its
   1.446 -    own Beacon and waits for a response." -->
   1.447  
   1.448  2. After determination of the role, the 'Requester' device sends a
   1.449     NegotiationRequest message.
   1.450 @@ -415,57 +390,43 @@
   1.451  3. The 'Requester' device displays the Trustwords to the user.
   1.452  
   1.453  4. Upon receipt of the NegotiationRequest message, the
   1.454 -   'Offerer' device sends a NegotiationOpen message. 
   1.455 -   
   1.456 +   'Offerer' device sends a NegotiationOpen message.
   1.457 +
   1.458  5. The 'Offerer' device displays the Trustwords to the user.
   1.459  
   1.460  6. The user compares the Trustwords of both devices. As the Trustwords
   1.461 -   are the same on both devices, the user presses the 'Accept' button
   1.462 +   are the same on both devices, the user chooses the 'Accept' option
   1.463     on the 'Requester' device.
   1.464 -   
   1.465 -   Note 1: The user may also press the 'Accept' button on the
   1.466 -   'Offerer' device first. The end result is not affected by which
   1.467 -   'Accept' button is pressed first. However, the order of the
   1.468 -   messages slightly changes.
   1.469 -   
   1.470 -   Note 2: The user may also choose to press the 'Cancel' button or
   1.471 -   the 'Reject' button (see below).
   1.472  
   1.473     <!-- Add (stable) internal reference -->
   1.474 -   
   1.475 +
   1.476  7. On receipt of the user's 'Accept', the 'Requester' device sends a
   1.477     CommitAcceptRequester message.
   1.478  
   1.479     The 'Offerer' device receives this message and waits for the user to
   1.480 -   press the local 'Accept' button.
   1.481 -   
   1.482 -8. The user compares the Trustwords of both devices and presses the
   1.483 -   'Accept' button on the 'Offerer' device.
   1.484 -
   1.485 -   Note: The user may also choose to press the 'Cancel' button or the
   1.486 -   'Reject' button (see below).
   1.487 +   choose 'Accept'.
   1.488 +
   1.489 +8. The user compares the Trustwords of both devices and chooses the
   1.490 +   'Accept' option on the 'Offerer' device.
   1.491  
   1.492     <!-- Add (stable) internal reference -->
   1.493  
   1.494 -9. On receipt of the user's 'Accept', the 'Offerer' device sends
   1.495 +9. Once the user chooses 'Accept', the 'Offerer' device sends
   1.496     a CommitAcceptRequester message.
   1.497  
   1.498  10. The 'Offerer' device then sends an OwnKeysOfferer message along
   1.499      with the user's local key pairs (private and public keys) to  
   1.500      to be synchronized.
   1.501 -    
   1.502 +
   1.503  11. Upon receipt of the OwnKeysOfferer message, the 'Requester'
   1.504      device is Grouped and sends an OwnKeysRequester message along
   1.505      with the user's local key pairs (private and public keys) to be
   1.506      synchronized.
   1.507 -    
   1.508 -    Upon receipt of the OwnKeysRequester message, also the
   1.509 -    'Offerer' device is grouped. The formation of the Device Group has
   1.510 +
   1.511 +    Upon receipt of the OwnKeysRequester message, the
   1.512 +    'Offerer' device is also grouped. The formation of the Device Group has
   1.513      been successful.
   1.514  
   1.515 -<!-- TODO: KRB: Verb tense should be maintained through a paragraph,
   1.516 -and through an entire document when possible. -->
   1.517 -
   1.518  <vspace blankLines="50" />
   1.519  
   1.520  #### Unsuccessful Case
   1.521 @@ -479,19 +440,14 @@
   1.522  For unsuccessful KeySync attempts, messages 1-5 are the same as in a
   1.523  successful attempt (see above), but once the Trustwords are shown,
   1.524  events are as follows:
   1.525 -<!-- Add (stable) internal reference --> 
   1.526 +<!-- Add (stable) internal reference -->
   1.527  
   1.528  
   1.529  {::include ../shared/fence-line.mkd}
   1.530  
   1.531  R6.  The user compares the Trustwords of both devices. As the
   1.532 -     Trustwords do not match, the user presses the 'Reject' button on
   1.533 +     Trustwords do not match, the user chooses the 'Reject' option on
   1.534       the 'Requester' device.
   1.535 -   
   1.536 -     Note: The user may also press the 'Reject' button on the
   1.537 -     'Offerer' device first. The end result is not affected by which
   1.538 -     'Reject' button is pressed first. However, the order of the
   1.539 -     messages slightly changes.
   1.540  
   1.541  {::include ../shared/fence-line.mkd}
   1.542  
   1.543 @@ -505,9 +461,8 @@
   1.544  Once the CommitReject message is sent or received, respectively, the
   1.545  devices cannot form a Device Group, and pEp KeySync is disabled on
   1.546  both devices. As a result, there are no further attempts to form a
   1.547 -Device Group involving either of these two devices.
   1.548 -
   1.549 -<!-- TODO: clarify how sync can be re-enabled on a device -->
   1.550 +Device Group involving either of these two devices. KeySync may be
   1.551 +re-enabled in the pEp settings on the affected device(s).
   1.552  
   1.553  <vspace blankLines="50" />
   1.554  
   1.555 @@ -525,29 +480,11 @@
   1.556  
   1.557  {::include ../shared/fence-line.mkd}
   1.558  
   1.559 -C6.  The user decides to discontinue the process and presses the
   1.560 -     'Cancel' button on the 'Requester' device.
   1.561 -   
   1.562 -     Note: The user may also press the 'Cancel' button on the
   1.563 -     'Offerer' device first. The end result is not affected by which
   1.564 -     'Cancel' button is pressed first. However, the order of the
   1.565 -     messages slightly changes.
   1.566 -     
   1.567 +C6.  The user decides to discontinue the process and chooses the
   1.568 +     'Cancel' option on the 'Requester' device.
   1.569 +
   1.570  {::include ../shared/fence-line.mkd}
   1.571  
   1.572 -<!-- TODO:
   1.573 -     **[KRB] This is getting fairly repetitive. I'd suggest making a
   1.574 -    broad statement about the order of button presses in the
   1.575 -    successful case or maybe even before. Then you can delete these
   1.576 -    and streamline the section a bit.  Suggest: "For messages
   1.577 -    requiring button presses in order to proceed, it does not matter
   1.578 -    which device has the specified button pressed first unless
   1.579 -    otherwise specified.  E.g., if a message states that the 'Offerer'
   1.580 -    presses Accept to continue, it is acceptable for the 'Requester'
   1.581 -    device to do so first.  The only difference is that the order of
   1.582 -    the roles in subsequent messages changes as a result."
   1.583 --->
   1.584 -
   1.585  {::include ../shared/fence-line.mkd}
   1.586  
   1.587  C7. On receipt of the user's 'Cancel', the 'Requester' device sends
   1.588 @@ -555,9 +492,9 @@
   1.589  
   1.590  {::include ../shared/fence-line.mkd}
   1.591  
   1.592 -The devices do not form a Device Group. KeySync remains enabled and
   1.593 -forming a Device Group can start again.
   1.594 -   
   1.595 +The devices do not form a Device Group. KeySync remains enabled on
   1.596 +both devices, and forming a Device Group can start again.
   1.597 +
   1.598  <vspace blankLines="50" />
   1.599  
   1.600  ### Add New Device to Existing Device Group
   1.601 @@ -573,13 +510,9 @@
   1.602  As depicted above, a user intends to add a new device to an existing
   1.603  Device Group.
   1.604  
   1.605 -Note: All messages are 'broadcast'. The TIDs added to each message
   1.606 -allow the identification of received messages which pertain to the
   1.607 -ongoing transaction and its sender.
   1.608 -
   1.609  1. During initialization of pEp KeySync, the new device sends a Beacon
   1.610     message.
   1.611 -   
   1.612 +
   1.613     Note: In the diagram, all messages marked "1. Beacon" are a single
   1.614     message, but drawn separately in order to convey that the message
   1.615     is sent to all devices in the Device Group.
   1.616 @@ -587,75 +520,54 @@
   1.617  2. Upon receipt of a Beacon message from a device not part of a
   1.618     Device Group, all Grouped Devices are send a NegotiationRequest
   1.619     message.
   1.620 -   
   1.621 +
   1.622     Note: Messages 2(a) and 2(p) are different instances of the
   1.623     NegotiationRequest message type.
   1.624 -   
   1.625 +
   1.626  3. All Grouped Devices display the Trustwords to the user.
   1.627  
   1.628  4. Upon receipt of every NegotiationRequest message, the New
   1.629     Device sends a NegotiationOpen message.
   1.630 -   
   1.631 +
   1.632     Note: Messages 4(a) and 4(p) are different instances of the
   1.633     NegotiationOpen message type.
   1.634 -   
   1.635 +
   1.636  5. The new device displays the Trustwords to the user.
   1.637  
   1.638 -6. The user compares the Trustwords of both devices and presses the
   1.639 -   'Accept' button on one of the Grouped Devices.
   1.640 -   
   1.641 -   Note 1: The Grouped Device that the user presses the
   1.642 -   'Accept' button on now assumes the role of the active device in
   1.643 -   Group, while the other Grouped Devices get the role of passive
   1.644 -   devices in the group.
   1.645 -   
   1.646 -   <!-- TODO **[nk] maybe make explicit, that each device (equal
   1.647 -   which) of an already existing device group can be used as active
   1.648 -   device, resulting in all other devices becoming the passive ones.
   1.649 -   -->
   1.650 -   
   1.651 -   Note 2: The user may also press the 'Accept' button on the new
   1.652 -   device first. The end result is not affected by which
   1.653 -   'Accept' button is pressed first. However, the order and number of
   1.654 -   the messages change.
   1.655 -   
   1.656 -   Note 3: The user may also choose to press the 'Cancel' button or
   1.657 -   the 'Reject' button (see below).
   1.658 +6. The user compares the Trustwords of both devices and chooses the
   1.659 +   'Accept' option on one of the Grouped Devices.
   1.660 +
   1.661 +   Note 1: The Grouped Device that the user chooses the
   1.662 +   'Accept' option from assumes the role of the active device for the
   1.663 +   Device Group.
   1.664 +   <!-- get fdik to explain active vs passive devices, why they're important -->
   1.665  
   1.666     <!-- Add (stable) internal reference -->
   1.667 -   
   1.668 -7. On receipt of the user's 'Accept', the active Grouped Device
   1.669 -   sends a TrustThisKey message, which is consumed by the passive
   1.670 -   Grouped Devices.
   1.671 -
   1.672 -8. Then, the Active Grouped Device also sends a CommitAcceptForGroup
   1.673 -   message.
   1.674 -
   1.675 -   The new device receives this message and waits for the user to
   1.676 -   press the local 'Accept' button.
   1.677 -   
   1.678 -9. The user compares the Trustwords of both devices and presses the
   1.679 -   'Accept' button on the new device.
   1.680 -
   1.681 -   Note: The user may also choose to press the 'Cancel' button or the
   1.682 -   'Reject' button. However, these cases are explained later.
   1.683 -
   1.684 -   <!-- TODO: Add reference if section is ready -->
   1.685 -
   1.686 -10. On receipt of the user's 'Accept', the new device sends
   1.687 -    a CommitAccept message.
   1.688 -
   1.689 -11. The new device then sends a GroupKeys message along with its own
   1.690 +
   1.691 +7. On receipt of the user's 'Accept', the Active Grouped Device
   1.692 +   sends a TrustThisKey message to the passive Grouped Devices.
   1.693 +
   1.694 +8. The Active Grouped Device also sends a CommitAcceptForGroup
   1.695 +   message to the new device. Upon receipt, the new device waits for
   1.696 +   the user to choose 'Accept'.
   1.697 +
   1.698 +9. The user compares the Trustwords of both devices and chooses the
   1.699 +   'Accept' option on the new device.
   1.700 +
   1.701 +   <!-- TODO: Add Trustwords reference if section is ready -->
   1.702 +
   1.703 +10. Once the user chooses 'Accept', the new device sends a CommitAccept
   1.704 +    message to the Device Group.
   1.705 +
   1.706 +11. The new device then sends a GroupKeys message which contains its own
   1.707      private keys.
   1.708 -    
   1.709 -12. Upon receipt of the GroupKeys message, the Active Grouped Device
   1.710 -    is Grouped and sends a GroupKeys message along with its own
   1.711 -    private keys.  The new device has successfully joined the Device
   1.712 -    Group.
   1.713 -
   1.714 -<!-- TODO: KRB: Verb tense should be maintained through a paragraph,
   1.715 -and through an entire document when possible. -->
   1.716 -    
   1.717 +
   1.718 +12. Upon receipt of the GroupKeys message from the new device, the
   1.719 +    Active Grouped Device FSM transitions to state Grouped, adds the
   1.720 +    new device's keys to the GroupKeys, and sends a GroupKeys message
   1.721 +    to the entire Device Group. The new device has successfully joined
   1.722 +    the Device Group and all keys are synchronized among the devices.
   1.723 +
   1.724     Note: In the diagram, all messages marked "12. GroupKeys + keys"
   1.725     are a single message, but drawn separately in order to convey that
   1.726     the message is sent to all devices in the Device Group.
   1.727 @@ -673,39 +585,33 @@
   1.728  For unsuccessful KeySync attempts, messages 1-5 are the same as in a
   1.729  successful attempt (see above), but once the Trustwords are shown,
   1.730  events are as follows:
   1.731 -<!-- Add (stable) internal reference --> 
   1.732 +<!-- Add (stable) internal reference -->
   1.733  
   1.734  {::include ../shared/fence-line.mkd}
   1.735  
   1.736 -R6.  The user compares the Trustwords of both devices. As the
   1.737 -     Trustwords do not match, the user presses the 'Reject' button on
   1.738 -     one of the Grouped Devices.
   1.739 -   
   1.740 -     Note: The user may also press the 'Reject' button on the New
   1.741 -     Device first. The end result is not affected by which 'Reject'
   1.742 -     button is pressed first. However, the order and number of the
   1.743 -     messages slightly changes.
   1.744 +R6.  The user compares the Trustwords displayed on both devices. If the
   1.745 +     Trustwords do not match, the user chooses the 'Reject' option on
   1.746 +     one of the Grouped Devices. This issues a 'CommitReject' message
   1.747 +     to the FSM as well as all devices in the Device Group.
   1.748  
   1.749  {::include ../shared/fence-line.mkd}
   1.750  
   1.751  {::include ../shared/fence-line.mkd}
   1.752  
   1.753 -R7. On receipt of the user's 'Reject', the 'Requester' device sends
   1.754 -    a 'CommitReject' message.
   1.755 +R7. Upon receiving the 'Reject' message from the Device Group, the
   1.756 +    'Requester' device sends a 'CommitReject' message to the FSM.
   1.757  
   1.758      Note: In the diagram, all messages marked "R7. CommitReject"
   1.759      are a single message, but drawn separately in order to convey
   1.760      that the message is sent to all devices in the Device Group.
   1.761 -   
   1.762 +
   1.763  {::include ../shared/fence-line.mkd}
   1.764  
   1.765 -The new device does not join the group and pEp KeySync is disabled on it. As a
   1.766 -consequence, there are no further attempts to join the Device Group. 
   1.767 -
   1.768  Once the CommitReject message is sent or received, respectively, the new
   1.769  device cannot join the Device Group, and pEp KeySync is disabled on
   1.770  the new device. As a result, there are no further attempts to join a
   1.771 -Device Group by the new device.
   1.772 +Device Group by the new device. pEp KeySync may be re-enabled in the
   1.773 +pEp settings on the affected device.
   1.774  
   1.775  <vspace blankLines="50" />
   1.776  
   1.777 @@ -720,57 +626,54 @@
   1.778  For discontinued (canceled) KeySync attempts, messages 1-5 are the
   1.779  same as in a successful attempt (see above), but once the Trustwords
   1.780  are shown, events are as follows:
   1.781 -<!-- Add (stable) internal reference --> 
   1.782 +<!-- Add (stable) internal reference -->
   1.783  
   1.784  {::include ../shared/fence-line.mkd}
   1.785  
   1.786 -C6.  The user decides to discontinue the process and presses the
   1.787 -     'Cancel' button on one of the Grouped Devices.
   1.788 -   
   1.789 -     Note: The user may also press the 'Cancel' button on the New
   1.790 -     Device first. The end result is not affected by which 'Cancel'
   1.791 -     button is pressed first. However, the order and number of the
   1.792 -     messages slightly changes.
   1.793 +C6.  The user decides to discontinue the process and chooses the
   1.794 +     'Cancel' option on one of the Grouped Devices.
   1.795  
   1.796  {::include ../shared/fence-line.mkd}
   1.797  
   1.798  {::include ../shared/fence-line.mkd}
   1.799  
   1.800 -C7. On receipt of the user's 'Cancel', the 'Requester' device sends
   1.801 -    a rollback message.
   1.802 +C7. On receipt of the 'Cancel' from the 'Offerer' device, the
   1.803 +    'Requester' device sends a rollback message to the FSM.
   1.804  
   1.805      Note: In the diagram, all messages marked "C7. Rollback"
   1.806      are a single message, but drawn separately in order to convey
   1.807      that the message is sent to all devices in the Device Group.
   1.808 -    
   1.809 +
   1.810  {::include ../shared/fence-line.mkd}
   1.811  
   1.812  The new device does not join the Device Group. KeySync remains enabled
   1.813 -and joining a Device Group can start again.
   1.814 +and joining a Device Group can start again at any time.
   1.815  
   1.816  
   1.817  ### Exchange Private Keys
   1.818  
   1.819 -\[\[ TODO ]\]
   1.820 +\[\[ TODO ]\] <!-- private keys are exchanged via GroupKeys -->
   1.821 +
   1.822  
   1.823  ### Leave Device Group
   1.824  
   1.825 -\[\[ TODO \]\]
   1.826 +\[\[ TODO \]\] <!-- NOTE: This isn't part of the keysync fsm code. They are triggered by keyreset. -->
   1.827  
   1.828  ### Remove other Device from Device Group
   1.829  
   1.830 -\[\[ TODO \]\]
   1.831 +\[\[ TODO \]\] <!-- NOTE: This isn't part of the keysync fsm code. They are triggered by keyreset. -->
   1.832  
   1.833  <!--
   1.834  
   1.835  ### Synchronizing Trust
   1.836  
   1.837  \[\[TODO]\]: Interaction diagrams and descriptions for the use cases
   1.838 -above
   1.839 +above [KRB] Trust will have to wait until that draft is ready.
   1.840  
   1.841  -->
   1.842  
   1.843  <!--
   1.844 +NOTE: ask VB about these three items
   1.845  
   1.846  ## Roles and Keys
   1.847  
   1.848 @@ -790,26 +693,27 @@
   1.849  ### Sender Group key
   1.850  
   1.851  A Sender Group Key is a Sender's signing key, which is used to update
   1.852 -the Device Group information. If it is reset the Device Groups breaks.
   1.853 +the Device Group information. If it is reset, the Device Group breaks.
   1.854  
   1.855  -->
   1.856  
   1.857  
   1.858  
   1.859 +<!-- NOTE: This entire section just creates more confusion, I think.
   1.860 +We already have diagrams above, and the full FSM description below.
   1.861  ## Simplified Finite-State Machine
   1.862  
   1.863  A simplified diagram of the implemented pEp KeySync finite-state
   1.864  machine (FSM), which does not contain the transitions that occur
   1.865 -when pressing the 'Cancel' or 'Reject' buttons, can be found at:
   1.866 +when choosing the 'Cancel' or 'Reject' options, can be found at:
   1.867  https://pep.foundation/dev/repos/internet-drafts/raw-file/tip/misc/figures/sync/sync_fsm_simplified.svg
   1.868  
   1.869  
   1.870 -<!--
   1.871 -The following figures are simplified excepts of the implemented pEp
   1.872 -KeySync finite-state machine (FSM).
   1.873 -
   1.874 -The States and Events that fire a transition are described in
   1.875 -{{full-finite-state-machine}}.
   1.876 +The following figures are simplified excerpts of the implemented pEp
   1.877 +KeySync Finite-State Machine (FSM).
   1.878 +
   1.879 +The states, actions, events, and messages that fire during these
   1.880 +interactions are described in {{full-finite-state-machine}}.
   1.881  
   1.882  
   1.883  ### FSM Form Device Group
   1.884 @@ -852,30 +756,35 @@
   1.885  
   1.886  # Reference Implementation
   1.887  
   1.888 -\[\[ Note: This description of the FSM implementation is
   1.889 -Work-In-Progress. For now it is supposed to be sufficient for the
   1.890 -reader to understand the general functionality of the FSM, and thus
   1.891 -lacking certain details. The authors intend to enhance and refine it
   1.892 -in later revisions of this document. \]\]
   1.893 -
   1.894 -## Full Finite-State Machine
   1.895 +\[\[ Note: The full Finite-State Machine code can be found in Appendix A.
   1.896 +This section is not a complete reference at this time. The authors
   1.897 +intend to refine this section in future revisions of this document. \]\]
   1.898 +
   1.899 +The pEp KeySync Finite-State Machine is based on a two-phase commit
   1.900 +protocol (2PC) structure. This section describes the states, actions,
   1.901 +events, and messages which comprise the pEp KeySync FSM, and are
   1.902 +intended to allow readers to understand the general functionality
   1.903 +and message flow of the FSM.
   1.904 +
   1.905 +States are used to direct actions, events, and messages. Actions
   1.906 +describe internal FSM functions, and fall into two general types.
   1.907 +The first action type directs the state transitions within the FSM,
   1.908 +and the second type drives UI functionality. Events are exchanged both
   1.909 +between negotiation partners as well as the pEp Engine itself to
   1.910 +trigger actions and send messages. Messages contain information to
   1.911 +ensure the integrity of the KeySync session as well as additional data,
   1.912 +depending on the type of message (cf. {{messages}}). <!-- verify this internal link works -->
   1.913 +
   1.914 +## Full Finite-State Machine Diagram
   1.915  
   1.916  A full diagram of the implemented pEp KeySync FSM can be found at the
   1.917  following URL:
   1.918  
   1.919  https://pep.foundation/dev/repos/internet-drafts/raw-file/tip/misc/figures/sync/sync_fsm_full.svg
   1.920 -
   1.921 +<!-- verify this link is still good -->
   1.922  
   1.923  ### States
   1.924  
   1.925 -<!--
   1.926 -####  None
   1.927 -
   1.928 -KeySync_state_None = None
   1.929 -\[\[ Not sure this is needed \]\]
   1.930 -
   1.931 --->
   1.932 -
   1.933  ####  InitState
   1.934  
   1.935  On initialization, the FSM enters InitState, which evaluates and
   1.936 @@ -884,569 +793,242 @@
   1.937  Grouped. Otherwise, the FSM transitions to state Sole
   1.938  (cf. {{devicegrouped-conditional}}).
   1.939  
   1.940 -{::include ../shared/text-blocks/more-info-following-code.mkd}
   1.941 -
   1.942 -{::include ../shared/fence-line.mkd}
   1.943 -
   1.944 -        state InitState {
   1.945 -            on Init {
   1.946 -                if deviceGrouped
   1.947 -                    go Grouped;
   1.948 -                go Sole;
   1.949 -            }
   1.950 -        }
   1.951 -
   1.952 -{::include ../shared/fence-line.mkd}
   1.953  
   1.954  ####  Sole
   1.955  
   1.956 -This is the default state for an ungrouped device. On initialization,
   1.957 -a challenge TID is created and sent out inside a Beacon message. It
   1.958 -waits also for Beacons from other devices. Upon receipt of a Beacon
   1.959 -message from another device, the received challenge TID is compared
   1.960 -with the own challenge. The device with the lower challenge TID
   1.961 -becomes 'Requester', the one with higher challenge TID becomes
   1.962 -'Offerer'.
   1.963 -
   1.964 -<!-- TODO:
   1.965 -KRB: Also, if earlier suggestions up in the first discussion of the challenge
   1.966 -TID process are accepted, they should be reflected here as well.
   1.967 --->
   1.968 -
   1.969 -If determined to be 'Requester', a NegotiationRequest message is sent.
   1.970 -
   1.971 -The device determined as 'Offerer' receives the NegotiationRequest
   1.972 -message, sends a NegotiationOpen message as response and the FSM transitions
   1.973 -to state HandshakingOfferer.
   1.974 -
   1.975 -On receipt of the NegotiationOpen message, the 'Requester' FSM
   1.976 -proceeds in one of two ways. If the NegotiationOpen message comes from
   1.977 -a Sole 'Offerer' Device, the FSM transitions to state
   1.978 -HandshakingRequester. If the NegotiationOpen message comes from a
   1.979 -Grouped Device, the FSM transitions to state HandshakingToJoin.
   1.980 -
   1.981 -   
   1.982 -{::include ../shared/text-blocks/more-info-following-code.mkd}
   1.983 -
   1.984 -{::include ../shared/fence-line.mkd}
   1.985 -
   1.986 -        state Sole timeout=off {
   1.987 -            on Init {
   1.988 -                do newChallengeAndNegotiationBase;
   1.989 -                do showBeingSole;
   1.990 -                send Beacon;
   1.991 -            }
   1.992 -
   1.993 -            on KeyGen {
   1.994 -                send Beacon;
   1.995 -            }
   1.996 -
   1.997 -            on CannotDecrypt { // cry baby
   1.998 -                send Beacon;
   1.999 -            }
  1.1000 -
  1.1001 -            on Beacon {
  1.1002 -                if sameChallenge {
  1.1003 -                    // this is our own Beacon; ignore
  1.1004 -                }
  1.1005 -                else {
  1.1006 -                    if weAreOfferer {
  1.1007 -                        do useOwnChallenge;
  1.1008 -                        send Beacon;
  1.1009 -                    }
  1.1010 -                    else /* we are requester */ {
  1.1011 -                        do openNegotiation;
  1.1012 -                        do tellWeAreNotGrouped;
  1.1013 -                        // requester is sending NegotiationRequest
  1.1014 -                        send NegotiationRequest;
  1.1015 -                        do useOwnChallenge;
  1.1016 -                    }
  1.1017 -                }
  1.1018 -            }
  1.1019 -           on NegotiationRequest {
  1.1020 -                if sameChallenge { // challenge accepted
  1.1021 -                    if sameNegotiation {
  1.1022 -                        // this is our own NegotiationRequest; ignore
  1.1023 -                    }
  1.1024 -                    else {
  1.1025 -                        do storeNegotiation;
  1.1026 -                        // offerer is accepting
  1.1027 -                        // by confirming NegotiationOpen
  1.1028 -                        send NegotiationOpen;
  1.1029 -                        if partnerIsGrouped
  1.1030 -                            go HandshakingToJoin;
  1.1031 -                        else
  1.1032 -                            go HandshakingOfferer;
  1.1033 -                    }
  1.1034 -                }
  1.1035 -            }
  1.1036 -
  1.1037 -            on NegotiationOpen if sameNegotiationAndPartner {
  1.1038 -                // requester is receiving NegotiationOpen
  1.1039 -                do storeNegotiation;
  1.1040 -                go HandshakingRequester;
  1.1041 -            }
  1.1042 -        }
  1.1043 -
  1.1044 -{::include ../shared/fence-line.mkd}
  1.1045 +This is the default FSM state for an ungrouped device.
  1.1046 +
  1.1047 +On initialization, a challenge TID is created and sent out inside of
  1.1048 +a Beacon message along with the device's current state. The FSM also
  1.1049 +listens for Beacons from other devices. Upon receipt of a Beacon message
  1.1050 +from another device, the received challenge TID is compared with the
  1.1051 +own challenge. The device with the lower challenge TID is assigned the
  1.1052 +'Requester' role, and the other device is automatically assigned the
  1.1053 +'Offerer' role.
  1.1054 +
  1.1055 +If a device is determined to be the 'Requester', it issues a
  1.1056 +NegotiationRequest event to the 'Offerer'.
  1.1057 +
  1.1058 +When the 'Offerer' device receives this NegotiationRequest message, it
  1.1059 +responds with a NegotiationOpen message, and the 'Offerer' FSM
  1.1060 +transitions to state HandshakingOfferer while it awaits the
  1.1061 +'Requester' device response.
  1.1062 +
  1.1063 +On receipt of the 'Offerer' device's NegotiationOpen message, the
  1.1064 +'Requester' FSM proceeds in one of two ways, depending on the
  1.1065 +'Offerer' device state:
  1.1066 +
  1.1067 +* Sole: The 'Requester' FSM transitions to state HandshakingRequester.
  1.1068 +
  1.1069 +* Grouped: The 'Requester' FSM transitions to state HandshakingToJoin.
  1.1070  
  1.1071  
  1.1072  ####  HandshakingOfferer
  1.1073  
  1.1074 -This state is entered by the 'Offerer' device only. The FSM waits for
  1.1075 -the user to compare the Trustwords and to press either of the
  1.1076 -following buttons (on the 'Offerer' device):
  1.1077 -
  1.1078 -* Accept: A CommitAcceptOfferer message is sent and the FSM transitions to
  1.1079 -  state HandshakingPhase1Offerer
  1.1080 -  
  1.1081 -* Reject: A CommitReject message is sent, pEp KeySync is disabled, and
  1.1082 -  the FSM transitions to state End
  1.1083 -
  1.1084 -* Cancel: A Rollback message is sent and the FSM transitions to state Sole
  1.1085 -
  1.1086 -If the 'Accept' button was pressed on the 'Requester' device, a
  1.1087 -CommitAcceptRequester message is received and the FSM transitions to state
  1.1088 -HandshakingPhase2Offerer.
  1.1089 -
  1.1090 -If the 'Reject' button was pressed on the 'Requester' device, a
  1.1091 -CommitReject message is received. pEp KeySync is disabled and the FSM
  1.1092 -transitions to state End.
  1.1093 -
  1.1094 -If the 'Cancel' button was pressed on the 'Requester' device, a
  1.1095 -Rollback message is received and the FSM transitions to state Sole.
  1.1096 -
  1.1097 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.1098 -
  1.1099 -{::include ../shared/fence-line.mkd}
  1.1100 -
  1.1101 -        // handshaking without existing Device group
  1.1102 -        state HandshakingOfferer timeout=600 {
  1.1103 -            on Init
  1.1104 -                do showSoleHandshake;
  1.1105 -
  1.1106 -            // Cancel is Rollback
  1.1107 -            on Cancel {
  1.1108 -                send Rollback;
  1.1109 -                go Sole;
  1.1110 -            }
  1.1111 -
  1.1112 -            on Rollback if sameNegotiationAndPartner
  1.1113 -                go Sole;
  1.1114 -
  1.1115 -            // Reject is CommitReject
  1.1116 -            on Reject {
  1.1117 -                send CommitReject;
  1.1118 -                do disable;
  1.1119 -                go End;
  1.1120 -            }
  1.1121 -
  1.1122 -            on CommitReject if sameNegotiationAndPartner {
  1.1123 -                do disable;
  1.1124 -                go End;
  1.1125 -            }
  1.1126 -
  1.1127 -            // Accept means init Phase1Commit
  1.1128 -            on Accept {
  1.1129 -                do trustThisKey;
  1.1130 -                send CommitAcceptOfferer;
  1.1131 -                go HandshakingPhase1Offerer;
  1.1132 -            }
  1.1133 -
  1.1134 -            // got a CommitAccept from requester
  1.1135 -            on CommitAcceptRequester if sameNegotiationAndPartner
  1.1136 -                go HandshakingPhase2Offerer;
  1.1137 -        }
  1.1138 -
  1.1139 -{::include ../shared/fence-line.mkd}
  1.1140 +This state can only be entered by the 'Offerer' device in a Sole state,
  1.1141 +and drives user interface options, including the Trustwords dialog.
  1.1142 +The user is prompted to compare Trustwords and choose from the
  1.1143 +following options:
  1.1144 +
  1.1145 +* Accept: A CommitAcceptOfferer message is sent to the 'Requester' device,
  1.1146 +  and the FSM transitions to state HandshakingPhase1Offerer while it
  1.1147 +  waits for a response.
  1.1148 +
  1.1149 +* Reject: A CommitReject message is sent to the 'Requester' device,
  1.1150 +  pEp KeySync is disabled, and the FSM transitions to state End.
  1.1151 +
  1.1152 +* Cancel: A Rollback message is sent to the 'Requester' device,
  1.1153 +  and the FSM transitions to state Sole.
  1.1154 +
  1.1155 +Once the user selects one of the above options on the 'Offerer'
  1.1156 +device, the FSM waits for a response from the 'Requester' device.
  1.1157 +When this response is received, the 'Offerer' FSM performs a
  1.1158 +sameNegotiationAndPartner conditional check to verify the session
  1.1159 +integrity. If this conditional returns 'true', the FSM proceeds as
  1.1160 +follows, depending on the message received:
  1.1161 +
  1.1162 +* CommitAcceptRequester: The 'Requester' device public key is
  1.1163 +  trusted, and the FSM transitions to state HandshakingPhase2Offerer.
  1.1164 +
  1.1165 +* CommitReject: pEp KeySync is disabled, and the FSM transitions to state End.
  1.1166 +
  1.1167 +* Rollback: The FSM transitions to state Sole.
  1.1168  
  1.1169  
  1.1170  ####  HandshakingRequester
  1.1171  
  1.1172 -This state is similar to the HandshakingOfferer
  1.1173 -(cf. {{handshakingofferer}}), but with swapped roles.
  1.1174 -
  1.1175 -This state is entered by the 'Requester' device only. The FSM waits
  1.1176 -for the user to compare the Trustwords and to press either of the
  1.1177 -following buttons (on the 'Requester' device):
  1.1178 -
  1.1179 -* Accept: A CommitAcceptOfferer message is sent and the FSM transitions to
  1.1180 -  state HandshakingPhase1Requester
  1.1181 -  
  1.1182 -* Reject: A CommitReject message is sent, pEp KeySync is disabled, and
  1.1183 -  the FSM transitions to state End
  1.1184 -  
  1.1185 -* Cancel: A Rollback message is sent and the FSM transitions to state Sole
  1.1186 -
  1.1187 -If the 'Accept' button was pressed on the 'Offerer' device, a
  1.1188 -CommitAcceptOfferer message is received and the FSM transitions to state
  1.1189 -HandshakingPhase2Requester.
  1.1190 -
  1.1191 -If the 'Reject' button was pressed on the 'Offerer' device, a
  1.1192 -CommitReject message is received. pEp KeySync is disabled and the FSM
  1.1193 -transitions to state End.
  1.1194 -
  1.1195 -If the 'Cancel' button was pressed on the 'Offerer' device, a Rollback
  1.1196 -message is received and the FSM transitions to state Sole.
  1.1197 -
  1.1198 -
  1.1199 -
  1.1200 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.1201 -
  1.1202 -{::include ../shared/fence-line.mkd}
  1.1203 -
  1.1204 -        state HandshakingRequester timeout=600 {
  1.1205 -            on Init
  1.1206 -                do showSoleHandshake;
  1.1207 -
  1.1208 -            // Cancel is Rollback
  1.1209 -            on Cancel {
  1.1210 -                send Rollback;
  1.1211 -                go Sole;
  1.1212 -            }
  1.1213 -
  1.1214 -            on Rollback if sameNegotiationAndPartner
  1.1215 -                go Sole;
  1.1216 -
  1.1217 -            // Reject is CommitReject
  1.1218 -            on Reject {
  1.1219 -                send CommitReject;
  1.1220 -                do disable;
  1.1221 -                go End;
  1.1222 -            }
  1.1223 -
  1.1224 -            on CommitReject if sameNegotiationAndPartner {
  1.1225 -                do disable;
  1.1226 -                go End;
  1.1227 -            }
  1.1228 -
  1.1229 -            // Accept means init Phase1Commit
  1.1230 -            on Accept {
  1.1231 -                do trustThisKey;
  1.1232 -                send CommitAcceptRequester;
  1.1233 -                go HandshakingPhase1Requester;
  1.1234 -            }
  1.1235 -
  1.1236 -            // got a CommitAccept from offerer
  1.1237 -            on CommitAcceptOfferer if sameNegotiationAndPartner
  1.1238 -                go HandshakingPhase2Requester;
  1.1239 -        }
  1.1240 -
  1.1241 -        state HandshakingPhase1Offerer {
  1.1242 -            on Rollback if sameNegotiationAndPartner {
  1.1243 -                do untrustThisKey;
  1.1244 -                go Sole;
  1.1245 -            }
  1.1246 -            
  1.1247 -            on CommitReject if sameNegotiationAndPartner {
  1.1248 -                do untrustThisKey;
  1.1249 -                do disable;
  1.1250 -                go End;
  1.1251 -            }
  1.1252 -
  1.1253 -            on CommitAcceptRequester if sameNegotiationAndPartner {
  1.1254 -                go FormingGroupOfferer;
  1.1255 -            }
  1.1256 -        }
  1.1257 -
  1.1258 -{::include ../shared/fence-line.mkd}
  1.1259 +This state can only be entered by the 'Requester' device in a Sole state,
  1.1260 +and drives user interface options, including the Trustwords dialog.
  1.1261 +The user is prompted to compare Trustwords, and choose from the
  1.1262 +following options:
  1.1263 +
  1.1264 +* Accept: A CommitAcceptRequester message is sent to the 'Offerer' device,
  1.1265 +  the 'Offerer' public key is trusted, and the FSM transitions to state
  1.1266 +  HandshakingPhase1Requester while it waits for a response.
  1.1267 +
  1.1268 +* Reject: A CommitReject message is sent to the 'Offerer' device,
  1.1269 +  pEp KeySync is disabled, and the FSM transitions to state End.
  1.1270 +
  1.1271 +* Cancel: A Rollback message is sent to the 'Offerer' device, and the
  1.1272 +  FSM transitions to state Sole.
  1.1273 +
  1.1274 +Once the user selects one of the above options on the 'Requester'
  1.1275 +device, the FSM waits for a response from the 'Offerer' device.
  1.1276 +When this response is received, the 'Requester' FSM performs a
  1.1277 +sameNegotiationAndPartner conditional check to verify the session
  1.1278 +integrity. If this conditional returns 'true', the FSM proceeds as
  1.1279 +follows, depending on the message received:
  1.1280 +
  1.1281 +* CommitAcceptOfferer: The FSM transitions to state HandshakingPhase2Requester.
  1.1282 +
  1.1283 +* CommitReject: pEp KeySync is disabled, and the FSM transitions to state End.
  1.1284 +
  1.1285 +* Rollback: The FSM transitions to state Sole.
  1.1286  
  1.1287  
  1.1288  ####  HandshakingPhase1Offerer
  1.1289  
  1.1290 -This state is entered by the 'Offerer' device only. The FSM waits for
  1.1291 -the user to finish the handshake on the 'Requester´ device
  1.1292 -(i.e. compare the Trustwords and press either of the buttons on the
  1.1293 -'Requester' device):
  1.1294 -
  1.1295 -If the 'Accept' button was pressed on the 'Requester' device, a
  1.1296 -CommitAcceptRequester message is received and the FSM transitions to state
  1.1297 -FormingGroupOfferer.
  1.1298 -
  1.1299 -If the 'Reject' button was pressed on the 'Requester' device, a
  1.1300 -CommitReject message is received. pEp KeySync is disabled and the FSM
  1.1301 -transitions to state End.
  1.1302 -
  1.1303 -If the 'Cancel' button was pressed on the 'Requester' device, a
  1.1304 -Rollback message is received and the FSM transitions to state Sole.
  1.1305 -
  1.1306 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.1307 -
  1.1308 -{::include ../shared/fence-line.mkd}
  1.1309 -
  1.1310 -       state HandshakingPhase1Offerer {
  1.1311 -            on Rollback if sameNegotiationAndPartner {
  1.1312 -                do untrustThisKey;
  1.1313 -                go Sole;
  1.1314 -            }
  1.1315 -            
  1.1316 -            on CommitReject if sameNegotiationAndPartner {
  1.1317 -                do untrustThisKey;
  1.1318 -                do disable;
  1.1319 -                go End;
  1.1320 -            }
  1.1321 -
  1.1322 -            on CommitAcceptRequester if sameNegotiationAndPartner {
  1.1323 -                go FormingGroupOfferer;
  1.1324 -            }
  1.1325 -        }
  1.1326 -
  1.1327 -{::include ../shared/fence-line.mkd}
  1.1328 +This state can only be entered by the 'Offerer' device in a Sole state.
  1.1329 +
  1.1330 +This state awaits and processes the response from a 'Requester' device
  1.1331 +in state HandshakingRequester. When this response is received, the
  1.1332 +'Offerer' FSM performs a sameNegotiationAndPartner conditional check to
  1.1333 +verify the session integrity. If this conditional returns 'true',
  1.1334 +the FSM proceeds as follows, depending on the message received:
  1.1335 +
  1.1336 +* CommitAcceptRequester: The FSM transitions to state FormingGroupOfferer.
  1.1337 +
  1.1338 +* CommitReject: The 'Requester' public key is mistrusted, pEp KeySync
  1.1339 +  is disabled, and the FSM transitions to state End.
  1.1340 +
  1.1341 +* Rollback: The 'Requester' public key is mistrusted, and the FSM
  1.1342 +  transitions to state Sole.
  1.1343  
  1.1344  
  1.1345  ####  HandshakingPhase1Requester
  1.1346  
  1.1347 -This state is similar to the HandshakingPhase1Offerer
  1.1348 -(cf. {{handshakingphase1offerer}}), but with swapped roles.
  1.1349 -
  1.1350 -This state is entered by the 'Requester' device only. The FSM waits
  1.1351 -for the user to finish the handshake on the 'Offerer´ device
  1.1352 -(i.e. compare the Trustwords and press either of the buttons on the
  1.1353 -'Offerer' device):
  1.1354 -
  1.1355 -If the 'Accept' button was pressed on the 'Offerer' device, a
  1.1356 -CommitAcceptRequester message is received and the FSM transitions to state
  1.1357 -FormingGroupOfferer.
  1.1358 -
  1.1359 -If the 'Reject' button was pressed on the 'Offerer' device, a
  1.1360 -CommitReject message is received. pEp KeySync is disabled and the FSM
  1.1361 -transitions to state End.
  1.1362 -
  1.1363 -If the 'Cancel' button was pressed on the 'Offerer' device, a Rollback
  1.1364 -message is received and the FSM transitions to state Sole.
  1.1365 -
  1.1366 -<!-- TODO: mention untrustThisKey everywhere it appears -->
  1.1367 -
  1.1368 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.1369 -
  1.1370 -{::include ../shared/fence-line.mkd}
  1.1371 -
  1.1372 -        state HandshakingPhase1Requester {
  1.1373 -            on Rollback if sameNegotiationAndPartner {
  1.1374 -                do untrustThisKey;
  1.1375 -                go Sole;
  1.1376 -            }
  1.1377 -            
  1.1378 -            on CommitReject if sameNegotiationAndPartner {
  1.1379 -                do untrustThisKey;
  1.1380 -                do disable;
  1.1381 -                go End;
  1.1382 -            }
  1.1383 -            on CommitAcceptOfferer if sameNegotiationAndPartner {
  1.1384 -                go FormingGroupRequester;
  1.1385 -            }
  1.1386 -        }
  1.1387 -
  1.1388 -{::include ../shared/fence-line.mkd}
  1.1389 +This state can only be entered by the 'Requester' device in a Sole state.
  1.1390 +
  1.1391 +This state awaits and processes the response from an 'Offerer' device
  1.1392 +in state HandshakingOfferer. When this response is received, the
  1.1393 +'Requester' FSM performs a sameNegotiationAndPartner conditional check
  1.1394 +to verify the session integrity. If this conditional returns 'true',
  1.1395 +the FSM proceeds as follows, depending on the message received:
  1.1396 +
  1.1397 +* CommitAcceptOfferer: The FSM transitions to state FormingGroupRequester.
  1.1398 +
  1.1399 +* CommitReject: The 'Offerer' public key is mistrusted, pEp KeySync
  1.1400 +  is disabled, and the FSM transitions to state End.
  1.1401 +
  1.1402 +* Rollback: The 'Offerer' public key is mistrusted, and the FSM
  1.1403 +  transitions to state Sole.
  1.1404  
  1.1405  
  1.1406  ####  HandshakingPhase2Offerer
  1.1407  
  1.1408 -This state is entered by the 'Offerer' device only. The FSM waits for
  1.1409 -the user to compare the Trustwords and to press either of the
  1.1410 -following buttons (on the 'Offerer' device):
  1.1411 -
  1.1412 -* Accept: The key used in the handshake is marked 'trusted', a
  1.1413 -  CommitAcceptOfferer message is sent and the FSM transitions to state
  1.1414 -  FormingGroupOfferer
  1.1415 -
  1.1416 -<!-- TODO: verify trustThisKey everywhere it appears -->
  1.1417 -
  1.1418 -* Reject: A CommitReject message is sent, pEp KeySync is disabled, and
  1.1419 -  the FSM transitions to state End
  1.1420 -
  1.1421 -* Cancel: A Rollback message is sent and the FSM transitions to state Sole
  1.1422 -
  1.1423 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.1424 -
  1.1425 -{::include ../shared/fence-line.mkd}
  1.1426 -
  1.1427 -       state HandshakingPhase2Offerer {
  1.1428 -            on Cancel {
  1.1429 -                send Rollback;
  1.1430 -                go Sole;
  1.1431 -            }
  1.1432 -
  1.1433 -            on Reject {
  1.1434 -                send CommitReject;
  1.1435 -                do disable;
  1.1436 -                go End;
  1.1437 -            }
  1.1438 -
  1.1439 -            on Accept {
  1.1440 -                send CommitAcceptOfferer;
  1.1441 -                do trustThisKey;
  1.1442 -                go FormingGroupOfferer;
  1.1443 -            }
  1.1444 -        }
  1.1445 -
  1.1446 -{::include ../shared/fence-line.mkd}
  1.1447 +This state can only be entered by the 'Offerer' device in a Sole state.
  1.1448 +
  1.1449 +The FSM waits for the 'Offerer' device in state HandshakingPhase1Offerer
  1.1450 +to process the 'Requester' device response. Once that is done, the
  1.1451 +following UI options are displayed for the 'Offerer' device:
  1.1452 +
  1.1453 +* Accept: The 'Requester' public key used in the handshake is marked
  1.1454 +  'trusted', a CommitAcceptOfferer message is issued to the 'Requester',
  1.1455 +  and the FSM transitions to state FormingGroupOfferer.
  1.1456 +
  1.1457 +* Reject: A CommitReject message is issued to the 'Requester' device,
  1.1458 +  pEp KeySync is disabled, and the FSM transitions to state End.
  1.1459 +
  1.1460 +* Cancel: A Rollback message is issued to the 'Requester' device, and
  1.1461 +  the FSM transitions to state Sole.
  1.1462  
  1.1463  
  1.1464  ####  HandshakingPhase2Requester
  1.1465  
  1.1466 -This state is similar to the HandshakingPhase2Offerer
  1.1467 -(cf. {{handshakingphase2offerer}}), but with swapped roles.
  1.1468 -
  1.1469 -This state is entered by the 'Requester' device only. The FSM waits
  1.1470 -for the user to compare the Trustwords and to press either of the
  1.1471 -following buttons (on the 'Requester' device):
  1.1472 -
  1.1473 -* Accept: The key used in the handshake is marked 'trusted', a
  1.1474 -  CommitAcceptOfferer message is sent and the FSM transitions to state
  1.1475 -  FormingGroupRequester
  1.1476 -  
  1.1477 -* Reject: A CommitReject message is sent, pEp KeySync is disabled, and
  1.1478 -  the FSM transitions to state End
  1.1479 -
  1.1480 -* Cancel: A Rollback message is sent and the FSM transitions to state Sole
  1.1481 -
  1.1482 -
  1.1483 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.1484 -
  1.1485 -{::include ../shared/fence-line.mkd}
  1.1486 -
  1.1487 -       state HandshakingPhase2Requester {
  1.1488 -            on Cancel {
  1.1489 -                send Rollback;
  1.1490 -                go Sole;
  1.1491 -            }
  1.1492 -
  1.1493 -            on Reject {
  1.1494 -                send CommitReject;
  1.1495 -                do disable;
  1.1496 -                go End;
  1.1497 -            }
  1.1498 -
  1.1499 -            on Accept {
  1.1500 -                send CommitAcceptRequester;
  1.1501 -                do trustThisKey;
  1.1502 -                go FormingGroupRequester;
  1.1503 -            }
  1.1504 -        }
  1.1505 -
  1.1506 -{::include ../shared/fence-line.mkd}
  1.1507 +This state can only be entered by the 'Requester' device in a Sole state.
  1.1508 +
  1.1509 +The FSM waits for the 'Requester' device in state HandshakingPhase1Requester
  1.1510 +to process the 'Offerer' device response. Once that is done, the
  1.1511 +following UI options are displayed for the 'Requester' device:
  1.1512 +
  1.1513 +* Accept: The 'Offerer' public key used in the handshake is marked
  1.1514 +  'trusted', a CommitAcceptRequester message is issued to the 'Offerer'
  1.1515 +  device, and the FSM transitions to state FormingGroupRequester.
  1.1516 +
  1.1517 +* Reject: A CommitReject message is issued to the 'Offerer' device,
  1.1518 +  pEp KeySync is disabled, and the FSM transitions to state End.
  1.1519 +
  1.1520 +* Cancel: A Rollback message is issued to the 'Offerer' device, and
  1.1521 +  the FSM transitions to state Sole.
  1.1522  
  1.1523  
  1.1524  ####  FormingGroupOfferer
  1.1525  
  1.1526 -This state is entered by the 'Offerer' device only. The FSM sends a
  1.1527 -OwnKeysOfferer along with its own keys, and waits to receive the
  1.1528 -keys from the 'Requester' device. Once received, the 'Requester'
  1.1529 -keys are saved and marked as Default Keys. The Device Group is
  1.1530 -created and the FSM transitions to state Grouped.
  1.1531 -
  1.1532 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.1533 -
  1.1534 -{::include ../shared/fence-line.mkd}
  1.1535 -
  1.1536 -       state FormingGroupOfferer {
  1.1537 -            on Init {
  1.1538 -                do prepareOwnKeys;
  1.1539 -                send OwnKeysOfferer; // we're not grouped yet,
  1.1540 -                                     // this is our own keys
  1.1541 -            }
  1.1542 -
  1.1543 -            on OwnKeysRequester {
  1.1544 -                do saveGroupKeys;
  1.1545 -                do receivedKeysAreDefaultKeys;
  1.1546 -                do showGroupCreated;
  1.1547 -                go Grouped;
  1.1548 -            }
  1.1549 -        }
  1.1550 -
  1.1551 -{::include ../shared/fence-line.mkd}
  1.1552 +This state can only be entered by the 'Offerer' device in a Sole state.
  1.1553 +
  1.1554 +In this state, the user is given two options: Initialize the final
  1.1555 +step of the KeySync process (exchange of private key information),
  1.1556 +or Cancel.
  1.1557 +
  1.1558 +* Init: The FSM prepares the Own Keys on the 'Offerer'
  1.1559 +  device for synchronization. The FSM then issues an OwnKeysOfferer
  1.1560 +  message which contains these keys, triggers a UI event to indicate
  1.1561 +  that Device Group formation is in progress, and awaits a response
  1.1562 +  from the 'Requester' device.
  1.1563 +
  1.1564 +  Once the 'Requester' responds with a OwnKeysRequester message, the
  1.1565 +  'Requester' device keys are received, combined with the 'Offerer' keys,
  1.1566 +  and saved in a shared GroupKeys array (saveGroupKeys). The 'Requester'
  1.1567 +  device keys are marked as default for those respective identities
  1.1568 +  (receivedKeysAreDefaultKeys). A UI event (showGroupCreated) indicates
  1.1569 +  that the Device Group process is complete, and the FSM transitions
  1.1570 +  to state Grouped.
  1.1571 +
  1.1572 +* Cancel: A Rollback message is issued to the 'Requester' device, and
  1.1573 +  the FSM transitions to state Sole. No private key data is exchanged.
  1.1574  
  1.1575  
  1.1576  ####  FormingGroupRequester
  1.1577  
  1.1578 -This state is entered by the 'Requester' device only. The FSM sends a
  1.1579 -OwnKeysRequester along with its own keys, and waits to receive the
  1.1580 -keys from the 'Offerer' device.  Once received, the 'Offerer' keys are
  1.1581 -saved. The own keys are marked as Default Keys. The Device Group is
  1.1582 -created and the FSM transitions to state Grouped.
  1.1583 -
  1.1584 -<!-- TODO: Explain Default Keys in Terms Section -->
  1.1585 -
  1.1586 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.1587 -
  1.1588 -{::include ../shared/fence-line.mkd}
  1.1589 -
  1.1590 -       state FormingGroupRequester {
  1.1591 -            on Init {
  1.1592 -                do prepareOwnKeys;
  1.1593 -                send OwnKeysRequester; // we're not grouped yet,
  1.1594 -                                       // this is our own keys
  1.1595 -            }
  1.1596 -
  1.1597 -            on OwnKeysOfferer {
  1.1598 -                do saveGroupKeys;
  1.1599 -                do ownKeysAreDefaultKeys;
  1.1600 -                do showGroupCreated;
  1.1601 -                go Grouped;
  1.1602 -            }
  1.1603 -        }
  1.1604 -
  1.1605 -{::include ../shared/fence-line.mkd}
  1.1606 -
  1.1607 -
  1.1608 +This state can only be entered by the 'Requester' device in a Sole state.
  1.1609 +
  1.1610 +In this state, the user is given two options: Initialize the final
  1.1611 +step of the KeySync process (exchange of private key information),
  1.1612 +or Cancel.
  1.1613 +
  1.1614 +* Init: The FSM triggers a UI event to indicate that Device Group
  1.1615 +  formation is in progress, and awaits an OwnKeysOfferer response
  1.1616 +  from the 'Offerer' device.
  1.1617 +
  1.1618 +* Cancel: A Rollback message is issued to the 'Requester' device, and
  1.1619 +  the FSM transitions to state Sole. No private key data is exchanged.
  1.1620 +
  1.1621 +Once an OwnKeysOfferer message is received, the 'Requester' FSM saves
  1.1622 +the 'Offerer' keys in a shared GroupKeys array (saveGroupKeys), and
  1.1623 +prepares the device's Own Keys for synchronization. The 'Requester'
  1.1624 +device keys are marked as default for those respective identities
  1.1625 +(ownKeysAreDefaultKeys). The FSM then issues an OwnKeysRequester message
  1.1626 +which contains these keys. A UI event (showGroupCreated) indicates
  1.1627 +that the Device Group process is complete, and the FSM transitions
  1.1628 +to state Grouped.
  1.1629 +
  1.1630 +<!-- TODO: Everything from here onward is still WIP. -->
  1.1631  ####  Grouped
  1.1632  
  1.1633 -
  1.1634 -This is the default state for any grouped device. The device also
  1.1635 -waits for Beacons from other devices that are not yet part of the
  1.1636 +This is the default state for any grouped device. This device state also
  1.1637 +listens for Beacons from other devices that are not yet part of the
  1.1638  Device Group.
  1.1639  
  1.1640  Upon receipt of a Beacon message from Sole Device, the device sends a
  1.1641  NegotiationRequest message and waits for the NegotiationOpen message.
  1.1642  
  1.1643 -On receipt of the NegotiationOpen message from the Sole Device the FSM
  1.1644 +On receipt of the NegotiationOpen message from the Sole Device, the FSM
  1.1645  of the 'Requester' transitions to state HandshakingGrouped.
  1.1646  
  1.1647  In this state, various other events are also processed, which do not
  1.1648  result in a transition to another state.
  1.1649  
  1.1650 -<!-- TODO [KRB]
  1.1651 -   Consider also noting where the reader can learn more about these
  1.1652 -   non-transitional states, or add an example (e.g., non-transitional
  1.1653 -   thing 1, non-transitional thing 2)
  1.1654 --->
  1.1655 -
  1.1656 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.1657 -
  1.1658 -{::include ../shared/fence-line.mkd}
  1.1659 -
  1.1660 -        state Grouped timeout=off {
  1.1661 -            on Init {
  1.1662 -                do newChallengeAndNegotiationBase;
  1.1663 -                do showBeingInGroup;
  1.1664 -            }
  1.1665 -
  1.1666 -            on GroupKeys
  1.1667 -                do saveGroupKeys;
  1.1668 -
  1.1669 -            on KeyGen {
  1.1670 -                do prepareOwnKeys;
  1.1671 -                send GroupKeys;
  1.1672 -            }
  1.1673 -
  1.1674 -            on Beacon {
  1.1675 -                do openNegotiation;
  1.1676 -                do tellWeAreGrouped;
  1.1677 -                send NegotiationRequest;
  1.1678 -                do useOwnChallenge;
  1.1679 -            }
  1.1680 -
  1.1681 -            on NegotiationOpen if sameNegotiationAndPartner {
  1.1682 -                do storeNegotiation;
  1.1683 -                go HandshakingGrouped;
  1.1684 -            }
  1.1685 -
  1.1686 -            on GroupTrustThisKey
  1.1687 -                do trustThisKey;
  1.1688 -        }
  1.1689 -
  1.1690 -{::include ../shared/fence-line.mkd}
  1.1691 +<!-- mention the non-transitional actions and cf those sections -->
  1.1692  
  1.1693  
  1.1694  ####  HandshakingToJoin
  1.1695 @@ -1455,155 +1037,66 @@
  1.1696  yet part of a Device Group.
  1.1697  
  1.1698  In this state the FSM waits for the user to compare the Trustwords and
  1.1699 -to press either of the following buttons (on the new device):
  1.1700 +to choose from the following options on the new device:
  1.1701  
  1.1702  * Accept: A CommitAccept message is sent and the FSM transitions to
  1.1703 -  state HandshakingToJoinPhase1
  1.1704 -  
  1.1705 +  state HandshakingToJoinPhase1.
  1.1706 +
  1.1707  * Reject: A CommitReject message is sent, pEp KeySync is disabled (on
  1.1708 -  the new device), and the FSM transitions to state End
  1.1709 -  
  1.1710 -* Cancel: A Rollback message is sent and the FSM transitions to state Sole
  1.1711 -
  1.1712 -If the 'Accept' button was pressed on a grouped device, a
  1.1713 +  the new device), and the FSM transitions to state End.
  1.1714 +
  1.1715 +* Cancel: A Rollback message is sent and the FSM transitions to state Sole.
  1.1716 +
  1.1717 +If the 'Accept' option is chosen on a grouped device, a
  1.1718  CommitAcceptForGroup message is received and the FSM transitions to state
  1.1719  HandshakingToJoinPhase2.
  1.1720  
  1.1721 -If the 'Reject' button was pressed on a grouped device, a CommitReject
  1.1722 +If the 'Reject' option is chosen on a grouped device, a CommitReject
  1.1723  message is received. pEp KeySync is disabled (on the new device) and
  1.1724  the FSM transitions to state End.
  1.1725  
  1.1726 -If the 'Cancel' button was pressed on the 'Requester' device, a
  1.1727 +If the 'Cancel' option is chosen on the 'Requester' device, a
  1.1728  Rollback message is received and the FSM transitions to state Sole.
  1.1729  
  1.1730  
  1.1731 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.1732 -
  1.1733 -{::include ../shared/fence-line.mkd}
  1.1734 -
  1.1735 -       // sole device handshaking with group
  1.1736 -        state HandshakingToJoin {
  1.1737 -            on Init
  1.1738 -                do showJoinGroupHandshake;
  1.1739 -
  1.1740 -            // Cancel is Rollback
  1.1741 -            on Cancel {
  1.1742 -                send Rollback;
  1.1743 -                go Sole;
  1.1744 -            }
  1.1745 -
  1.1746 -            on Rollback if sameNegotiationAndPartner
  1.1747 -                go Sole;
  1.1748 -
  1.1749 -            // Reject is CommitReject
  1.1750 -            on Reject {
  1.1751 -                send CommitReject;
  1.1752 -                do disable;
  1.1753 -                go End;
  1.1754 -            }
  1.1755 -
  1.1756 -            on CommitAcceptForGroup if sameNegotiationAndPartner
  1.1757 -                go HandshakingToJoinPhase2;
  1.1758 -
  1.1759 -            on CommitReject if sameNegotiationAndPartner {
  1.1760 -                do disable;
  1.1761 -                go End;
  1.1762 -            }
  1.1763 -
  1.1764 -            // Accept is Phase1Commit
  1.1765 -            on Accept {
  1.1766 -                do trustThisKey;
  1.1767 -                send CommitAccept;
  1.1768 -                go HandshakingToJoinPhase1;
  1.1769 -            }
  1.1770 -        }
  1.1771 -
  1.1772 -{::include ../shared/fence-line.mkd}
  1.1773 -
  1.1774 -
  1.1775  ####  HandshakingToJoinPhase1
  1.1776  
  1.1777  
  1.1778  This state is entered by a new device only, i.e. a device that is not
  1.1779  yet part of a Device Group. The FSM waits for the user to finish the
  1.1780 -handshake on a grouped device (i.e. compare the Trustwords and press
  1.1781 -either of the buttons on a grouped device):
  1.1782 -
  1.1783 -If the 'Accept' button was pressed on a grouped device, a
  1.1784 +handshake on a grouped device (the user compares the Trustwords and
  1.1785 +chooses from the options presented):
  1.1786 +
  1.1787 +If the 'Accept' option is chosen on a grouped device, a
  1.1788  CommitAcceptForGroup message is received and the FSM transitions to state
  1.1789  JoiningGroup.
  1.1790  
  1.1791 -If the 'Reject' button was pressed on a grouped device, a CommitReject
  1.1792 +If the 'Reject' option is chosen on a grouped device, a CommitReject
  1.1793  message is received. pEp KeySync is disabled (on the new device) and
  1.1794  the FSM transitions to state End.
  1.1795  
  1.1796 -If the 'Cancel' button was pressed on the 'Requester' device, a
  1.1797 +If the 'Cancel' option is chosen on the 'Requester' device, a
  1.1798  Rollback message is received and the FSM transitions to state Sole.
  1.1799  
  1.1800  
  1.1801 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.1802 -
  1.1803 -{::include ../shared/fence-line.mkd}
  1.1804 -
  1.1805 -        state HandshakingToJoinPhase1 {
  1.1806 -            on Rollback if sameNegotiationAndPartner
  1.1807 -                go Sole;
  1.1808 -            
  1.1809 -            on CommitReject if sameNegotiationAndPartner {
  1.1810 -                do disable;
  1.1811 -                go End;
  1.1812 -            }
  1.1813 -
  1.1814 -            on CommitAcceptForGroup if sameNegotiationAndPartner
  1.1815 -                go JoiningGroup;
  1.1816 -        }
  1.1817 -
  1.1818 -{::include ../shared/fence-line.mkd}
  1.1819 -
  1.1820 -
  1.1821  ####  HandshakingToJoinPhase2
  1.1822  
  1.1823  
  1.1824  This state is entered by a new device only, i.e. a device that is not
  1.1825  yet part of a Device Group.
  1.1826  
  1.1827 -In this state the FSM waits for the user to compare the Trustwords and
  1.1828 -to press either of the following buttons (on the new device):
  1.1829 +In this state, the FSM waits for the user to compare the Trustwords and
  1.1830 +to choose from the following options on the new device:
  1.1831  
  1.1832  * Accept: A CommitAccept message is sent and the FSM transitions to
  1.1833    state JoiningGroup.
  1.1834 -  
  1.1835 +
  1.1836  * Reject: A CommitReject message is sent, pEp KeySync is disabled (on
  1.1837    the new device), and the FSM transitions to state End.
  1.1838 -  
  1.1839 +
  1.1840  * Cancel: A Rollback message is sent and the FSM transitions to state Sole.
  1.1841  
  1.1842  
  1.1843 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.1844 -
  1.1845 -{::include ../shared/fence-line.mkd}
  1.1846 -
  1.1847 -       state HandshakingToJoinPhase2 {
  1.1848 -            on Cancel {
  1.1849 -                send Rollback;
  1.1850 -                go Sole;
  1.1851 -            }
  1.1852 -
  1.1853 -            on Reject {
  1.1854 -                send CommitReject;
  1.1855 -                do disable;
  1.1856 -                go End;
  1.1857 -            }
  1.1858 -
  1.1859 -            on Accept {
  1.1860 -                do trustThisKey;
  1.1861 -                go JoiningGroup;
  1.1862 -            }
  1.1863 -        }
  1.1864 -
  1.1865 -{::include ../shared/fence-line.mkd}
  1.1866 -
  1.1867 -
  1.1868  ####  JoiningGroup
  1.1869  
  1.1870  This state is entered by a new device only, i.e. a device that is not
  1.1871 @@ -1613,23 +1106,6 @@
  1.1872  received, these are saved and marked as default keys. Then it sends
  1.1873  all keys to the grouped devices and the FSM transitions to state Grouped.
  1.1874  
  1.1875 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.1876 -
  1.1877 -{::include ../shared/fence-line.mkd}
  1.1878 -
  1.1879 -       state JoiningGroup {
  1.1880 -            on GroupKeys {
  1.1881 -                do saveGroupKeys;
  1.1882 -                do receivedKeysAreDefaultKeys;
  1.1883 -                do prepareOwnKeys;
  1.1884 -                send GroupKeys;
  1.1885 -                do showDeviceAdded;
  1.1886 -                go Grouped;
  1.1887 -            }
  1.1888 -        }
  1.1889 -
  1.1890 -{::include ../shared/fence-line.mkd}
  1.1891 -
  1.1892  
  1.1893  ####  HandshakingGrouped
  1.1894  
  1.1895 @@ -1637,143 +1113,66 @@
  1.1896  part of a Device Group.
  1.1897  
  1.1898  In this state the FSM waits for the user to compare the Trustwords and
  1.1899 -to press either of the following buttons (on any grouped device, which
  1.1900 -now becomes the 'Active' grouped device):
  1.1901 +to choose any of the following options from any grouped device, which
  1.1902 +will now become the Active Grouped Device:
  1.1903 +
  1.1904 +* Accept: A CommitAcceptForGroup message is sent and the FSM transitions to
  1.1905 +  state HandshakingGroupedPhase1.
  1.1906 +
  1.1907 +* Reject: A CommitReject message is sent and the FSM transitions to state
  1.1908 +  Grouped.
  1.1909 +
  1.1910 +* Cancel: A Rollback message is sent and the FSM transitions to state Grouped.
  1.1911 +
  1.1912 +If the 'Accept' option is chosen on the new device, a
  1.1913 +CommitAccept message is received and the FSM transitions to state
  1.1914 +HandshakingPhase2.
  1.1915 +
  1.1916 +If the 'Reject' option is chosen on the new device, a CommitReject
  1.1917 +message is received and the FSM transitions to state Grouped.
  1.1918 +
  1.1919 +If the 'Cancel' option is chosen on the new device, a Rollback
  1.1920 +message is received and the FSM transitions to state Grouped.
  1.1921 +
  1.1922 +Note: In this state, other events are processed, but these events do not
  1.1923 +result in a transition to another state and are not discussed here.
  1.1924 +
  1.1925 +
  1.1926 +####  HandshakingGroupedPhase1
  1.1927 +
  1.1928 +This state is entered by grouped devices only, i.e., devices that are
  1.1929 +already part of a Device Group. The FSM waits for the user to finish the
  1.1930 +handshake on the new device (the user compares the Trustwords and
  1.1931 +chooses from the options presented):
  1.1932 +
  1.1933 +If the 'Accept' option is chosen on the new device, a
  1.1934 +CommitAccept message is received and the FSM transitions to state
  1.1935 +Grouped.
  1.1936 +
  1.1937 +If the 'Reject' option is chosen on the new device, a CommitReject
  1.1938 +message is received and the FSM transitions to state Grouped.
  1.1939 +
  1.1940 +If the 'Cancel' option is chosen on the new device, a Rollback
  1.1941 +message is received and the FSM transitions to state Grouped.
  1.1942 +
  1.1943 +In this state also a various other events are processed, which do not
  1.1944 +result in a transition to another state.
  1.1945 +
  1.1946 +
  1.1947 +####  HandshakingGroupedPhase2
  1.1948 +
  1.1949 +This state is entered by grouped devices only, i.e. devices that are
  1.1950 +already part of a Device Group.
  1.1951 +
  1.1952 +In this state the FSM waits for the user to compare the Trustwords and
  1.1953 +to choose from the following options from any grouped device, which
  1.1954 +will now become the Active Grouped Device:
  1.1955  
  1.1956  * Accept: A CommitAcceptForGroup message is sent and the FSM transitions to
  1.1957    state HandshakingGroupedPhase1
  1.1958 -  
  1.1959 +
  1.1960  * Reject: A CommitReject message is sent and the FSM transitions to state
  1.1961 -  Grouped 
  1.1962 -
  1.1963 -* Cancel: A Rollback message is sent and the FSM transitions to state Grouped
  1.1964 -
  1.1965 -If the 'Accept' button was pressed on the new device, a
  1.1966 -CommitAccept message is received and the FSM transitions to state
  1.1967 -HandshakingPhase2.
  1.1968 -
  1.1969 -If the 'Reject' button was pressed on the new device, a CommitReject
  1.1970 -message is received and the FSM transitions to state Grouped.
  1.1971 -
  1.1972 -If the 'Cancel' button was pressed on the new device, a Rollback
  1.1973 -message is received and the FSM transitions to state Grouped.
  1.1974 -
  1.1975 -In this state also a various other events are processed, which do not
  1.1976 -result in a transition to another state.
  1.1977 -
  1.1978 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.1979 -
  1.1980 -{::include ../shared/fence-line.mkd}
  1.1981 -
  1.1982 -       state HandshakingGrouped {
  1.1983 -            on Init
  1.1984 -                do showGroupedHandshake;
  1.1985 -    
  1.1986 -            // Cancel is Rollback
  1.1987 -            on Cancel {
  1.1988 -                send Rollback;
  1.1989 -                go Grouped;
  1.1990 -            }
  1.1991 -
  1.1992 -            on Rollback if sameNegotiationAndPartner
  1.1993 -                go Grouped;
  1.1994 -
  1.1995 -            // Reject is CommitReject
  1.1996 -            on Reject {
  1.1997 -                send CommitReject;
  1.1998 -                go Grouped;
  1.1999 -            }
  1.2000 -
  1.2001 -            on CommitReject if sameNegotiationAndPartner
  1.2002 -                go Grouped;
  1.2003 -
  1.2004 -            // Accept is Phase1Commit
  1.2005 -            on Accept {
  1.2006 -                do trustThisKey;
  1.2007 -                send GroupTrustThisKey;
  1.2008 -                send CommitAcceptForGroup;
  1.2009 -                go HandshakingGroupedPhase1;
  1.2010 -            }
  1.2011 -
  1.2012 -            on CommitAccept if sameNegotiationAndPartner
  1.2013 -                go HandshakingGroupedPhase2;
  1.2014 -
  1.2015 -            on GroupTrustThisKey {
  1.2016 -                do hideHandshakeDialog;
  1.2017 -                do trustThisKey;
  1.2018 -            }
  1.2019 -
  1.2020 -            on GroupKeys
  1.2021 -                do saveGroupKeys;
  1.2022 -        }
  1.2023 -
  1.2024 -{::include ../shared/fence-line.mkd}
  1.2025 -
  1.2026 -
  1.2027 -####  HandshakingGroupedPhase1
  1.2028 -
  1.2029 -
  1.2030 -This state is entered by grouped devices only, i.e., devices that are
  1.2031 -part of a Device Group. The FSM waits for the user to finish the
  1.2032 -handshake on the new device (i.e., compare the Trustwords and press
  1.2033 -either of the buttons on the new device):
  1.2034 -
  1.2035 -If the 'Accept' button was pressed on the new device, a
  1.2036 -CommitAccept message is received and the FSM transitions to state
  1.2037 -Grouped.
  1.2038 -
  1.2039 -If the 'Reject' button was pressed on the new device, a CommitReject
  1.2040 -message is received and the FSM transitions to state Grouped.
  1.2041 -
  1.2042 -If the 'Cancel' button was pressed on the new device, a Rollback
  1.2043 -message is received and the FSM transitions to state Grouped.
  1.2044 -
  1.2045 -In this state also a various other events are processed, which do not
  1.2046 -result in a transition to another state.
  1.2047 -
  1.2048 -
  1.2049 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.2050 -
  1.2051 -{::include ../shared/fence-line.mkd}
  1.2052 -
  1.2053 -        state HandshakingGroupedPhase1 {
  1.2054 -            on Rollback if sameNegotiationAndPartner
  1.2055 -                go Grouped;
  1.2056 -
  1.2057 -            on CommitReject if sameNegotiationAndPartner
  1.2058 -                go Grouped;
  1.2059 -
  1.2060 -            on CommitAccept if sameNegotiationAndPartner {
  1.2061 -                do prepareOwnKeys;
  1.2062 -                send GroupKeys;
  1.2063 -                go Grouped;
  1.2064 -            }
  1.2065 -
  1.2066 -            on GroupTrustThisKey {
  1.2067 -                do trustThisKey;
  1.2068 -            }
  1.2069 -
  1.2070 -            on GroupKeys
  1.2071 -                do saveGroupKeys;
  1.2072 -        }
  1.2073 -
  1.2074 -{::include ../shared/fence-line.mkd}
  1.2075 -
  1.2076 -
  1.2077 -####  HandshakingGroupedPhase2
  1.2078 -
  1.2079 -This state is entered by grouped devices only, i.e. devices that are
  1.2080 -part of a Device Group.
  1.2081 -
  1.2082 -In this state the FSM waits for the user to compare the Trustwords and
  1.2083 -to press either of the following buttons (on any grouped device, which
  1.2084 -now becomes the 'Active' grouped device):
  1.2085 -
  1.2086 -* Accept: A CommitAcceptForGroup message is sent and the FSM transitions to
  1.2087 -  state HandshakingGroupedPhase1
  1.2088 -  
  1.2089 -* Reject: A CommitReject message is sent and the FSM transitions to state
  1.2090 -  Grouped 
  1.2091 +  Grouped
  1.2092  
  1.2093  * Cancel: A Rollback message is sent and the FSM transitions to state Grouped
  1.2094  
  1.2095 @@ -1782,281 +1181,46 @@
  1.2096  certain actions (e.g., saveGroupKeys).
  1.2097  
  1.2098  
  1.2099 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.2100 -
  1.2101 -{::include ../shared/fence-line.mkd}
  1.2102 -
  1.2103 -        state HandshakingGroupedPhase2 {
  1.2104 -            on Cancel {
  1.2105 -                send Rollback;
  1.2106 -                go Grouped;
  1.2107 -            }
  1.2108 -
  1.2109 -            on Reject {
  1.2110 -                send CommitReject;
  1.2111 -                go Grouped;
  1.2112 -            }
  1.2113 -
  1.2114 -            on Accept {
  1.2115 -                do trustThisKey;
  1.2116 -                send GroupTrustThisKey;
  1.2117 -                do prepareOwnKeys;
  1.2118 -                send GroupKeys;
  1.2119 -                go Grouped;
  1.2120 -            }
  1.2121 -
  1.2122 -            on GroupTrustThisKey {
  1.2123 -                do trustThisKey;
  1.2124 -            }
  1.2125 -
  1.2126 -            on GroupKeys
  1.2127 -                do saveGroupKeys;
  1.2128 -        }
  1.2129 -
  1.2130 -{::include ../shared/fence-line.mkd}
  1.2131 -
  1.2132 -
  1.2133 -<!-- TODO: clean up " vs ' --> 
  1.2134 -
  1.2135  <!-- ============================================================== -->
  1.2136  
  1.2137  
  1.2138  ### Actions
  1.2139  
  1.2140 -<!-- TODO
  1.2141 -**[KRB] These code snips are a bit confusing, as the first
  1.2142 -  portion contains calls associated with 'Cancel', which I'm
  1.2143 -  understanding is NOT the same as 'Reject'. May want to prune
  1.2144 -  how much code is used here to focus specifically on the
  1.2145 -  'Reject' functions.
  1.2146 --->
  1.2147 -
  1.2148 -Actions describe internal FSM functions, and fall into two general
  1.2149 -types. The first action type is a conditional 'if' statement, which
  1.2150 -direct the transitional states within the FSM (cf. 'if' statements;
  1.2151 -e.g., 'if deviceGrouped'). The second action type directs state
  1.2152 -changes which KeySync implementers can use to drive UI functionality,
  1.2153 -such as 'do' statements that trigger dialog box changes (cf 'do'
  1.2154 -statements; e.g., 'do hideHandshakeDialog').
  1.2155 -
  1.2156 -<!-- TODO: HM to verify the above paragraphe suggested by KRB -->
  1.2157 -
  1.2158  #### deviceGrouped (conditional)
  1.2159  
  1.2160  The 'deviceGrouped' conditional evaluates true if a device is already
  1.2161 -in a Device Group.  This boolean value is available and eventually
  1.2162 +in a Device Group. This boolean value is available and eventually
  1.2163  altered locally on every KeySync-enabled device. For example, in the
  1.2164  reference implementation, this boolean value is stored in a local SQL
  1.2165  database.
  1.2166  
  1.2167 -<!-- TODO: HM to verify the above paragraphe suggested by KRB -->
  1.2168 -
  1.2169  The 'deviceGrouped' value is what the KeySync FSM uses upon
  1.2170  initialization to determine whether a device should transition to
  1.2171  state Sole or state Grouped.
  1.2172  
  1.2173 -<!-- TODO: HM to verify the above paragraphe suggested by KRB -->
  1.2174 -
  1.2175 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2176 -
  1.2177 -{::include ../shared/fence-line.mkd}
  1.2178 -
  1.2179 -        state InitState {
  1.2180 -            on Init {
  1.2181 -                if deviceGrouped
  1.2182 -                    go Grouped;
  1.2183 -                go Sole;
  1.2184 -            }
  1.2185 -        }
  1.2186 -
  1.2187 -{::include ../shared/fence-line.mkd}
  1.2188  
  1.2189  #### disable
  1.2190  
  1.2191 -The 'disable' function may be called in an number of scenarios. For
  1.2192 +The 'disable' action may be called in an number of scenarios. For
  1.2193  example, a user has rejected a pEp Handshake on either device involved
  1.2194  in a pEp Handshake. At this time, in all cases, invoking the 'disable'
  1.2195  function results in the FSM transitioning to state End, which disables
  1.2196 -the KeySync feature.
  1.2197 -
  1.2198 -<!-- TODO: HM to verify the above paragraphe suggested by KRB -->
  1.2199 -
  1.2200 -
  1.2201 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2202 -
  1.2203 -{::include ../shared/fence-line.mkd}
  1.2204 -
  1.2205 -        // handshaking without existing Device group
  1.2206 -        state HandshakingOfferer timeout=600 {
  1.2207 -            on Init
  1.2208 -                do showSoleHandshake;
  1.2209 -
  1.2210 -            // Cancel is Rollback
  1.2211 -            on Cancel {
  1.2212 -                send Rollback;
  1.2213 -                go Sole;
  1.2214 -            }
  1.2215 -
  1.2216 -            on Rollback if sameNegotiationAndPartner
  1.2217 -                go Sole;
  1.2218 -
  1.2219 -            // Reject is CommitReject
  1.2220 -            on Reject {
  1.2221 -                send CommitReject;
  1.2222 -                do disable;
  1.2223 -                go End;
  1.2224 -            }
  1.2225 -
  1.2226 -            on CommitReject if sameNegotiationAndPartner {
  1.2227 -                do disable;
  1.2228 -                go End;
  1.2229 -            }
  1.2230 -
  1.2231 -        [...] 
  1.2232 -
  1.2233 -        // handshaking without existing Device group
  1.2234 -        state HandshakingRequester timeout=600 {
  1.2235 -            on Init
  1.2236 -                do showSoleHandshake;
  1.2237 -
  1.2238 -            // Cancel is Rollback
  1.2239 -            on Cancel {
  1.2240 -                send Rollback;
  1.2241 -                go Sole;
  1.2242 -            }
  1.2243 -
  1.2244 -            on Rollback if sameNegotiationAndPartner
  1.2245 -                go Sole;
  1.2246 -
  1.2247 -            // Reject is CommitReject
  1.2248 -            on Reject {
  1.2249 -                send CommitReject;
  1.2250 -                do disable;
  1.2251 -                go End;
  1.2252 -            }
  1.2253 -
  1.2254 -            on CommitReject if sameNegotiationAndPartner {
  1.2255 -                do disable;
  1.2256 -                go End;
  1.2257 -            }
  1.2258 -
  1.2259 -        [...]
  1.2260 -
  1.2261 -        state HandshakingPhase1Offerer {
  1.2262 -            on Rollback if sameNegotiationAndPartner {
  1.2263 -                do untrustThisKey;
  1.2264 -                go Sole;
  1.2265 -            }
  1.2266 -
  1.2267 -            on CommitReject if sameNegotiationAndPartner {
  1.2268 -                do untrustThisKey;
  1.2269 -                do disable;
  1.2270 -                go End;
  1.2271 -            }
  1.2272 -
  1.2273 -        [...]
  1.2274 -
  1.2275 -        state HandshakingPhase1Requester {
  1.2276 -            on Rollback if sameNegotiationAndPartner {
  1.2277 -                do untrustThisKey;
  1.2278 -                go Sole;
  1.2279 -            }
  1.2280 -
  1.2281 -            on CommitReject if sameNegotiationAndPartner {
  1.2282 -                do untrustThisKey;
  1.2283 -                do disable;
  1.2284 -                go End;
  1.2285 -            }
  1.2286 -
  1.2287 -        [...]
  1.2288 -
  1.2289 -        state HandshakingToJoinPhase1 {
  1.2290 -            on Rollback if sameNegotiationAndPartner
  1.2291 -                go Sole;
  1.2292 -
  1.2293 -            on CommitReject if sameNegotiationAndPartner {
  1.2294 -                do disable;
  1.2295 -                go End;
  1.2296 -            }
  1.2297 -
  1.2298 -            on CommitAcceptForGroup if sameNegotiationAndPartner
  1.2299 -                go JoiningGroup;
  1.2300 -        }
  1.2301 -
  1.2302 -        [...]
  1.2303 -
  1.2304 -        [[ TODO: More occurrences exist; perhaps it's better
  1.2305 -                 to move to appendix? ]]
  1.2306 -
  1.2307 -
  1.2308 -{::include ../shared/fence-line.mkd}
  1.2309 +the KeySync feature. pEp KeySync can be manually reenabled in the pEp
  1.2310 +settings on an affected device.
  1.2311 +
  1.2312  
  1.2313  #### hideHandshakeDialog
  1.2314  
  1.2315 -The 'hideHandshakeDialog' function is invoked when a GroupTrustThisKey
  1.2316 -message is received by a device which is in the Grouped state and
  1.2317 -negotiating the addition of a new device, but another device within
  1.2318 -the Device Group has already confirmed the Trustwords dialog to accept
  1.2319 -the new device.
  1.2320 -   
  1.2321 -This action is intended to send an event to the 'Passive' grouped
  1.2322 -devices that forces the closure of any unnecessary dialog boxes.
  1.2323 -
  1.2324 -
  1.2325 -<!-- TODO
  1.2326 -[KRB] I'm not 100% sure what this means. Does this mean we intend
  1.2327 -   to have things happen so quickly that the extra Trustwords dialog
  1.2328 -   boxes never pop up for the other grouped devices if one of the
  1.2329 -   grouped devices hits "Accept" first?
  1.2330 --->
  1.2331 -
  1.2332 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2333 -
  1.2334 -{::include ../shared/fence-line.mkd}
  1.2335 -
  1.2336 -       state HandshakingGrouped {
  1.2337 -            on Init
  1.2338 -                do showGroupedHandshake;
  1.2339 -    
  1.2340 -            // Cancel is Rollback
  1.2341 -            on Cancel {
  1.2342 -                send Rollback;
  1.2343 -                go Grouped;
  1.2344 -            }
  1.2345 -
  1.2346 -            on Rollback if sameNegotiationAndPartner
  1.2347 -                go Grouped;
  1.2348 -
  1.2349 -            // Reject is CommitReject
  1.2350 -            on Reject {
  1.2351 -                send CommitReject;
  1.2352 -                go Grouped;
  1.2353 -            }
  1.2354 -
  1.2355 -            on CommitReject if sameNegotiationAndPartner
  1.2356 -                go Grouped;
  1.2357 -
  1.2358 -            // Accept is Phase1Commit
  1.2359 -            on Accept {
  1.2360 -                do trustThisKey;
  1.2361 -                send GroupTrustThisKey;
  1.2362 -                send CommitAcceptForGroup;
  1.2363 -                go HandshakingGroupedPhase1;
  1.2364 -            }
  1.2365 -
  1.2366 -            on CommitAccept if sameNegotiationAndPartner
  1.2367 -                go HandshakingGroupedPhase2;
  1.2368 -
  1.2369 -            on GroupTrustThisKey {
  1.2370 -                do hideHandshakeDialog;
  1.2371 -                do trustThisKey;
  1.2372 -            }
  1.2373 -
  1.2374 -            on GroupKeys
  1.2375 -                do saveGroupKeys;
  1.2376 -        }
  1.2377 -
  1.2378 -{::include ../shared/fence-line.mkd}
  1.2379 +During the negotiation process for adding a new device to an existing
  1.2380 +Device Group, any device in that group can be used to complete the
  1.2381 +handshaking process and, as a result, each device in a Device Group will
  1.2382 +display the handshake dialog options. Once this process is performed
  1.2383 +on one of the Grouped Devices, that device becomes the Active Grouped
  1.2384 +Device, and a GroupTrustThisKey message is sent to the other (now Passive)
  1.2385 +Grouped Devices. Upon receipt of the GroupTrustThisKey message, the
  1.2386 +'hideHandshakeDialog' action is invoked, and is intended to force the
  1.2387 +closure of the extra handshake dialog boxes.
  1.2388 +
  1.2389  
  1.2390  #### openNegotiation
  1.2391  
  1.2392 @@ -2071,212 +1235,40 @@
  1.2393  simultaneously.
  1.2394  
  1.2395  
  1.2396 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2397 -
  1.2398 -{::include ../shared/fence-line.mkd}
  1.2399 -
  1.2400 -        state Sole timeout=off {
  1.2401 -            on Init {
  1.2402 -                do newChallengeAndNegotiationBase;
  1.2403 -                do showBeingSole;
  1.2404 -                send Beacon;
  1.2405 -            }
  1.2406 -
  1.2407 -            on KeyGen {
  1.2408 -                send Beacon;
  1.2409 -            }
  1.2410 -
  1.2411 -            on CannotDecrypt { // cry baby
  1.2412 -                send Beacon;
  1.2413 -            }
  1.2414 -
  1.2415 -            on Beacon {
  1.2416 -                if sameChallenge {
  1.2417 -                    // this is our own Beacon; ignore
  1.2418 -                }
  1.2419 -                else {
  1.2420 -                    if weAreOfferer {
  1.2421 -                        do useOwnChallenge;
  1.2422 -                        send Beacon;
  1.2423 -                    }
  1.2424 -                    else /* we are requester */ {
  1.2425 -                        do openNegotiation;
  1.2426 -                        do tellWeAreNotGrouped;
  1.2427 -                        // requester is sending NegotiationRequest
  1.2428 -                        send NegotiationRequest;
  1.2429 -                        do useOwnChallenge;
  1.2430 -                    }
  1.2431 -                }
  1.2432 -
  1.2433 -        [...]
  1.2434 -
  1.2435 -        state Grouped timeout=off {
  1.2436 -            on Init {
  1.2437 -                do newChallengeAndNegotiationBase;
  1.2438 -                do showBeingInGroup;
  1.2439 -            }
  1.2440 -
  1.2441 -            on GroupKeys
  1.2442 -                do saveGroupKeys;
  1.2443 -
  1.2444 -            on KeyGen {
  1.2445 -                do prepareOwnKeys;
  1.2446 -                send GroupKeys;
  1.2447 -            }
  1.2448 -
  1.2449 -            on Beacon {
  1.2450 -                do openNegotiation;
  1.2451 -                do tellWeAreGrouped;
  1.2452 -                send NegotiationRequest;
  1.2453 -                do useOwnChallenge;
  1.2454 -            }
  1.2455 -
  1.2456 -
  1.2457 -{::include ../shared/fence-line.mkd}
  1.2458 -
  1.2459  #### ownKeysAreDefaultKeys
  1.2460  
  1.2461  \[\[ TODO \]\]
  1.2462 -
  1.2463 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2464 -
  1.2465 -{::include ../shared/fence-line.mkd}
  1.2466 -
  1.2467 -        state FormingGroupOfferer {
  1.2468 -            on Init {
  1.2469 -                do prepareOwnKeys;
  1.2470 -                send OwnKeysOfferer; // we're not grouped yet,
  1.2471 -                                     // this is our own keys
  1.2472 -            }
  1.2473 -
  1.2474 -            on OwnKeysRequester {
  1.2475 -                do saveGroupKeys;
  1.2476 -                do receivedKeysAreDefaultKeys;
  1.2477 -                do showGroupCreated;
  1.2478 -                go Grouped;
  1.2479 -            }
  1.2480 -        }
  1.2481 -
  1.2482 -        state FormingGroupRequester {
  1.2483 -            on Init {
  1.2484 -                do prepareOwnKeys;
  1.2485 -                send OwnKeysRequester; // we're not grouped yet,
  1.2486 -                                       // this is our own keys
  1.2487 -            }
  1.2488 -
  1.2489 -            on OwnKeysOfferer {
  1.2490 -                do saveGroupKeys;
  1.2491 -                do ownKeysAreDefaultKeys;
  1.2492 -                do showGroupCreated;
  1.2493 -                go Grouped;
  1.2494 -            }
  1.2495 -        }
  1.2496 -
  1.2497 -{::include ../shared/fence-line.mkd}
  1.2498 +<!-- NOTE: ask VB about this.
  1.2499 +VB response:
  1.2500 +23:51 <fdik> a default key is an actually used key for an identity
  1.2501 +23:52 <fdik> an own key is a default key for an own identity
  1.2502 +23:52 <fdik> users are able to select which own identities they want to sync and which not
  1.2503 +23:53 <fdik> in the apps it's mainly accounts which are in sync and some, which may be not
  1.2504 +-->
  1.2505 +
  1.2506  
  1.2507  #### newChallengeAndNegotiationBase
  1.2508  
  1.2509  \[\[ TODO \]\]
  1.2510 -
  1.2511 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2512 -
  1.2513 -{::include ../shared/fence-line.mkd}
  1.2514 -
  1.2515 -        state Sole timeout=off {
  1.2516 -            on Init {
  1.2517 -                do newChallengeAndNegotiationBase;
  1.2518 -                do showBeingSole;
  1.2519 -                send Beacon;
  1.2520 -            }
  1.2521 -
  1.2522 -        [...]
  1.2523 -
  1.2524 -        state Grouped timeout=off {
  1.2525 -            on Init {
  1.2526 -                do newChallengeAndNegotiationBase;
  1.2527 -                do showBeingInGroup;
  1.2528 -            }
  1.2529 -
  1.2530 -{::include ../shared/fence-line.mkd}
  1.2531 +<!-- newChallengeAndNegotiationBase is resetting the transaction IDs -->
  1.2532 +
  1.2533  
  1.2534  #### partnerIsGrouped (conditional)
  1.2535  
  1.2536 +The partnerIsGrouped conditional evaluates whether a negotiation partner
  1.2537 +is already in a Device Group or not, which determines if the new device
  1.2538 +will be joining the Device Group or forming a new Device Group with
  1.2539 +another device in the Sole state. If this boolean evaluates true, then
  1.2540 +the FSM transitions to HandshakingToJoin. If not, the FSM proceeds with
  1.2541 +the negotiation process for two sole devices seeking to form a new Device Group.
  1.2542 +
  1.2543 +
  1.2544 +#### prepareOwnKeys
  1.2545 +
  1.2546  \[\[ TODO \]\]
  1.2547  
  1.2548 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2549 -
  1.2550 -{::include ../shared/fence-line.mkd}
  1.2551 -
  1.2552 -        state Sole timeout=off {
  1.2553 -            
  1.2554 -            [...]
  1.2555 -
  1.2556 -            on NegotiationRequest {
  1.2557 -                if sameChallenge { // challenge accepted
  1.2558 -                    if sameNegotiation {
  1.2559 -                        // this is our own NegotiationRequest; ignore
  1.2560 -                    }
  1.2561 -                    else {
  1.2562 -                        do storeNegotiation;
  1.2563 -                        // offerer is accepting by confirming
  1.2564 -                        // NegotiationOpen
  1.2565 -                        send NegotiationOpen;
  1.2566 -                        if partnerIsGrouped
  1.2567 -                            go HandshakingToJoin;
  1.2568 -                        else
  1.2569 -                            go HandshakingOfferer;
  1.2570 -                    }
  1.2571 -                }
  1.2572 -            }
  1.2573 -
  1.2574 -{::include ../shared/fence-line.mkd}
  1.2575 -
  1.2576 -#### prepareOwnKeys
  1.2577 -
  1.2578 -\[\[ TODO \]\]
  1.2579 -
  1.2580  <!-- TODO: This was planned for review week.. -->
  1.2581  
  1.2582 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2583 -
  1.2584 -{::include ../shared/fence-line.mkd}
  1.2585 -
  1.2586 -        state FormingGroupOfferer {
  1.2587 -            on Init {
  1.2588 -                do prepareOwnKeys;
  1.2589 -                send OwnKeysOfferer; // we're not grouped yet,
  1.2590 -                                     // this is our own keys
  1.2591 -            }
  1.2592 -
  1.2593 -            [...]
  1.2594 -
  1.2595 -        [...]
  1.2596 -
  1.2597 -        state FormingGroupRequester {
  1.2598 -            on Init {
  1.2599 -                do prepareOwnKeys;
  1.2600 -                send OwnKeysRequester; // we're not grouped yet,
  1.2601 -                                       // this is our own keys
  1.2602 -            }
  1.2603 -
  1.2604 -            [...]
  1.2605 -
  1.2606 -        [...]
  1.2607 -
  1.2608 -        state Grouped timeout=off {
  1.2609 -
  1.2610 -            [...]
  1.2611 -
  1.2612 -            on KeyGen {
  1.2613 -                do prepareOwnKeys;
  1.2614 -                send GroupKeys;
  1.2615 -            }
  1.2616 -
  1.2617 -            [...]
  1.2618 -
  1.2619 -        [...]
  1.2620 -
  1.2621 -{::include ../shared/fence-line.mkd}
  1.2622  
  1.2623  #### receivedKeysAreDefaultKeys
  1.2624  
  1.2625 @@ -2290,104 +1282,15 @@
  1.2626  
  1.2627  <!-- TODO: This was planned for review week.. -->
  1.2628  
  1.2629 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2630 -
  1.2631 -{::include ../shared/fence-line.mkd}
  1.2632 -
  1.2633 -        state FormingGroupOfferer {
  1.2634 -            on Init {
  1.2635 -                do prepareOwnKeys;
  1.2636 -                send OwnKeysOfferer; // we're not grouped yet,
  1.2637 -                                     // this is our own keys
  1.2638 -            }
  1.2639 -
  1.2640 -            on OwnKeysRequester {
  1.2641 -                do saveGroupKeys;
  1.2642 -                do receivedKeysAreDefaultKeys;
  1.2643 -                do showGroupCreated;
  1.2644 -                go Grouped;
  1.2645 -            }
  1.2646 -        }
  1.2647 -
  1.2648 -        [...]
  1.2649 -
  1.2650 -        state JoiningGroup {
  1.2651 -            on GroupKeys {
  1.2652 -                do saveGroupKeys;
  1.2653 -                do receivedKeysAreDefaultKeys;
  1.2654 -                do prepareOwnKeys;
  1.2655 -                send GroupKeys;
  1.2656 -                do showDeviceAdded;
  1.2657 -                go Grouped;
  1.2658 -            }
  1.2659 -        }
  1.2660 -
  1.2661 -        [...]
  1.2662 -
  1.2663 -{::include ../shared/fence-line.mkd}
  1.2664  
  1.2665  #### sameChallenge (conditional)
  1.2666  
  1.2667  \[\[ TODO \]\]
  1.2668  
  1.2669 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2670 -
  1.2671 -{::include ../shared/fence-line.mkd}
  1.2672 -
  1.2673 -        state Sole timeout=off {
  1.2674 -            on Init {
  1.2675 -                do newChallengeAndNegotiationBase;
  1.2676 -                do showBeingSole;
  1.2677 -                send Beacon;
  1.2678 -            }
  1.2679 -
  1.2680 -            on KeyGen {
  1.2681 -                send Beacon;
  1.2682 -            }
  1.2683 -
  1.2684 -            on CannotDecrypt { // cry baby
  1.2685 -                send Beacon;
  1.2686 -            }
  1.2687 -
  1.2688 -            on Beacon {
  1.2689 -                if sameChallenge {
  1.2690 -                    // this is our own Beacon; ignore
  1.2691 -                }
  1.2692 -                else {
  1.2693 -                    if weAreOfferer {
  1.2694 -                        do useOwnChallenge;
  1.2695 -                        send Beacon;
  1.2696 -                    }
  1.2697 -                    else /* we are requester */ {
  1.2698 -                        do openNegotiation;
  1.2699 -                        do tellWeAreNotGrouped;
  1.2700 -                        // requester is sending NegotiationRequest
  1.2701 -                        send NegotiationRequest;
  1.2702 -                        do useOwnChallenge;
  1.2703 -                    }
  1.2704 -                }
  1.2705 -
  1.2706 -            on NegotiationRequest {
  1.2707 -                if sameChallenge { // challenge accepted
  1.2708 -                    if sameNegotiation {
  1.2709 -                        // this is our own NegotiationRequest; ignore
  1.2710 -                    }
  1.2711 -                    else {
  1.2712 -                        do storeNegotiation;
  1.2713 -                        // offerer is accepting by confirming
  1.2714 -                        // NegotiationOpen
  1.2715 -                        send NegotiationOpen;
  1.2716 -                        if partnerIsGrouped
  1.2717 -                            go HandshakingToJoin;
  1.2718 -                        else
  1.2719 -                            go HandshakingOfferer;
  1.2720 -                    }
  1.2721 -                }
  1.2722 -            }
  1.2723 -
  1.2724 -        [...]
  1.2725 -
  1.2726 -{::include ../shared/fence-line.mkd}
  1.2727 +<!-- sameChallenge compares TIDs. If 'true', this is our own beacon
  1.2728 +coming back to us and we can ignore it. If 'false', then the TID
  1.2729 +comparison takes place and roles are assigned. -->
  1.2730 +
  1.2731  
  1.2732  #### sameNegotiation (conditional)
  1.2733  
  1.2734 @@ -2397,217 +1300,60 @@
  1.2735  match upon comparison, and the NegotiationRequest will be ignored as a
  1.2736  result.
  1.2737  
  1.2738 -<!-- TODO: HM to verify the above paragraphe suggested by KRB -->
  1.2739 -
  1.2740 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2741 -
  1.2742 -{::include ../shared/fence-line.mkd}
  1.2743 -
  1.2744 -        state Sole timeout=off {
  1.2745 -
  1.2746 -            [...]
  1.2747 -
  1.2748 -            on NegotiationRequest {
  1.2749 -                if sameChallenge { // challenge accepted
  1.2750 -                    if sameNegotiation {
  1.2751 -                        // this is our own NegotiationRequest; ignore
  1.2752 -                    }
  1.2753 -                    else {
  1.2754 -                        do storeNegotiation;
  1.2755 -                        // offerer is accepting by confirming
  1.2756 -                        // NegotiationOpen
  1.2757 -                        send NegotiationOpen;
  1.2758 -                        if partnerIsGrouped
  1.2759 -                            go HandshakingToJoin;
  1.2760 -                        else
  1.2761 -                            go HandshakingOfferer;
  1.2762 -                    }
  1.2763 -                }
  1.2764 -            }
  1.2765 -
  1.2766 -{::include ../shared/fence-line.mkd}
  1.2767 -
  1.2768  #### sameNegotiationAndPartner (conditional)
  1.2769  
  1.2770  \[\[ TODO \]\]
  1.2771  
  1.2772 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2773 -
  1.2774 -{::include ../shared/fence-line.mkd}
  1.2775 -
  1.2776 -{::include ../shared/fence-line.mkd}
  1.2777 +<!-- sameNegotiationAndPartner, if evaluates true, confirms that the
  1.2778 +pEp KeySync session in progress is the same throughout. It is a
  1.2779 +fidelity check to make sure we are still in the same session and
  1.2780 +communicating with the same partner. (write this more elegantly, Kel)
  1.2781 +-->
  1.2782  
  1.2783  #### saveGroupKeys
  1.2784  
  1.2785  \[\[ TODO \]\]
  1.2786 -
  1.2787 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2788 -
  1.2789 -{::include ../shared/fence-line.mkd}
  1.2790 -
  1.2791 -{::include ../shared/fence-line.mkd}
  1.2792 +<!-- saveGroupKeys directs the addition of received keys along with
  1.2793 +own keys to an array (GroupKeys). -->
  1.2794 +
  1.2795  
  1.2796  #### showBeingInGroup
  1.2797  
  1.2798 -The 'showBeingInGroup' action (in state Grouped) is used to notify a
  1.2799 -pEp implementer that a device is Grouped and to prepare the necessary
  1.2800 -structures to potentially carry out KeySync (in case any other device
  1.2801 -exists and a Beacon from a Sole Device appears at some point).
  1.2802 -
  1.2803 -
  1.2804 -<!-- TODO: HM to merge the below paragraphe suggested by KRB to the
  1.2805 -the above paragraphe:
  1.2806 -
  1.2807  The 'showBeingInGroup' action in state Grouped is used to notify a pEp
  1.2808  implementer that a device is Grouped, and to prepare the necessary
  1.2809  structures to potentially initiate KeySync, in the event any other
  1.2810 -(Grouped?) devices exist, or a Beacon from a Sole Device is received.
  1.2811 --->
  1.2812 -
  1.2813 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2814 -
  1.2815 -{::include ../shared/fence-line.mkd}
  1.2816 -
  1.2817 -        state Grouped timeout=off {
  1.2818 -            on Init {
  1.2819 -                do newChallengeAndNegotiationBase;
  1.2820 -                do showBeingInGroup;
  1.2821 -            }
  1.2822 -
  1.2823 -{::include ../shared/fence-line.mkd}
  1.2824 +Grouped devices exist, or a Beacon from a Sole Device is received.
  1.2825 +
  1.2826  
  1.2827  #### showBeingSole
  1.2828  
  1.2829 -The 'showBeingSole' action (in state Sole) is used to notify a pEp
  1.2830 -implementer that a device is ungrouped (or: sole) and to prepare the
  1.2831 -necessary structures to potentially carry out KeySync (in case any
  1.2832 -other device exists and a negotiation starts).
  1.2833 -
  1.2834 -<!-- TODO: HM to merge the below paragraphe suggested by KRB to the
  1.2835 -the above paragraphe:
  1.2836 -
  1.2837  The 'showBeingSole' action in state Sole is used to notify a pEp
  1.2838  implementer that a device is Sole (ungrouped), and to prepare the
  1.2839  necessary structures to potentially initiate KeySync, in the event a
  1.2840  Beacon from another device is received.
  1.2841 --->
  1.2842 -
  1.2843 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2844 -
  1.2845 -{::include ../shared/fence-line.mkd}
  1.2846 -
  1.2847 -        state Sole timeout=off {
  1.2848 -            on Init {
  1.2849 -                do newChallengeAndNegotiationBase;
  1.2850 -                do showBeingSole;
  1.2851 -                send Beacon;
  1.2852 -            }
  1.2853 -
  1.2854 -{::include ../shared/fence-line.mkd}
  1.2855 +
  1.2856  
  1.2857  #### showDeviceAdded
  1.2858  
  1.2859  The 'showDeviceAdded' action is used to notify a pEp implementer that
  1.2860  a Sole Device was added to an already existing Device Group.
  1.2861  
  1.2862 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2863 -
  1.2864 -{::include ../shared/fence-line.mkd}
  1.2865 -
  1.2866 -        state JoiningGroup {
  1.2867 -            on GroupKeys {
  1.2868 -                do saveGroupKeys;
  1.2869 -                do receivedKeysAreDefaultKeys;
  1.2870 -                do prepareOwnKeys;
  1.2871 -                send GroupKeys;
  1.2872 -                do showDeviceAdded;
  1.2873 -                go Grouped;
  1.2874 -            }
  1.2875 -        }
  1.2876 -
  1.2877 -{::include ../shared/fence-line.mkd}
  1.2878  
  1.2879  #### showGroupCreated
  1.2880  
  1.2881 -In both roles a Sole Device can assume (either as Requester or
  1.2882 -Offerer), this action 'showGroupCreated' ensures that the pEp
  1.2883 -implementer gets a notification that a new Device Group was formed
  1.2884 -(both devices coming from Sole state in their respective FSMs).
  1.2885 -
  1.2886 -<!-- TODO: HM to merge the below paragraphe suggested by KRB to the
  1.2887 -the above paragraphe:
  1.2888 -
  1.2889  In both roles that a Sole Device can assume ('Requester' or
  1.2890  'Offerer'), the action 'showGroupCreated' ensures that the pEp
  1.2891  implementer gets a notification that a new Device Group was formed
  1.2892 -from two Sole Devices, and allows the respective devices' FSMs to
  1.2893 -transition to the Grouped state.
  1.2894 --->
  1.2895 -
  1.2896 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2897 -
  1.2898 -{::include ../shared/fence-line.mkd}
  1.2899 -
  1.2900 -        state FormingGroupOfferer {
  1.2901 -            on Init {
  1.2902 -                do prepareOwnKeys;
  1.2903 -                send OwnKeysOfferer; // we're not grouped yet,
  1.2904 -                                     // this is our own keys
  1.2905 -            }
  1.2906 -
  1.2907 -            on OwnKeysRequester {
  1.2908 -                do saveGroupKeys;
  1.2909 -                do receivedKeysAreDefaultKeys;
  1.2910 -                do showGroupCreated;
  1.2911 -                go Grouped;
  1.2912 -            }
  1.2913 -        }
  1.2914 -
  1.2915 -               state FormingGroupRequester {
  1.2916 -            on Init {
  1.2917 -                do prepareOwnKeys;
  1.2918 -                send OwnKeysRequester; // we're not grouped yet,
  1.2919 -                                       // this is our own keys
  1.2920 -            }
  1.2921 -
  1.2922 -            on OwnKeysOfferer {
  1.2923 -                do saveGroupKeys;
  1.2924 -                do ownKeysAreDefaultKeys;
  1.2925 -                do showGroupCreated;
  1.2926 -                go Grouped;
  1.2927 -            }
  1.2928 -        }
  1.2929 -
  1.2930 -{::include ../shared/fence-line.mkd}
  1.2931 +from two Sole Devices.
  1.2932  
  1.2933  
  1.2934  #### showGroupedHandshake
  1.2935  
  1.2936  The 'showGroupedHandshake' action notifies a pEp implementer to show a
  1.2937 -pEp Handshake on the own, already Grouped Device (which is thus in
  1.2938 -state Grouped).  That means, the Handshake should be displayed in a
  1.2939 -way indicating there is another (yet) Sole Device willing to join the
  1.2940 -Device Group one is already a member of.
  1.2941 -
  1.2942 -<!-- TODO: HM to merge the below paragraphe suggested by KRB to the
  1.2943 -the above paragraphe:
  1.2944 -
  1.2945 -The 'showGroupedHandshake' action notifies a pEp implementer to show a
  1.2946 -pEp Handshake (request? dialog?) on the own, already Grouped
  1.2947 -Device. The Handshake should be displayed in a way that indicates
  1.2948 -there is another Sole Device that is requesting to join the Device
  1.2949 -Group that this device already belongs to.
  1.2950 --->
  1.2951 -
  1.2952 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2953 -
  1.2954 -{::include ../shared/fence-line.mkd}
  1.2955 -
  1.2956 -        state HandshakingGrouped {
  1.2957 -            on Init
  1.2958 -                do showGroupedHandshake;
  1.2959 -
  1.2960 -{::include ../shared/fence-line.mkd}
  1.2961 +pEp Handshake dialog on the own, already Grouped Device. The Handshake
  1.2962 +should be displayed in a way that indicates there is another Sole Device
  1.2963 +that is requesting to join the Device Group that this device already belongs to.
  1.2964 +
  1.2965  
  1.2966  #### showJoinGroupHandshake
  1.2967  
  1.2968 @@ -2623,112 +1369,29 @@
  1.2969  to show a Handshake dialog when a Sole Device is requesting to join an
  1.2970  existing Device Group, in order that a user of that Sole Device can
  1.2971  'Accept', 'Cancel', or 'Reject' on the group joining dialog.
  1.2972 +(this whole thing is a mess and needs to be rewritten)
  1.2973  -->
  1.2974  
  1.2975 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.2976 -
  1.2977 -{::include ../shared/fence-line.mkd}
  1.2978 -
  1.2979 -        // sole device handshaking with group
  1.2980 -        state HandshakingToJoin {
  1.2981 -            on Init
  1.2982 -                do showJoinGroupHandshake;
  1.2983 -
  1.2984 -{::include ../shared/fence-line.mkd}
  1.2985  
  1.2986  #### showSoleHandshake
  1.2987  
  1.2988 -For either the role of the Requester or the Offerer, in case of two
  1.2989 -Sole Devices, 'showSoleHandshake' notifies a pEp implementer that a
  1.2990 -pEp Handshake dialog between the two devices in negotiation has to be
  1.2991 -shown (depending on the role this action is called from two different
  1.2992 -states; see code below), such that the user (on both Sole Devices in
  1.2993 -user-defined sequence) can either press 'Accept', 'Cancel' or 'Reject'
  1.2994 -to decide on the group formation process.
  1.2995 -
  1.2996 -<!-- TODO: HM to merge the below paragraphe suggested by KRB to the
  1.2997 -the above paragraphe:
  1.2998 -
  1.2999  In the case of two Sole Devices (in either the 'Requester' or
  1.3000  'Offerer' role), 'showSoleHandshake' notifies a pEp implementer that a
  1.3001  pEp Handshake dialog has to be shown to the two devices in
  1.3002  negotiation. Depending on the assigned role, this action is called
  1.3003  from different states; see code excerpt below. This allows the user to
  1.3004 -press 'Accept', 'Cancel', or 'Reject' on the group formation request.
  1.3005 --->
  1.3006 -
  1.3007 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.3008 -
  1.3009 -{::include ../shared/fence-line.mkd}
  1.3010 -
  1.3011 -        // handshaking without existing Device group
  1.3012 -        state HandshakingRequester timeout=600 {
  1.3013 -            on Init
  1.3014 -                do showSoleHandshake;
  1.3015 -
  1.3016 -        [...]
  1.3017 -
  1.3018 -        // handshaking without existing Device group
  1.3019 -        state HandshakingOfferer timeout=600 {
  1.3020 -            on Init
  1.3021 -                do showSoleHandshake;
  1.3022 -
  1.3023 -{::include ../shared/fence-line.mkd}
  1.3024 +choose 'Accept', 'Cancel', or 'Reject' on the group formation request.
  1.3025 +
  1.3026  
  1.3027  #### storeNegotiation
  1.3028  
  1.3029  \[\[ TODO \]\]
  1.3030  
  1.3031 -<!-- TODO: This was planned for review week.. -->
  1.3032 -
  1.3033 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.3034 -
  1.3035 -{::include ../shared/fence-line.mkd}
  1.3036 -
  1.3037 -        state Sole timeout=off {
  1.3038 -            
  1.3039 -            [...] 
  1.3040 - 
  1.3041 -            on NegotiationRequest {
  1.3042 -                if sameChallenge { // challenge accepted
  1.3043 -                    if sameNegotiation {
  1.3044 -                        // this is our own NegotiationRequest; ignore
  1.3045 -                    }
  1.3046 -                    else {
  1.3047 -                        do storeNegotiation;
  1.3048 -                        // offerer is accepting by confirming 
  1.3049 -                        // NegotiationOpen
  1.3050 -                        send NegotiationOpen;
  1.3051 -                        if partnerIsGrouped
  1.3052 -                            go HandshakingToJoin;
  1.3053 -                        else
  1.3054 -                            go HandshakingOfferer;
  1.3055 -                    }
  1.3056 -                }
  1.3057 -            }
  1.3058 -
  1.3059 -            on NegotiationOpen if sameNegotiationAndPartner {
  1.3060 -                // requester is receiving NegotiationOpen
  1.3061 -                do storeNegotiation;
  1.3062 -                go HandshakingRequester;
  1.3063 -            }
  1.3064 -
  1.3065 -        [...]
  1.3066 -
  1.3067 -        state Grouped timeout=off {
  1.3068 -
  1.3069 -            [...]
  1.3070 -            
  1.3071 -            on NegotiationOpen if sameNegotiationAndPartner {
  1.3072 -                do storeNegotiation;
  1.3073 -                go HandshakingGrouped;
  1.3074 -            }
  1.3075 -
  1.3076 -            [...]
  1.3077 -
  1.3078 -        }
  1.3079 -
  1.3080 -{::include ../shared/fence-line.mkd}
  1.3081 +<!-- storeNegotiation saves the received non-own negotiation info so
  1.3082 +that a session fidelity check can be performed later
  1.3083 +(see sameNegotiationAndPartner). -->
  1.3084 +
  1.3085 +
  1.3086  
  1.3087  #### tellWeAreGrouped
  1.3088  
  1.3089 @@ -2747,32 +1410,6 @@
  1.3090  Device Group.
  1.3091  -->
  1.3092  
  1.3093 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.3094 -
  1.3095 -{::include ../shared/fence-line.mkd}
  1.3096 -
  1.3097 -        state Grouped timeout=off {
  1.3098 -            on Init {
  1.3099 -                do newChallengeAndNegotiationBase;
  1.3100 -                do showBeingInGroup;
  1.3101 -            }
  1.3102 -
  1.3103 -            on GroupKeys
  1.3104 -                do saveGroupKeys;
  1.3105 -
  1.3106 -            on KeyGen {
  1.3107 -                do prepareOwnKeys;
  1.3108 -                send GroupKeys;
  1.3109 -            }
  1.3110 -
  1.3111 -            on Beacon {
  1.3112 -                do openNegotiation;
  1.3113 -                do tellWeAreGrouped;
  1.3114 -                send NegotiationRequest;
  1.3115 -                do useOwnChallenge;
  1.3116 -            }
  1.3117 -
  1.3118 -{::include ../shared/fence-line.mkd}
  1.3119  
  1.3120  #### tellWeAreNotGrouped
  1.3121  
  1.3122 @@ -2792,216 +1429,19 @@
  1.3123  
  1.3124  -->
  1.3125  
  1.3126 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.3127 -
  1.3128 -{::include ../shared/fence-line.mkd}
  1.3129 -
  1.3130 -        state Sole timeout=off {
  1.3131 -            on Init {
  1.3132 -                do newChallengeAndNegotiationBase;
  1.3133 -                do showBeingSole;
  1.3134 -                send Beacon;
  1.3135 -            }
  1.3136 -
  1.3137 -            on KeyGen {
  1.3138 -                send Beacon;
  1.3139 -            }
  1.3140 -
  1.3141 -            on CannotDecrypt { // cry baby
  1.3142 -                send Beacon; 
  1.3143 -            }
  1.3144 -
  1.3145 -            on Beacon {
  1.3146 -                if sameChallenge {
  1.3147 -                    // this is our own Beacon; ignore
  1.3148 -                }
  1.3149 -                else {
  1.3150 -                    if weAreOfferer {
  1.3151 -                        do useOwnChallenge;
  1.3152 -                        send Beacon;
  1.3153 -                    }
  1.3154 -                    else /* we are requester */ {
  1.3155 -                        do openNegotiation;
  1.3156 -                        do tellWeAreNotGrouped;
  1.3157 -                        // requester is sending NegotiationRequest
  1.3158 -                        send NegotiationRequest;
  1.3159 -                        do useOwnChallenge;
  1.3160 -                    }
  1.3161 -                }
  1.3162 -            }
  1.3163 -
  1.3164 -{::include ../shared/fence-line.mkd}
  1.3165  
  1.3166  #### trustThisKey
  1.3167  
  1.3168 -The 'trustThisKey' action is executed in all states a user can do
  1.3169 -'Accept' of the Handshake dialog. The pEp implementer is told to put
  1.3170 -trust on the public key received by the other device, which wants to
  1.3171 -get paired. This means, depending on the role or grouping status the
  1.3172 -own device is in, this key is candidate to be the new default key.
  1.3173 -(Note: The trust also extends to the private key part of the public
  1.3174 -key received at a later stage of the FSM -- given the user does
  1.3175 -effectively 'Accept' on both devices; this trust can also be removed
  1.3176 -if a 'Reject' on the other device occurs, cf. {{untrustthiskey}}.)
  1.3177 -
  1.3178 -<!-- TODO: HM to merge the below paragraphe suggested by KRB to the
  1.3179 -the above paragraphe:
  1.3180 -
  1.3181 -The 'trustThisKey' action is executed in all states where a user
  1.3182 -chooses 'Accept' on the Handshake dialog.  The pEp implementer is then
  1.3183 +The 'trustThisKey' action is executed in all states when a user
  1.3184 +chooses 'Accept' on the Handshake dialog. The pEp implementer is then
  1.3185  told to put trust on the public key received by the other device that
  1.3186 -wants to be paired.  Depending on the role or grouped status the own
  1.3187 +wants to be paired. Depending on the role or grouped status the own
  1.3188  device is in, this key becomes a candidate for the new default key.
  1.3189  (Note: The trust also extends to the private key portion of the key
  1.3190  pair at a later stage in the FSM, so long as the user chooses 'Accept'
  1.3191 -on both devices.  This trust can also be removed (maybe 'revoked'?) if
  1.3192 +on both devices. This trust can also be removed if
  1.3193  a 'Reject' is chosen on the other device. cf. {{untrustthiskey}}.)
  1.3194  
  1.3195 --->
  1.3196 -
  1.3197 -<!-- TODO
  1.3198 -**[nk] I think the discussion about keys: which keys it chooses as
  1.3199 -default, under which conditions it changes etc, how group keys come
  1.3200 -into play etc. should come way earlier (or made more explicit in
  1.3201 -earlier parts of the draft), maybe right below the outlining of the
  1.3202 -accept/reject/cancel scheme. Because this is about keysync, the reader
  1.3203 -should be able to understand quickly 1) how devices can be grouped but
  1.3204 -also 2) how (which) keys are handled (how). This to me seem to be the
  1.3205 -two most important parts from which all other cases/states and other
  1.3206 -differentiations can be derived.
  1.3207 --->
  1.3208 -
  1.3209 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.3210 -
  1.3211 -{::include ../shared/fence-line.mkd}
  1.3212 -
  1.3213 -        // handshaking without existing Device group
  1.3214 -        state HandshakingOfferer timeout=600 {
  1.3215 -            
  1.3216 -            [...]
  1.3217 -
  1.3218 -            // Accept means init Phase1Commit
  1.3219 -            on Accept {
  1.3220 -                do trustThisKey;
  1.3221 -                send CommitAcceptOfferer;
  1.3222 -
  1.3223 -        [...]
  1.3224 -
  1.3225 -        // handshaking without existing Device group
  1.3226 -        state HandshakingRequester timeout=600 {
  1.3227 -
  1.3228 -            [...]
  1.3229 -            
  1.3230 -            // Accept means init Phase1Commit
  1.3231 -            on Accept {
  1.3232 -                do trustThisKey;
  1.3233 -                send CommitAcceptRequester;
  1.3234 -                go HandshakingPhase1Requester;
  1.3235 -            }
  1.3236 -
  1.3237 -        state HandshakingPhase2Offerer {
  1.3238 -            
  1.3239 -            [...]
  1.3240 -
  1.3241 -            on Accept {
  1.3242 -                send CommitAcceptOfferer;
  1.3243 -                do trustThisKey;
  1.3244 -                go FormingGroupOfferer;
  1.3245 -            }
  1.3246 -        }
  1.3247 -
  1.3248 -        [...]
  1.3249 -
  1.3250 -        state HandshakingPhase2Requester {
  1.3251 -
  1.3252 -            [...]
  1.3253 -        
  1.3254 -            on Accept {
  1.3255 -                send CommitAcceptRequester;
  1.3256 -                do trustThisKey;
  1.3257 -                go FormingGroupRequester;
  1.3258 -            }
  1.3259 -        }
  1.3260 -
  1.3261 -        [...]
  1.3262 -
  1.3263 -        state Grouped timeout=off {
  1.3264 -
  1.3265 -            [...]
  1.3266 -            
  1.3267 -            on GroupTrustThisKey
  1.3268 -                do trustThisKey;
  1.3269 -        }
  1.3270 -
  1.3271 -       [...]
  1.3272 -
  1.3273 -       state HandshakingToJoin {
  1.3274 -            
  1.3275 -            [...]
  1.3276 -
  1.3277 -            // Accept is Phase1Commit
  1.3278 -            on Accept {
  1.3279 -                do trustThisKey;
  1.3280 -                send CommitAccept;
  1.3281 -
  1.3282 -        [...]
  1.3283 -
  1.3284 -        state HandshakingToJoinPhase2 {
  1.3285 -            
  1.3286 -            [...]
  1.3287 -
  1.3288 -            on Accept {
  1.3289 -                do trustThisKey;
  1.3290 -                go JoiningGroup;
  1.3291 -            }
  1.3292 -        }
  1.3293 -
  1.3294 -        [...]
  1.3295 -
  1.3296 -        state HandshakingGrouped {
  1.3297 -
  1.3298 -            [...]
  1.3299 -
  1.3300 -            // Accept is Phase1Commit
  1.3301 -            on Accept {
  1.3302 -                do trustThisKey;
  1.3303 -                send GroupTrustThisKey;
  1.3304 -                send CommitAcceptForGroup;
  1.3305 -                go HandshakingGroupedPhase1;
  1.3306 -            }
  1.3307 -
  1.3308 -           [...]
  1.3309 -
  1.3310 -           on GroupTrustThisKey {
  1.3311 -                do hideHandshakeDialog;
  1.3312 -                do trustThisKey;
  1.3313 -            }
  1.3314 -
  1.3315 -        [...]
  1.3316 -
  1.3317 -        state HandshakingGroupedPhase1 {
  1.3318 -
  1.3319 -            [...]
  1.3320 -            
  1.3321 -            on GroupTrustThisKey {
  1.3322 -                do trustThisKey;
  1.3323 -            }
  1.3324 -
  1.3325 -        [...]
  1.3326 -
  1.3327 -        state HandshakingGroupedPhase2 {
  1.3328 -
  1.3329 -            [...]
  1.3330 -            
  1.3331 -            on Accept {
  1.3332 -                do trustThisKey;
  1.3333 -                send GroupTrustThisKey;
  1.3334 -                do prepareOwnKeys;
  1.3335 -                send GroupKeys;
  1.3336 -                go Grouped;
  1.3337 -            }
  1.3338 -
  1.3339 -{::include ../shared/fence-line.mkd}
  1.3340  
  1.3341  #### untrustThisKey
  1.3342  
  1.3343 @@ -3012,115 +1452,56 @@
  1.3344  public key, despite being imported, is never attached to messages sent
  1.3345  to outside peers.
  1.3346  
  1.3347 -<!-- TODO: HM to verify the above paragraphe suggested by KRB -->
  1.3348 -
  1.3349 -
  1.3350 -
  1.3351 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.3352 +<!-- TODO: rewrite to be clearer -->
  1.3353 +
  1.3354 +
  1.3355 +#### useOwnChallenge
  1.3356 +
  1.3357 +\[\[ TODO  \]\]
  1.3358 +
  1.3359 +<!-- clarify how this occurs. the TID comparison has already been done.
  1.3360 +I think this is the TID continuing to be sent through beacons to verify the session. -->
  1.3361 +
  1.3362 +
  1.3363 +<!--
  1.3364 +### Transitions
  1.3365 +
  1.3366 +\[\[ TODO \]\]
  1.3367 +
  1.3368 +### Events
  1.3369 +
  1.3370 +\[\[ TODO \]\]
  1.3371 +
  1.3372 +
  1.3373 +#### Events triggered by FSM
  1.3374 +
  1.3375 +\[\[ TODO \]\]
  1.3376 +
  1.3377 +##### Beacon
  1.3378 +
  1.3379 +
  1.3380 +{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.3381  
  1.3382  {::include ../shared/fence-line.mkd}
  1.3383  
  1.3384 -        state HandshakingPhase1Offerer {
  1.3385 -            on Rollback if sameNegotiationAndPartner {
  1.3386 -                do untrustThisKey;
  1.3387 -                go Sole;
  1.3388 -            }
  1.3389 -
  1.3390 -            on CommitReject if sameNegotiationAndPartner {
  1.3391 -                do untrustThisKey;
  1.3392 -                do disable;
  1.3393 -                go End;
  1.3394 -            }
  1.3395 -
  1.3396 -        [...]
  1.3397 -
  1.3398 -        state HandshakingPhase1Requester {
  1.3399 -            on Rollback if sameNegotiationAndPartner {
  1.3400 -                do untrustThisKey;
  1.3401 -                go Sole;
  1.3402 -            }
  1.3403 -
  1.3404 -            on CommitReject if sameNegotiationAndPartner {
  1.3405 -                do untrustThisKey;
  1.3406 -                do disable;
  1.3407 -                go End;
  1.3408 -            }
  1.3409  
  1.3410  {::include ../shared/fence-line.mkd}
  1.3411  
  1.3412 -#### useOwnChallenge
  1.3413 -
  1.3414 -\[\[ TODO  \]\]
  1.3415 -
  1.3416 -<!-- TODO: This was planned for review week.. -->
  1.3417 -
  1.3418 -{::include ../shared/text-blocks/see-code-where-action-called.mkd}
  1.3419 +
  1.3420 +
  1.3421 +##### NegotiationRequest
  1.3422 +
  1.3423 +
  1.3424 +{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.3425  
  1.3426  {::include ../shared/fence-line.mkd}
  1.3427  
  1.3428 -        state Sole timeout=off {
  1.3429 -
  1.3430 -            [...]
  1.3431 -
  1.3432 -            on Beacon {
  1.3433 -                if sameChallenge {
  1.3434 -                    // this is our own Beacon; ignore
  1.3435 -                }
  1.3436 -                else {
  1.3437 -                    if weAreOfferer {
  1.3438 -                        do useOwnChallenge;
  1.3439 -                        send Beacon;
  1.3440 -                    }
  1.3441 -                    else /* we are requester */ {
  1.3442 -                        do openNegotiation;
  1.3443 -                        do tellWeAreNotGrouped;
  1.3444 -                        // requester is sending NegotiationRequest
  1.3445 -                        send NegotiationRequest;
  1.3446 -                        do useOwnChallenge;
  1.3447 -                    }
  1.3448 -                }
  1.3449 -
  1.3450 -        [...]
  1.3451 -
  1.3452 -        state Sole timeout=off {
  1.3453 -            
  1.3454 -           [...]
  1.3455 -
  1.3456 -            on Beacon {
  1.3457 -                if sameChallenge {
  1.3458 -                    // this is our own Beacon; ignore
  1.3459 -                }
  1.3460 -                else {
  1.3461 -                    if weAreOfferer {
  1.3462 -                        do useOwnChallenge;
  1.3463 -                        send Beacon;
  1.3464 -                    }
  1.3465 -                    else /* we are requester */ {
  1.3466 -                        do openNegotiation;
  1.3467 -                        do tellWeAreNotGrouped;
  1.3468 -                        // requester is sending NegotiationRequest
  1.3469 -                        send NegotiationRequest;
  1.3470 -                        do useOwnChallenge;
  1.3471 -                    }
  1.3472 -                }
  1.3473  
  1.3474  {::include ../shared/fence-line.mkd}
  1.3475  
  1.3476 -<!-- 
  1.3477 -### Transitions
  1.3478 -
  1.3479 -\[\[ TODO \]\]
  1.3480 -
  1.3481 -### Events
  1.3482 -
  1.3483 -\[\[ TODO \]\]
  1.3484 -
  1.3485 -
  1.3486 -#### Events triggered by FSM
  1.3487 -
  1.3488 -\[\[ TODO \]\]
  1.3489 -
  1.3490 -##### Beacon
  1.3491 +
  1.3492 +
  1.3493 +##### NegotiationOpen
  1.3494  
  1.3495  
  1.3496  {::include ../shared/text-blocks/more-info-following-code.mkd}
  1.3497 @@ -3132,7 +1513,7 @@
  1.3498  
  1.3499  
  1.3500  
  1.3501 -##### NegotiationRequest
  1.3502 +##### Rollback
  1.3503  
  1.3504  
  1.3505  {::include ../shared/text-blocks/more-info-following-code.mkd}
  1.3506 @@ -3144,7 +1525,7 @@
  1.3507  
  1.3508  
  1.3509  
  1.3510 -##### NegotiationOpen
  1.3511 +##### CommitReject
  1.3512  
  1.3513  
  1.3514  {::include ../shared/text-blocks/more-info-following-code.mkd}
  1.3515 @@ -3156,7 +1537,7 @@
  1.3516  
  1.3517  
  1.3518  
  1.3519 -##### Rollback
  1.3520 +##### CommitAcceptOfferer
  1.3521  
  1.3522  
  1.3523  {::include ../shared/text-blocks/more-info-following-code.mkd}
  1.3524 @@ -3168,7 +1549,7 @@
  1.3525  
  1.3526  
  1.3527  
  1.3528 -##### CommitReject
  1.3529 +##### CommitAcceptRequester
  1.3530  
  1.3531  
  1.3532  {::include ../shared/text-blocks/more-info-following-code.mkd}
  1.3533 @@ -3180,7 +1561,7 @@
  1.3534  
  1.3535  
  1.3536  
  1.3537 -##### CommitAcceptOfferer
  1.3538 +##### CommitAccept
  1.3539  
  1.3540  
  1.3541  {::include ../shared/text-blocks/more-info-following-code.mkd}
  1.3542 @@ -3192,7 +1573,7 @@
  1.3543  
  1.3544  
  1.3545  
  1.3546 -##### CommitAcceptRequester
  1.3547 +##### CommitAcceptForGroup
  1.3548  
  1.3549  
  1.3550  {::include ../shared/text-blocks/more-info-following-code.mkd}
  1.3551 @@ -3204,7 +1585,7 @@
  1.3552  
  1.3553  
  1.3554  
  1.3555 -##### CommitAccept
  1.3556 +##### GroupTrustThisKey
  1.3557  
  1.3558  
  1.3559  {::include ../shared/text-blocks/more-info-following-code.mkd}
  1.3560 @@ -3216,51 +1597,10 @@
  1.3561  
  1.3562  
  1.3563  
  1.3564 -##### CommitAcceptForGroup
  1.3565 -
  1.3566 -
  1.3567 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.3568 -
  1.3569 -{::include ../shared/fence-line.mkd}
  1.3570 -
  1.3571 -
  1.3572 -{::include ../shared/fence-line.mkd}
  1.3573 -
  1.3574 -
  1.3575 -
  1.3576 -##### GroupTrustThisKey
  1.3577 -
  1.3578 -
  1.3579 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.3580 -
  1.3581 -{::include ../shared/fence-line.mkd}
  1.3582 -
  1.3583 -
  1.3584 -{::include ../shared/fence-line.mkd}
  1.3585 -
  1.3586 -
  1.3587 -
  1.3588  ##### GroupKeys
  1.3589  
  1.3590  -->
  1.3591  
  1.3592 -<!-- no longer part of the FSM
  1.3593 -
  1.3594 -##### OwnKeys
  1.3595 -
  1.3596 --->
  1.3597 -
  1.3598 -<!--
  1.3599 -
  1.3600 -{::include ../shared/text-blocks/more-info-following-code.mkd}
  1.3601 -
  1.3602 -{::include ../shared/fence-line.mkd}
  1.3603 -
  1.3604 -
  1.3605 -{::include ../shared/fence-line.mkd}
  1.3606 -
  1.3607 -
  1.3608 -
  1.3609  ##### OwnKeysOfferer
  1.3610  
  1.3611  
  1.3612 @@ -3534,13 +1874,6 @@
  1.3613  {::include ../shared/fence-line.mkd}
  1.3614  
  1.3615  
  1.3616 -<!-- no longer part of the FSM
  1.3617 -
  1.3618 -#### OwnKeys
  1.3619 -
  1.3620 -    ownIdentities IdentityList
  1.3621 -
  1.3622 --->
  1.3623  
  1.3624  #### OwnKeysOfferer
  1.3625  
  1.3626 @@ -3581,6 +1914,542 @@
  1.3627  \[\[ TODO \]\]
  1.3628  
  1.3629  
  1.3630 +# Appendix A: Finite-State Machine Code
  1.3631 +
  1.3632 +Below is the full code for the pEp KeySync FSM, including messages
  1.3633 +and external events.
  1.3634 +
  1.3635 +{::include ../shared/fence-line.mkd}
  1.3636 +
  1.3637 +fsm KeySync 1, threshold=300 {
  1.3638 +    version 1, 2;
  1.3639 +
  1.3640 +    state InitState {
  1.3641 +        on Init {
  1.3642 +            if deviceGrouped
  1.3643 +                go Grouped;
  1.3644 +            go Sole;
  1.3645 +        }
  1.3646 +    }
  1.3647 +
  1.3648 +    state Sole timeout=off {
  1.3649 +        on Init {
  1.3650 +            do newChallengeAndNegotiationBase;
  1.3651 +            do showBeingSole;
  1.3652 +            send Beacon;
  1.3653 +        }
  1.3654 +
  1.3655 +        on KeyGen {
  1.3656 +            send Beacon;
  1.3657 +        }
  1.3658 +
  1.3659 +        on CannotDecrypt { // cry baby
  1.3660 +            send Beacon;
  1.3661 +        }
  1.3662 +
  1.3663 +        on Beacon {
  1.3664 +            if sameChallenge {
  1.3665 +                // this is our own Beacon; ignore
  1.3666 +            }
  1.3667 +            else {
  1.3668 +                if weAreOfferer {
  1.3669 +                    do useOwnChallenge;
  1.3670 +                    send Beacon;
  1.3671 +                }
  1.3672 +                else /* we are requester */ {
  1.3673 +                    do openNegotiation;
  1.3674 +                    do tellWeAreNotGrouped;
  1.3675 +                    // requester is sending NegotiationRequest
  1.3676 +                    send NegotiationRequest;
  1.3677 +                    do useOwnChallenge;
  1.3678 +                }
  1.3679 +            }
  1.3680 +        }
  1.3681 +
  1.3682 +        on NegotiationRequest {
  1.3683 +            if sameChallenge { // challenge accepted
  1.3684 +                if sameNegotiation {
  1.3685 +                    // this is our own NegotiationRequest; ignore
  1.3686 +                }
  1.3687 +                else {
  1.3688 +                    do storeNegotiation;
  1.3689 +                    // offerer is accepting by confirming NegotiationOpen
  1.3690 +                    send NegotiationOpen;
  1.3691 +                    if partnerIsGrouped
  1.3692 +                        go HandshakingToJoin;
  1.3693 +                    else
  1.3694 +                        go HandshakingOfferer;
  1.3695 +                }
  1.3696 +            }
  1.3697 +        }
  1.3698 +
  1.3699 +        on NegotiationOpen if sameNegotiationAndPartner {
  1.3700 +            // requester is receiving NegotiationOpen
  1.3701 +            do storeNegotiation;
  1.3702 +            go HandshakingRequester;
  1.3703 +        }
  1.3704 +    }
  1.3705 +
  1.3706 +    // handshaking without existing Device group
  1.3707 +    state HandshakingOfferer timeout=600 {
  1.3708 +        on Init
  1.3709 +            do showSoleHandshake;
  1.3710 +
  1.3711 +        // Cancel is Rollback
  1.3712 +        on Cancel {
  1.3713 +            send Rollback;
  1.3714 +            go Sole;
  1.3715 +        }
  1.3716 +
  1.3717 +        on Rollback if sameNegotiationAndPartner
  1.3718 +            go Sole;
  1.3719 +
  1.3720 +        // Reject is CommitReject
  1.3721 +        on Reject {
  1.3722 +            send CommitReject;
  1.3723 +            do disable;
  1.3724 +            go End;
  1.3725 +        }
  1.3726 +
  1.3727 +        on CommitReject if sameNegotiationAndPartner {
  1.3728 +            do disable;
  1.3729 +            go End;
  1.3730 +        }
  1.3731 +
  1.3732 +        // Accept means init Phase1Commit
  1.3733 +        on Accept {
  1.3734 +            do trustThisKey;
  1.3735 +            send CommitAcceptOfferer;
  1.3736 +            go HandshakingPhase1Offerer;
  1.3737 +        }
  1.3738 +
  1.3739 +        // got a CommitAccept from requester
  1.3740 +        on CommitAcceptRequester if sameNegotiationAndPartner
  1.3741 +            go HandshakingPhase2Offerer;
  1.3742 +    }
  1.3743 +
  1.3744 +    // handshaking without existing Device group
  1.3745 +    state HandshakingRequester timeout=600 {
  1.3746 +        on Init
  1.3747 +            do showSoleHandshake;
  1.3748 +
  1.3749 +        // Cancel is Rollback
  1.3750 +        on Cancel {
  1.3751 +            send Rollback;
  1.3752 +            go Sole;
  1.3753 +        }
  1.3754 +
  1.3755 +        on Rollback if sameNegotiationAndPartner
  1.3756 +            go Sole;
  1.3757 +
  1.3758 +        // Reject is CommitReject
  1.3759 +        on Reject {
  1.3760 +            send CommitReject;
  1.3761 +            do disable;
  1.3762 +            go End;
  1.3763 +        }
  1.3764 +
  1.3765 +        on CommitReject if sameNegotiationAndPartner {
  1.3766 +            do disable;
  1.3767 +            go End;
  1.3768 +        }
  1.3769 +
  1.3770 +        // Accept means init Phase1Commit
  1.3771 +        on Accept {
  1.3772 +            do trustThisKey;
  1.3773 +            send CommitAcceptRequester;
  1.3774 +            go HandshakingPhase1Requester;
  1.3775 +        }
  1.3776 +
  1.3777 +        // got a CommitAccept from offerer
  1.3778 +        on CommitAcceptOfferer if sameNegotiationAndPartner
  1.3779 +            go HandshakingPhase2Requester;
  1.3780 +    }
  1.3781 +
  1.3782 +    state HandshakingPhase1Offerer {
  1.3783 +        on Rollback if sameNegotiationAndPartner {
  1.3784 +            do untrustThisKey;
  1.3785 +            go Sole;
  1.3786 +        }
  1.3787 +
  1.3788 +        on CommitReject if sameNegotiationAndPartner {
  1.3789 +            do untrustThisKey;
  1.3790 +            do disable;
  1.3791 +            go End;
  1.3792 +        }
  1.3793 +
  1.3794 +        on CommitAcceptRequester if sameNegotiationAndPartner {
  1.3795 +            go FormingGroupOfferer;
  1.3796 +        }
  1.3797 +    }
  1.3798 +
  1.3799 +    state HandshakingPhase1Requester {
  1.3800 +        on Rollback if sameNegotiationAndPartner {
  1.3801 +            do untrustThisKey;
  1.3802 +            go Sole;
  1.3803 +        }
  1.3804 +
  1.3805 +        on CommitReject if sameNegotiationAndPartner {
  1.3806 +            do untrustThisKey;
  1.3807 +            do disable;
  1.3808 +            go End;
  1.3809 +        }
  1.3810 +
  1.3811 +        on CommitAcceptOfferer if sameNegotiationAndPartner {
  1.3812 +            go FormingGroupRequester;
  1.3813 +        }
  1.3814 +    }
  1.3815 +
  1.3816 +    state HandshakingPhase2Offerer {
  1.3817 +        on Cancel {
  1.3818 +            send Rollback;
  1.3819 +            go Sole;
  1.3820 +        }
  1.3821 +
  1.3822 +        on Reject {
  1.3823 +            send CommitReject;
  1.3824 +            do disable;
  1.3825 +            go End;
  1.3826 +        }
  1.3827 +
  1.3828 +        on Accept {
  1.3829 +            send CommitAcceptOfferer;
  1.3830 +            do trustThisKey;
  1.3831 +            go FormingGroupOfferer;
  1.3832 +        }
  1.3833 +    }
  1.3834 +
  1.3835 +    state HandshakingPhase2Requester {
  1.3836 +        on Cancel {
  1.3837 +            send Rollback;
  1.3838 +            go Sole;
  1.3839 +        }
  1.3840 +
  1.3841 +        on Reject {
  1.3842 +            send CommitReject;
  1.3843 +            do disable;
  1.3844 +            go End;
  1.3845 +        }
  1.3846 +
  1.3847 +        on Accept {
  1.3848 +            send CommitAcceptRequester;
  1.3849 +            do trustThisKey;
  1.3850 +            go FormingGroupRequester;
  1.3851 +        }
  1.3852 +    }
  1.3853 +
  1.3854 +    state FormingGroupOfferer {
  1.3855 +        on Init {
  1.3856 +            do prepareOwnKeys;
  1.3857 +            send OwnKeysOfferer; // not grouped yet, this are our own keys
  1.3858 +            do showFormingGroup;
  1.3859 +        }
  1.3860 +
  1.3861 +        on Cancel {
  1.3862 +            send Rollback;
  1.3863 +            go Sole;
  1.3864 +        }
  1.3865 +
  1.3866 +        on Rollback
  1.3867 +            go Sole;
  1.3868 +
  1.3869 +        on OwnKeysRequester {
  1.3870 +            do saveGroupKeys;
  1.3871 +            do receivedKeysAreDefaultKeys;
  1.3872 +            do showGroupCreated;
  1.3873 +            go Grouped;
  1.3874 +        }
  1.3875 +    }
  1.3876 +
  1.3877 +    state FormingGroupRequester {
  1.3878 +        on Init
  1.3879 +            do showFormingGroup;
  1.3880 +
  1.3881 +        on Cancel {
  1.3882 +            send Rollback;
  1.3883 +            go Sole;
  1.3884 +        }
  1.3885 +
  1.3886 +        on Rollback
  1.3887 +            go Sole;
  1.3888 +
  1.3889 +        on OwnKeysOfferer {
  1.3890 +            do saveGroupKeys;
  1.3891 +            do prepareOwnKeys;
  1.3892 +            do ownKeysAreDefaultKeys;
  1.3893 +            send OwnKeysRequester;
  1.3894 +            do showGroupCreated;
  1.3895 +            go Grouped;
  1.3896 +        }
  1.3897 +    }
  1.3898 +
  1.3899 +    state Grouped timeout=off {
  1.3900 +        on Init {
  1.3901 +            do newChallengeAndNegotiationBase;
  1.3902 +            do showBeingInGroup;
  1.3903 +        }
  1.3904 +
  1.3905 +        on GroupKeys
  1.3906 +            do saveGroupKeys;
  1.3907 +
  1.3908 +        on KeyGen {
  1.3909 +            do prepareOwnKeys;
  1.3910 +            send GroupKeys;
  1.3911 +        }
  1.3912 +
  1.3913 +        on Beacon {
  1.3914 +            do openNegotiation;
  1.3915 +            do tellWeAreGrouped;
  1.3916 +            send NegotiationRequest;
  1.3917 +            do useOwnChallenge;
  1.3918 +        }
  1.3919 +
  1.3920 +        on NegotiationOpen if sameNegotiationAndPartner {
  1.3921 +            do storeNegotiation;
  1.3922 +            go HandshakingGrouped;
  1.3923 +        }
  1.3924 +
  1.3925 +        on GroupTrustThisKey
  1.3926 +            do trustThisKey;
  1.3927 +    }
  1.3928 +
  1.3929 +    // sole device handshaking with group
  1.3930 +    state HandshakingToJoin {
  1.3931 +        on Init
  1.3932 +            do showJoinGroupHandshake;
  1.3933 +
  1.3934 +        // Cancel is Rollback
  1.3935 +        on Cancel {
  1.3936 +            send Rollback;
  1.3937 +            go Sole;
  1.3938 +        }
  1.3939 +
  1.3940 +        on Rollback if sameNegotiationAndPartner
  1.3941 +            go Sole;
  1.3942 +
  1.3943 +        // Reject is CommitReject
  1.3944 +        on Reject {
  1.3945 +            send CommitReject;
  1.3946 +            do disable;
  1.3947 +            go End;
  1.3948 +        }
  1.3949 +
  1.3950 +        on CommitAcceptForGroup if sameNegotiationAndPartner
  1.3951 +            go HandshakingToJoinPhase2;
  1.3952 +
  1.3953 +        on CommitReject if sameNegotiationAndPartner {
  1.3954 +            do disable;
  1.3955 +            go End;
  1.3956 +        }
  1.3957 +
  1.3958 +        // Accept is Phase1Commit
  1.3959 +        on Accept {
  1.3960 +            do trustThisKey;
  1.3961 +            send CommitAccept;
  1.3962 +            go HandshakingToJoinPhase1;
  1.3963 +        }
  1.3964 +    }
  1.3965 +
  1.3966 +    state HandshakingToJoinPhase1 {
  1.3967 +        on Rollback if sameNegotiationAndPartner
  1.3968 +            go Sole;
  1.3969 +
  1.3970 +        on CommitReject if sameNegotiationAndPartner {
  1.3971 +            do disable;
  1.3972 +            go End;
  1.3973 +        }
  1.3974 +
  1.3975 +        on CommitAcceptForGroup if sameNegotiationAndPartner
  1.3976 +            go JoiningGroup;
  1.3977 +    }
  1.3978 +
  1.3979 +    state HandshakingToJoinPhase2 {
  1.3980 +        on Cancel {
  1.3981 +            send Rollback;
  1.3982 +            go Sole;
  1.3983 +        }
  1.3984 +
  1.3985 +        on Reject {
  1.3986 +            send CommitReject;
  1.3987 +            do disable;
  1.3988 +            go End;
  1.3989 +        }
  1.3990 +
  1.3991 +        on Accept {
  1.3992 +            do trustThisKey;
  1.3993 +            go JoiningGroup;
  1.3994 +        }
  1.3995 +    }
  1.3996 +
  1.3997 +    state JoiningGroup {
  1.3998 +        on GroupKeys {
  1.3999 +            do saveGroupKeys;
  1.4000 +            do receivedKeysAreDefaultKeys;
  1.4001 +            do prepareOwnKeys;
  1.4002 +            send GroupKeys;
  1.4003 +            do showDeviceAdded;
  1.4004 +            go Grouped;
  1.4005 +        }
  1.4006 +    }
  1.4007 +
  1.4008 +    state HandshakingGrouped {
  1.4009 +        on Init
  1.4010 +            do showGroupedHandshake;
  1.4011 +
  1.4012 +        // Cancel is Rollback
  1.4013 +        on Cancel {
  1.4014 +            send Rollback;
  1.4015 +            go Grouped;
  1.4016 +        }
  1.4017 +
  1.4018 +        on Rollback if sameNegotiationAndPartner
  1.4019 +            go Grouped;
  1.4020 +
  1.4021 +        // Reject is CommitReject
  1.4022 +        on Reject {
  1.4023 +            send CommitReject;
  1.4024 +            go Grouped;
  1.4025 +        }
  1.4026 +
  1.4027 +        on CommitReject if sameNegotiationAndPartner
  1.4028 +            go Grouped;
  1.4029 +
  1.4030 +        // Accept is Phase1Commit
  1.4031 +        on Accept {
  1.4032 +            do trustThisKey;
  1.4033 +            send GroupTrustThisKey;
  1.4034 +            send CommitAcceptForGroup;
  1.4035 +            go HandshakingGroupedPhase1;
  1.4036 +        }
  1.4037 +
  1.4038 +        on CommitAccept if sameNegotiationAndPartner
  1.4039 +            go HandshakingGroupedPhase2;
  1.4040 +
  1.4041 +        on GroupTrustThisKey {
  1.4042 +            do hideHandshakeDialog;
  1.4043 +            do trustThisKey;
  1.4044 +        }
  1.4045 +
  1.4046 +        on GroupKeys
  1.4047 +            do saveGroupKeys;
  1.4048 +    }
  1.4049 +
  1.4050 +    state HandshakingGroupedPhase1 {
  1.4051 +        on Rollback if sameNegotiationAndPartner
  1.4052 +            go Grouped;
  1.4053 +
  1.4054 +        on CommitReject if sameNegotiationAndPartner
  1.4055 +            go Grouped;
  1.4056 +
  1.4057 +        on CommitAccept if sameNegotiationAndPartner {
  1.4058 +            do prepareOwnKeys;
  1.4059 +            send GroupKeys;
  1.4060 +            go Grouped;
  1.4061 +        }
  1.4062 +
  1.4063 +        on GroupTrustThisKey {
  1.4064 +            do trustThisKey;
  1.4065 +        }
  1.4066 +
  1.4067 +        on GroupKeys
  1.4068 +            do saveGroupKeys;
  1.4069 +    }
  1.4070 +
  1.4071 +    state HandshakingGroupedPhase2 {
  1.4072 +        on Cancel {
  1.4073 +            send Rollback;
  1.4074 +            go Grouped;
  1.4075 +        }
  1.4076 +
  1.4077 +        on Reject {
  1.4078 +            send CommitReject;
  1.4079 +            go Grouped;
  1.4080 +        }
  1.4081 +
  1.4082 +        on Accept {
  1.4083 +            do trustThisKey;
  1.4084 +            send GroupTrustThisKey;
  1.4085 +            do prepareOwnKeys;
  1.4086 +            send GroupKeys;
  1.4087 +            go Grouped;
  1.4088 +        }
  1.4089 +
  1.4090 +        on GroupTrustThisKey {
  1.4091 +            do trustThisKey;
  1.4092 +        }
  1.4093 +
  1.4094 +        on GroupKeys
  1.4095 +            do saveGroupKeys;
  1.4096 +    }
  1.4097 +
  1.4098 +    external Accept 129;
  1.4099 +    external Reject 130;
  1.4100 +    external Cancel 131;
  1.4101 +
  1.4102 +    // beacons are always broadcasted
  1.4103 +
  1.4104 +    message Beacon 2, type=broadcast, security=unencrypted {
  1.4105 +        field TID challenge;
  1.4106 +        auto Version version;
  1.4107 +    }
  1.4108 +
  1.4109 +    message NegotiationRequest 3, security=untrusted {
  1.4110 +        field TID challenge;
  1.4111 +        auto Version version;
  1.4112 +        field TID negotiation;
  1.4113 +        field bool is_group;
  1.4114 +    }
  1.4115 +
  1.4116 +    message NegotiationOpen 4, security=untrusted {
  1.4117 +        auto Version version;
  1.4118 +        field TID negotiation;
  1.4119 +    }
  1.4120 +
  1.4121 +    message Rollback 5, security=untrusted {
  1.4122 +        field TID negotiation;
  1.4123 +    }
  1.4124 +
  1.4125 +    message CommitReject 6, security=untrusted {
  1.4126 +        field TID negotiation;
  1.4127 +    }
  1.4128 +
  1.4129 +    message CommitAcceptOfferer 7, security=untrusted {
  1.4130 +        field TID negotiation;
  1.4131 +    }
  1.4132 +
  1.4133 +    message CommitAcceptRequester 8, security=untrusted {
  1.4134 +        field TID negotiation;
  1.4135 +    }
  1.4136 +
  1.4137 +    message CommitAccept 9, security=untrusted {
  1.4138 +        field TID negotiation;
  1.4139 +    }
  1.4140 +
  1.4141 +    message CommitAcceptForGroup 10, security=untrusted {
  1.4142 +        field TID negotiation;
  1.4143 +    }
  1.4144 +
  1.4145 +    // default: security=trusted only
  1.4146 +    message GroupTrustThisKey 11 {
  1.4147 +        field Hash key;
  1.4148 +    }
  1.4149 +
  1.4150 +    // trust in future
  1.4151 +    message GroupKeys 12, security=attach_own_keys {
  1.4152 +        field IdentityList ownIdentities;
  1.4153 +    }
  1.4154 +
  1.4155 +    message OwnKeysOfferer 13, security=attach_own_keys {
  1.4156 +        field IdentityList ownIdentities;
  1.4157 +    }
  1.4158 +
  1.4159 +    message OwnKeysRequester 14, security=attach_own_keys {
  1.4160 +        field IdentityList ownIdentities;
  1.4161 +    }
  1.4162 +}
  1.4163 +
  1.4164 +{::include ../shared/fence-line.mkd}
  1.4165 +
  1.4166  # Security Considerations
  1.4167  
  1.4168  \[\[ TODO \]\]
  1.4169 @@ -3592,19 +2461,24 @@
  1.4170  Internet users presented with Trustwords engage in comparing them
  1.4171  manually.
  1.4172  
  1.4173 -If an attacker gains possession to a device which is configured to
  1.4174 +If an attacker gains physical possession of a Sole device which is configured to
  1.4175  receive messages for a pEp identity, the attacker can start to build
  1.4176 -own Device Groups as long as the legitimate user does not stop the
  1.4177 -attacker to have read access to the respective channel (e.g., in
  1.4178 -email: to the mailbox) - to read Beacon messages; this allows an
  1.4179 -attacker to create at least some kind of disturbance towards Sole
  1.4180 -Devices and already existing Device Groups.
  1.4181 -
  1.4182 -In case an attacker gains possession of a device which is already
  1.4183 -grouped, such an attacker gets into a MITM position allowing to
  1.4184 -impersonate a user as long as the legitimate user does not manage to
  1.4185 -stop the attacker to use the respective account (e.g., in email: by
  1.4186 -changing access credentials).
  1.4187 +their own Device Groups for as long as the legitimate user does not
  1.4188 +take measures to prevent the attacker from having read access to the respective
  1.4189 +channel used to read Beacon messages (e.g., an email inbox); this would
  1.4190 +allow an attacker to create at least some kind of disturbance towards
  1.4191 +other Sole Devices and existing Device Groups.
  1.4192 +
  1.4193 +In case an attacker gains physical possession of a device which is already
  1.4194 +part of a Device Group, they would automatically be in a MITM position.
  1.4195 +The attacker would be able to impersonate the legitimate user as long
  1.4196 +as the user does not take measures to stop the attacker from using the
  1.4197 +affected account(s) that the compromised device had access to.
  1.4198 +
  1.4199 +In both of these cases, potential damage can be mitigated by changing
  1.4200 +access credentials for all affected accounts, and leaving the Device
  1.4201 +Group from any remaining Grouped Devices. For Sole devices, all keys
  1.4202 +used on that device should be revoked.
  1.4203  
  1.4204  -->
  1.4205  
  1.4206 @@ -3614,6 +2488,9 @@
  1.4207  many readers will have them in their head right away, so I think it
  1.4208  would be good to cover or link to them more prominently. (relates to
  1.4209  section 1.3)
  1.4210 +**[KRB] The security considerations section is required to be towards
  1.4211 +the end of the document per IETF, but the concerns in this section are
  1.4212 +discussed briefly in the Use Cases section.
  1.4213  
  1.4214  -->
  1.4215  
  1.4216 @@ -3667,7 +2544,7 @@
  1.4217  
  1.4218  \[\[ RFC Editor: This section is to be removed before publication \]\]
  1.4219  
  1.4220 -* draft-hoeneisen-pep-keysync-00:
  1.4221 +* draft-hoeneisen-pep-KeySync-00:
  1.4222    * Initial version
  1.4223  
  1.4224  # Open Issues
  1.4225 @@ -3677,7 +2554,7 @@
  1.4226  
  1.4227  * Resolve several TODOs / add missing text
  1.4228  
  1.4229 -<!-- 
  1.4230 +<!--
  1.4231  * Do we need a section "Relationship to other pEp documents" in the
  1.4232    introduction?
  1.4233  -->