idnits 2.17.1 draft-birk-pep-keysync-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 07, 2019) is 1749 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-06) exists of draft-birk-pep-03 ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Downref: Normative reference to an Informational RFC: RFC 7435 == Outdated reference: A later version (-05) exists of draft-birk-pep-trustwords-03 == Outdated reference: A later version (-05) exists of draft-marques-pep-handshake-02 Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Hoeneisen 3 Internet-Draft Ucom.ch 4 Intended status: Standards Track H. Marques 5 Expires: January 8, 2020 pEp Foundation 6 July 07, 2019 8 pretty Easy privacy (pEp): Key Synchronization Protocol 9 draft-birk-pep-keysync-00 11 Abstract 13 Modern users of messaging systems usually have multiple devices, and 14 often desire to send and receive encrypted messages on some or all of 15 their devices. Using encryption on multiple devices often results in 16 situations where messages cannot be decrypted on the device used to 17 read the message due to a missing private key. 19 This document specifies a protocol for secure peer-to-peer 20 synchronization of private keys across devices belonging to the same 21 user (pEp Key Synchronization Protocol). 23 The pretty Easy privacy (pEp) protocols describe a set of conventions 24 for the automation of operations traditionally seen as barriers to 25 the use and deployment of secure end-to-end interpersonal messaging. 26 These include, but are not limited to, key management, key discovery, 27 and private key handling. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on January 8, 2020. 46 Copyright Notice 48 Copyright (c) 2019 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Problem Statement . . . . . . . . . . . . . . . . . . . . 3 65 1.2. Approach . . . . . . . . . . . . . . . . . . . . . . . . 4 66 1.3. Main Challenge . . . . . . . . . . . . . . . . . . . . . 4 67 1.4. Requirements Language . . . . . . . . . . . . . . . . . . 4 68 1.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 4 69 2. General Description . . . . . . . . . . . . . . . . . . . . . 5 70 2.1. Use Cases for pEp KeySync . . . . . . . . . . . . . . . . 6 71 2.1.1. Form Device Group . . . . . . . . . . . . . . . . . . 6 72 2.1.2. Add New Device to Existing Device Group . . . . . . . 6 73 2.1.3. Exchange Private Keys . . . . . . . . . . . . . . . . 6 74 2.1.4. Leave Device Group . . . . . . . . . . . . . . . . . 7 75 2.1.5. Remove other Device from Device Group . . . . . . . . 7 76 2.2. Interaction Diagrams . . . . . . . . . . . . . . . . . . 7 77 2.2.1. Form Device Group . . . . . . . . . . . . . . . . . . 8 78 2.2.2. Add New Device to Existing Device Group . . . . . . . 16 79 2.2.3. Exchange Private Keys . . . . . . . . . . . . . . . . 23 80 2.2.4. Leave Device Group . . . . . . . . . . . . . . . . . 23 81 2.2.5. Remove other Device from Device Group . . . . . . . . 23 82 2.3. Simplified Finite-State Machine . . . . . . . . . . . . . 23 83 3. Reference Implementation . . . . . . . . . . . . . . . . . . 24 84 3.1. Full Finite-State Machine . . . . . . . . . . . . . . . . 24 85 3.1.1. States . . . . . . . . . . . . . . . . . . . . . . . 24 86 3.1.2. Actions . . . . . . . . . . . . . . . . . . . . . . . 43 87 3.2. Messages . . . . . . . . . . . . . . . . . . . . . . . . 69 88 3.2.1. Format . . . . . . . . . . . . . . . . . . . . . . . 69 89 3.2.2. List of Messages Used in Finite-State Machine . . . . 69 90 3.2.3. Example Messages . . . . . . . . . . . . . . . . . . 72 91 4. Security Considerations . . . . . . . . . . . . . . . . . . . 72 92 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 72 93 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 72 94 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 72 95 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 73 96 8.1. Normative References . . . . . . . . . . . . . . . . . . 73 97 8.2. Informative References . . . . . . . . . . . . . . . . . 73 98 Appendix A. Document Changelog . . . . . . . . . . . . . . . . . 74 99 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 74 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 74 102 1. Introduction 104 This document specifies the pEp Key Synchronization (KeySync) 105 Protocol, a means for secure peer-to-peer synchronization of private 106 keys across devices belonging to the same user. 108 This part of the pretty Easy privacy (pEp) protocols [I-D.birk-pep] 109 presents a way to synchronize private key material in a decentralized 110 manner that is easy to implement. This network protocol is designed 111 as a finite-state machine (FSM) along with the exchange of specific 112 KeySync messages. 114 For pEp implementations, pEp KeySync for key synchronization is a 115 critical part of the broader pEp Sync protocol, which is designed to 116 be extensible to allow for the synchronization of additional user 117 data, such as configuration settings and peer trust status 118 information across a user's devices. 120 This document will provide a general description of pEp KeySync, 121 including idealized use cases, diagrams, and examples of messages 122 that may be generated during the KeySync process. 124 1.1. Problem Statement 126 Modern users of messaging systems usually have multiple devices, and 127 often desire to send and receive encrypted messages on some or all of 128 them. 130 Using encryption on multiple devices often results in situations 131 where messages cannot be decrypted on the device used to read the 132 message due to a missing private key. These messages were likely 133 encrypted with a key that was generated on another device belonging 134 to the same user. For example, the sender encrypts with a key that 135 was generated on the home laptop of the recipient. The recipient 136 then attempts to decrypt the message on their mobile phone, where the 137 corresponding private key is not available. As a result, the 138 recipient either must return to their laptop to decrypt the message, 139 or attempt to copy the correct private key to their mobile device, 140 which may expose the user's private key to potential leaks or theft. 142 1.2. Approach 144 The basic approach to solving the multiple-device decryption problem 145 is to synchronize private keys among the devices of a user in a 146 secure manner. pEp aims to do this by using Trustword confirmation 147 (cf. [I-D.birk-pep-trustwords]) between any two devices at a time 148 for pairing purposes. Simply put, a user needs to manually compare 149 and confirm Trustwords before the automatic and security-sensitive 150 transfer of private key information can occur. 152 1.3. Main Challenge 154 The main challenge, that pEp KeySync is designed to overcome, is to 155 perform the synchronization in a secure manner so that private keys 156 are not leaked or exposed to theft. 158 Note: The case of an adversary getting access to the device itself is 159 beyond the scope of this document. 161 1.4. Requirements Language 163 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 164 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 165 document are to be interpreted as described in [RFC2119]. 167 1.5. Terms 169 The following terms are defined for the scope of this document: 171 o pEp Handshake: The process of one user contacting another over an 172 independent channel in order to verify Trustwords (or by fallback: 173 fingerprints). This can be done in-person or through established 174 verbal communication channels, like a phone call. 175 [I-D.marques-pep-handshake] 177 Note: In pEp KeySync, the handshake is used to authenticate own 178 devices (the user normally compares the Trustwords directly by 179 looking at the screens of the devices involved). 181 o Trustwords: A scalar-to-word representation of 16-bit numbers (0 182 to 65535) to natural language words. When doing a Handshake, 183 peers are shown combined Trustwords of both public keys involved 184 to ease the comparison. [I-D.birk-pep-trustwords] 186 o Trust On First Use (TOFU): cf. [RFC7435], which states: "In a 187 protocol, TOFU calls for accepting and storing a public key or 188 credential associated with an asserted identity, without 189 authenticating that assertion. Subsequent communication that is 190 authenticated using the cached key or credential is secure against 191 an MiTM attack, if such an attack did not succeed during the 192 vulnerable initial communication." 194 o Man-in-the-middle (MITM) attack: cf. [RFC4949], which states: "A 195 form of active wiretapping attack in which the attacker intercepts 196 and selectively modifies communicated data to masquerade as one or 197 more of the entities involved in a communication association." 199 o Identity: The combination of a unique user ID plus a specific 200 address (email, network ID, URI, etc.). A single user may have 201 multiple identities. 203 o Device Group: All devices that are grouped to share data like 204 cryptographic keys, trust information, calendar, configuration and 205 other data. The data is synchronized through a common channel for 206 a given identity, e.g., an identity can be an email address and 207 the common channel a mailbox in email. 209 o Group Key: A key pair primarily used by a Device Group for a 210 certain identity. A Device Group has a Group Key for each of a 211 user's identities. 213 o Sole Device: A device which is not part of a Device Group. 215 o Grouped Device: A device which is already part of a Device Group. 217 o Beacon (message): A technical text message that is broadcast by 218 Sole Devices and transmitted through a message sent to the channel 219 of an identity. Other Sole Devices, or a Grouped Device of the 220 same unique identity and using that identity's channel, can 221 interpret this Beacon in order to initiate negotiation for the 222 formation of a Device Group. 224 2. General Description 226 This section describes an ideal-condition use case for pEp KeySync. 227 It focuses on the main procedures and on the scenarios where 228 everything works. Unexpected user behavior, error handling, race 229 conditions and the like are mostly omitted from this section in order 230 to facilitate a better understanding of the general concepts of pEp 231 KeySync. Additional use cases will be discussed in further detail 232 throughout Section 3. 234 2.1. Use Cases for pEp KeySync 236 2.1.1. Form Device Group 238 Our user, Alice, has two devices that are configured with pEp- 239 implementing messaging clients and share the same identity for her 240 preferred communication channel (in our example: a communication 241 channel with an email address). Let us call these devices Alice_R 242 and Alice_O. Each device already has its own key pair, which was 243 automatically generated by the pEp protocol. Neither device knows 244 anything about the other. 246 Alice wants full communication capability from both of her devices, 247 but currently cannot do so, as the devices do not know about each 248 other. Alice will use pEp Keysync to form a Device Group and add her 249 devices to it. This allows for the exchange of private key data 250 among its devices, allowing Alice to have full communication 251 capability on both of her devices. 253 2.1.2. Add New Device to Existing Device Group 255 Sometime after devices Alice_R and Alice_O have formed a Device Group 256 (cf. Section 2.1.1), Alice buys another device, Alice_J, which is 257 also configured with pEp-implementing messaging clients and shares 258 the same identity for her preferred communication channel (the 259 aforementioned email address). Alice_J also has a key pair, which 260 was automatically generated by the pEp protocol, just as the Grouped 261 Devices Alice_R and Alice_O have. But while the Grouped Devices know 262 each other and have exchanged private keys, Alice_J and the Grouped 263 Devices don't know anything each other. Thus, Alice does not have 264 full communication capability across the three devices. 266 As before with devices Alice_R and Alice_O, Alice will use pEp 267 Keysync to add device Alice_J to the existing Device Group, allowing 268 all three devices to exchange private key information, and Alice to 269 have access to her messages from any of them. 271 2.1.3. Exchange Private Keys 273 All devices from Alice are part of a Device Group (cf. Section 2.1.1 274 and Section 2.1.2). However, as keys may expire or get reset, 275 occasionally new key pairs are generated. For Alice to be able to 276 read all encrypted messages on all devices, any new private key needs 277 to be shared with the other devices in the device group. All devices 278 in Alice's Device Group will share the latest private keys as they 279 are generated, keeping all of her devices up to date and functioning 280 as desired. 282 2.1.4. Leave Device Group 284 Alice may decide that one of her devices (e.g., her mobile phone) 285 should no longer have access to all private keys of the Device Group. 286 Alice can manually tell that device to leave the Device Group. The 287 Device Group will ensure that further communication among the 288 remaining Grouped Devices is private. 290 2.1.5. Remove other Device from Device Group 292 One of Alice's devices may be stolen or become otherwise compromised. 293 She needs to ensure that the affected device no longer receives 294 updates to private keys from the other devices in her Device Group. 295 Alice can initiate actions to mitigate the damage, including the 296 revocation of her private keys, as well as forcibly removing the 297 compromised device from her Device Group. 299 2.2. Interaction Diagrams 301 The following interaction diagrams depict what happens during Alice's 302 KeySync scenarios in a simplified manner. For each scenario, we 303 first present a successful case, then an unsuccessful case and, 304 finally, a case that has been interrupted, or discontinued. Some 305 details are skipped here for the sake of readability. Descriptions 306 of the interactions are included after each diagram. 308 2.2.1. Form Device Group 310 2.2.1.1. Successful Case 312 ,-. 313 `-' 314 /|\ 315 ,----------------. | ,------------------. 316 |'Offerer' device| / \ |'Requester' device| 317 `-------+--------' User `--------+---------' 318 | | | 319 | | | 320 | 1(r). Beacon (challenge TID) | 321 |<--------------------------------------------| 322 | | | 323 | 1(o). Beacon (challenge TID) | 324 |-------------------------------------------->| 325 | | | 326 | 2. NegotiationRequest | 327 |<--------------------------------------------| 328 | | | 329 | | 3. Display Trustwords| 330 | |<- - - - - - - - - - -| 331 | | | 332 | 4. NegotiationOpen | 333 |-------------------------------------------->| 334 | | | 335 | 5. Display Trustwords| | 336 | - - - - - - - - - - >| | 337 | | | 338 | ,-----------------------------. | 339 | |Handshake (user comparison | | 340 | |of Trustwords) successful | | 341 | `-----------------------------' | 342 ,-----------------------------------. | 343 |User presses 'Accept' button | | 344 |on 'Requestor' device | | 345 `-----------------------------------' | 346 | | 6. Accept | 347 | | - - - - - - - - - - >| 348 | | | 349 | 7. CommitAcceptRequester | 350 |<--------------------------------------------| 351 | | | 352 ,-----------------------------------. | 353 |User presses 'Accept' button | | 354 |on 'Offerer' Device | | 355 `-----------------------------------' | 356 | 8. Accept | | 357 |<- - - - - - - - - - -| | 358 | | | 359 | 9. CommitAcceptOfferer | 360 |-------------------------------------------->| 361 | | | 362 | 10. OwnKeysOfferer + keys | 363 |-------------------------------------------->| 364 | | | 365 | | ,----------------------. 366 | | |Requester is Grouped | 367 | | `----------------------' 368 | 11. OwnKeysRequester + keys | 369 |<--------------------------------------------| 370 | | | 371 ,--------------------. | | 372 |Offerer is Grouped | | | 373 `--------------------' | | 374 | | | 375 ,-------+--------. User ,--------+---------. 376 |'Offerer' device| ,-. |'Requester' device| 377 `----------------' `-' `------------------' 378 /|\ 379 | 380 / \ 382 As depicted above, a user intends to form a Device Group in order to 383 securely share key material among its members. The group is formed 384 by an 'Offerer' device and a 'Requester' device. The names 'Offerer' 385 and 'Requester' are derived from the FSM (cf. Section 2.3), in which 386 the device roles are defined during the start sequence, which is 387 necessary for the FSM to work as intended. 389 During initialization of pEp KeySync, each device generates a UUID 390 version 4, variant 1 number, which is called a Transaction-ID (TID). 391 These TIDs are sent as a challenge in a Beacon over the mutual 392 channel, and the device roles of 'Offerer' and 'Requester' are 393 determined by the numeric value of each device's unique TID. 395 Note: All messages are 'broadcast'. The TIDs added to each message 396 allow the identification of received messages which pertain to the 397 ongoing transaction and its sender. 399 1. Every device sends a Beacon message containing a challenge TID. 400 Upon receipt of a Beacon message from another device, the the 401 received challenge TID is compared with the device's own 402 challenge TID. The device which has a TID with a lower 403 numerical value is assigned as the 'Requester', and the other 404 device is automatically assigned as the 'Offerer'. 406 Note: The 'Offerer' device MUST NOT start a Negotiation. Thus, 407 it re-sends its own Beacon (for robustness in case earlier 408 Beacon message got lost) and waits. Message 1(r) depicts the 409 Beacon message sent by the 'Requester' device and is not 410 required for the process to continue. 412 2. After determination of the role, the 'Requester' device sends a 413 NegotiationRequest message. 415 3. The 'Requester' device displays the Trustwords to the user. 417 4. Upon receipt of the NegotiationRequest message, the 'Offerer' 418 device sends a NegotiationOpen message. 420 5. The 'Offerer' device displays the Trustwords to the user. 422 6. The user compares the Trustwords of both devices. As the 423 Trustwords are the same on both devices, the user presses the 424 'Accept' button on the 'Requester' device. 426 Note 1: The user may also press the 'Accept' button on the 427 'Offerer' device first. The end result is not affected by which 428 'Accept' button is pressed first. However, the order of the 429 messages slightly changes. 431 Note 2: The user may also choose to press the 'Cancel' button or 432 the 'Reject' button (see below). 434 7. On receipt of the user's 'Accept', the 'Requester' device sends 435 a CommitAcceptRequester message. 437 The 'Offerer' device receives this message and waits for the 438 user to press the local 'Accept' button. 440 8. The user compares the Trustwords of both devices and presses the 441 'Accept' button on the 'Offerer' device. 443 Note: The user may also choose to press the 'Cancel' button or 444 the 'Reject' button (see below). 446 9. On receipt of the user's 'Accept', the 'Offerer' device sends a 447 CommitAcceptRequester message. 449 10. The 'Offerer' device then sends an OwnKeysOfferer message along 450 with the user's local key pairs (private and public keys) to 451 to be synchronized. 453 11. Upon receipt of the OwnKeysOfferer message, the 'Requester' 454 device is Grouped and sends an OwnKeysRequester message along 455 with the user's local key pairs (private and public keys) to be 456 synchronized. 458 Upon receipt of the OwnKeysRequester message, also the 'Offerer' 459 device is grouped. The formation of the Device Group has been 460 successful. 462 2.2.1.2. Unsuccessful Case 464 ,-. 465 `-' 466 /|\ 467 ,----------------. | ,------------------. 468 |'Offerer' device| / \ |'Requester' device| 469 `-------+--------' User `--------+---------' 470 | | | 471 | | | 472 ,--------------------------------------------------------------!. 473 |Messages (1-5) are same as in the successful case (see above) |_\ 474 `----------------------------------------------------------------' 475 | | | 476 | | | 477 | ,-----------------------------. | 478 | |Handshake (user comparison | | 479 | |of Trustwords) unsuccessful | | 480 | `-----------------------------' | 481 | ,------------------------------------. 482 | |User presses 'Reject' button | 483 | |on 'Requestor' device | 484 | `------------------------------------' 485 | | R6. Reject | 486 | | - - - - - - - - - - >| 487 | | | 488 | R7. CommitReject | 489 |<-------------------------------------------| 490 | | | 491 ,--------------------------------------------------------------!. 492 |Devices (still not grouped) will not try again |_\ 493 `----------------------------------------------------------------' 494 | | | 495 ,-------+--------. User ,--------+---------. 496 |'Offerer' device| ,-. |'Requester' device| 497 `----------------' `-' `------------------' 498 /|\ 499 | 500 / \ 502 For unsuccessful KeySync attempts, messages 1-5 are the same as in a 503 successful attempt (see above), but once the Trustwords are shown, 504 events are as follows: 506 R6. The user compares the Trustwords of both devices. As the 507 Trustwords do not match, the user presses the 'Reject' button on 508 the 'Requester' device. 510 Note: The user may also press the 'Reject' button on the 511 'Offerer' device first. The end result is not affected by which 512 'Reject' button is pressed first. However, the order of the 513 messages slightly changes. 515 R7. On receipt of the user's 'Reject', the 'Requester' device sends 516 a CommitReject message. 518 Once the CommitReject message is sent or received, respectively, the 519 devices cannot form a Device Group, and pEp KeySync is disabled on 520 both devices. As a result, there are no further attempts to form a 521 Device Group involving either of these two devices. 523 2.2.1.3. Discontinuation Case 525 ,-. 526 `-' 527 /|\ 528 ,----------------. | ,------------------. 529 |'Offerer' device| / \ |'Requester' device| 530 `-------+--------' User `--------+---------' 531 | | | 532 | | | 533 ,--------------------------------------------------------------!. 534 |Messages (1-5) are same as in the successful case (see above) |_\ 535 `----------------------------------------------------------------' 536 | | | 537 | | | 538 | ,-----------------------------. | 539 | |Handshake (user comparison | | 540 | |of Trustwords) discontinued | | 541 | `-----------------------------' | 542 | ,------------------------------------. 543 | |User presses 'Cancel' button | 544 | |on 'Requestor' device | 545 | `------------------------------------' 546 | | C6. Cancel | 547 | | - - - - - - - - - - >| 548 | | | 549 | C7. Rollback | 550 |<-------------------------------------------| 551 | | | 552 ,--------------------------------------------------------------!. 553 |Devices (still not grouped) will try again |_\ 554 `----------------------------------------------------------------' 555 | | | 556 ,-------+--------. User ,--------+---------. 557 |'Offerer' device| ,-. |'Requester' device| 558 `----------------' `-' `------------------' 559 /|\ 560 | 561 / \ 563 For discontinued (canceled) KeySync attempts, messages 1-5 are the 564 same as in a successful attempt (see above), but once the Trustwords 565 are shown, events are as follows: 567 C6. The user decides to discontinue the process and presses the 568 'Cancel' button on the 'Requester' device. 570 Note: The user may also press the 'Cancel' button on the 571 'Offerer' device first. The end result is not affected by which 572 'Cancel' button is pressed first. However, the order of the 573 messages slightly changes. 575 C7. On receipt of the user's 'Cancel', the 'Requester' device sends 576 a rollback message. 578 The devices do not form a Device Group. KeySync remains enabled and 579 forming a Device Group can start again. 581 2.2.2. Add New Device to Existing Device Group 583 2.2.2.1. Successful Case 585 ,-------. ,-. 586 |New | `-' ,--------. ,--------. 587 |device | /|\ |Active | |Passive | 588 |to join| | |device | |devices | 589 |group | / \ |in group| |in group| 590 `---+---' User `---+----' `---+----' 591 | | | | 592 | | | | 593 | 1. Beacon | | 594 |--------------------------------->| | 595 | | | | 596 | | 1. Beacon | | 597 |----------------------------------------------------->| 598 | | | | 599 | 2(p). NegotiationRequest | 600 |<-----------------------------------------------------| 601 | | | | 602 | | 3(p) Display Trustwords | 603 | |<- - - - - - - - - - - - - - - - - - | 604 | | | | 605 | 4(p) NegotiationOpen | 606 |----------------------------------------------------->| 607 | | | | 608 | 2(a). NegotiationRequest | | 609 |<---------------------------------| | 610 | | | | 611 | | 3(a). Display | | 612 | | Trustwords | | 613 | |<- - - - - - - - | | 614 | | | | 615 | 4(a). NegotiationOpen | | 616 |--------------------------------->| | 617 | | | | 618 | 5. Display | | | 619 | Trustwords | | | 620 | - - - - - - - >| | | 621 | | | | 622 | ,-----------------------------. | | 623 | |Handshake (user comparison | | | 624 | |of Trustwords) successful | | | 625 | `-----------------------------' | | 626 | ,------------------------------. | 627 | |User presses 'Accept' button | | 628 | |on a device in group | | 629 | `------------------------------' | 630 | | 6. Accept | | 631 | | - - - - - - - ->| | 632 | | | | 633 | | | 7. GroupTrust | 634 | | | ThisKey | 635 | | |------------------>| 636 | | | | 637 | 8. CommitAcceptForGroup | | 638 |<---------------------------------| | 639 | | | | 640 ,------------------------------. | | 641 |User presses 'Accept' button | | | 642 |on new device | | | 643 `------------------------------' | | 644 | 9. Accept | | | 645 |<- - - - - - - -| | | 646 | | | | 647 | 10. CommitAccept | | 648 |--------------------------------->| | 649 | | | | 650 | 11. GroupKeys + keys | | 651 |<---------------------------------| | 652 | | | | 653 ,------------. | | | 654 |New device | | | | 655 |is grouped | | | | 656 `------------' | | | 657 | 12. GroupKeys + keys | | 658 |--------------------------------->| | 659 | | | | 660 | | 12. GroupKeys + keys | 661 |----------------------------------------------------->| 662 | | | | 663 | | | | 664 ,---+---. User ,---+----. ,---+----. 665 |New | ,-. |Active | |Passive | 666 |device | `-' |device | |devices | 667 |to join| /|\ |in group| |in group| 668 |group | | `--------' `--------' 669 `-------' / \ 671 As depicted above, a user intends to add a new device to an existing 672 Device Group. 674 Note: All messages are 'broadcast'. The TIDs added to each message 675 allow the identification of received messages which pertain to the 676 ongoing transaction and its sender. 678 1. During initialization of pEp KeySync, the new device sends a 679 Beacon message. 681 Note: In the diagram, all messages marked "1. Beacon" are a 682 single message, but drawn separately in order to convey that the 683 message is sent to all devices in the Device Group. 685 2. Upon receipt of a Beacon message from a device not part of a 686 Device Group, all Grouped Devices are send a NegotiationRequest 687 message. 689 Note: Messages 2(a) and 2(p) are different instances of the 690 NegotiationRequest message type. 692 3. All Grouped Devices display the Trustwords to the user. 694 4. Upon receipt of every NegotiationRequest message, the New Device 695 sends a NegotiationOpen message. 697 Note: Messages 4(a) and 4(p) are different instances of the 698 NegotiationOpen message type. 700 5. The new device displays the Trustwords to the user. 702 6. The user compares the Trustwords of both devices and presses the 703 'Accept' button on one of the Grouped Devices. 705 Note 1: The Grouped Device that the user presses the 'Accept' 706 button on now assumes the role of the active device in Group, 707 while the other Grouped Devices get the role of passive devices 708 in the group. 710 Note 2: The user may also press the 'Accept' button on the new 711 device first. The end result is not affected by which 'Accept' 712 button is pressed first. However, the order and number of the 713 messages change. 715 Note 3: The user may also choose to press the 'Cancel' button or 716 the 'Reject' button (see below). 718 7. On receipt of the user's 'Accept', the active Grouped Device 719 sends a TrustThisKey message, which is consumed by the passive 720 Grouped Devices. 722 8. Then, the Active Grouped Device also sends a 723 CommitAcceptForGroup message. 725 The new device receives this message and waits for the user to 726 press the local 'Accept' button. 728 9. The user compares the Trustwords of both devices and presses the 729 'Accept' button on the new device. 731 Note: The user may also choose to press the 'Cancel' button or 732 the 'Reject' button. However, these cases are explained later. 734 10. On receipt of the user's 'Accept', the new device sends a 735 CommitAccept message. 737 11. The new device then sends a GroupKeys message along with its own 738 private keys. 740 12. Upon receipt of the GroupKeys message, the Active Grouped Device 741 is Grouped and sends a GroupKeys message along with its own 742 private keys. The new device has successfully joined the Device 743 Group. 745 Note: In the diagram, all messages marked "12. GroupKeys + keys" are 746 a single message, but drawn separately in order to convey that the 747 message is sent to all devices in the Device Group. 749 2.2.2.2. Unsuccessful Case 751 ,-------. ,-. 752 |New | `-' ,--------. ,--------. 753 |device | /|\ |Active | |Passive | 754 |to join| | |device | |devices | 755 |group | / \ |in group| |in group| 756 `---+---' User `---+----' `---+----' 757 | | | | 758 | | | | 759 ,---------------------------------------------------------------!. 760 |Messages (1-5) are same as in the successful case (see above) |_\ 761 `-----------------------------------------------------------------' 762 | | | | 763 | | | | 764 | ,-----------------------------. | | 765 | |Handshake (user comparison | | | 766 | |of Trustwords) unsuccessful | | | 767 | `-----------------------------' | | 768 | ,------------------------------. | 769 | |User presses 'Reject' button | | 770 | |on a device in group | | 771 | `------------------------------' | 772 | | R6. Reject | | 773 | | - - - - - - - ->| | 774 | | | | 775 | R7. CommitReject | | 776 |<---------------------------------| | 777 | | | | 778 | | | R7. CommitReject | 779 | | |------------------>| 780 | | | | 781 ,----------!. | | | 782 |New device|_\ | | | 783 |(still not | | | | 784 |grouped) | | | | 785 |will not | | | | 786 |try again | | | | 787 `------------' | | | 788 | | | | 789 ,---+---. User ,---+----. ,---+----. 790 |New | ,-. |Active | |Passive | 791 |device | `-' |device | |devices | 792 |to join| /|\ |in group| |in group| 793 |group | | `--------' `--------' 794 `-------' / \ 796 For unsuccessful KeySync attempts, messages 1-5 are the same as in a 797 successful attempt (see above), but once the Trustwords are shown, 798 events are as follows: 800 R6. The user compares the Trustwords of both devices. As the 801 Trustwords do not match, the user presses the 'Reject' button on 802 one of the Grouped Devices. 804 Note: The user may also press the 'Reject' button on the New 805 Device first. The end result is not affected by which 'Reject'- 806 Button is pressed first. However, the order and number of the 807 messages slightly changes. 809 R7. On receipt of the user's 'Reject', the 'Requester' device sends 810 a 'CommitReject' message. 812 Note: In the diagram, all messages marked "R7. CommitReject" 813 are a single message, but drawn separately in order to convey 814 that the message is sent to all devices in the Device Group. 816 The new device does not join the group and pEp KeySync is disabled on 817 it. As a consequence, there are no further attempts to join the 818 Device Group. 820 Once the CommitReject message is sent or received, respectively, the 821 new device cannot join the Device Group, and pEp KeySync is disabled 822 on the new device. As a result, there are no further attempts to 823 join a Device Group by the new device. 825 2.2.2.3. Discontinuation Case 827 ,-------. ,-. 828 |New | `-' ,--------. ,--------. 829 |device | /|\ |Active | |Passive | 830 |to join| | |device | |devices | 831 |group | / \ |in group| |in group| 832 `---+---' User `---+----' `---+----' 833 | | | | 834 | | | | 835 ,---------------------------------------------------------------!. 836 |Messages (1-5) are same as in the successful case (see above) |_\ 837 `-----------------------------------------------------------------' 838 | | | | 839 | | | | 840 | ,-----------------------------. | | 841 | |Handshake (user comparison | | | 842 | |of Trustwords) discontinued | | | 843 | `-----------------------------' | | 844 | ,------------------------------. | 845 | |User presses 'Cancel' button | | 846 | |on a device in group | | 847 | `------------------------------' | 848 | | C6. Cancel | | 849 | | - - - - - - - ->| | 850 | | | | 851 | C7. Rollback | | 852 |<---------------------------------| | 853 | | | | 854 | | | C7. Rollback | 855 | | |------------------>| 856 | | | | 857 ,----------!. | | | 858 |New device|_\ | | | 859 |(still not | | | | 860 |grouped) | | | | 861 |will try | | | | 862 |again | | | | 863 `------------' | | | 864 | | | | 865 ,---+---. User ,---+----. ,---+----. 866 |New | ,-. |Active | |Passive | 867 |device | `-' |device | |devices | 868 |to join| /|\ |in group| |in group| 869 |group | | `--------' `--------' 870 `-------' / \ 872 For discontinued (canceled) KeySync attempts, messages 1-5 are the 873 same as in a successful attempt (see above), but once the Trustwords 874 are shown, events are as follows: 876 C6. The user decides to discontinue the process and presses the 877 'Cancel' button on one of the Grouped Devices. 879 Note: The user may also press the 'Cancel' button on the New 880 Device first. The end result is not affected by which 'Cancel'- 881 Button is pressed first. However, the order and number of the 882 messages slightly changes. 884 C7. On receipt of the user's 'Cancel', the 'Requester' device sends 885 a rollback message. 887 Note: In the diagram, all messages marked "C7. Rollback" 888 are a single message, but drawn separately in order to convey 889 that the message is sent to all devices in the Device Group. 891 The new device does not join the Device Group. KeySync remains 892 enabled and joining a Device Group can start again. 894 2.2.3. Exchange Private Keys 896 [[ TODO ]] 898 2.2.4. Leave Device Group 900 [[ TODO ]] 902 2.2.5. Remove other Device from Device Group 904 [[ TODO ]] 906 2.3. Simplified Finite-State Machine 908 A simplified diagram of the implemented pEp KeySync finite-state 909 machine (FSM), which does not contain the transitions that occur when 910 pressing the 'Cancel' or 'Reject' buttons, can be found at: 911 https://pep.foundation/dev/repos/internet-drafts/raw- 912 file/tip/misc/figures/sync/sync_fsm_simplified.svg 914 3. Reference Implementation 916 [[ Note: This description of the FSM implementation is Work-In- 917 Progress. For now it is supposed to be sufficient for the reader to 918 understand the general functionality of the FSM, and thus lacking 919 certain details. The authors intend to enhance and refine it in 920 later revisions of this document. ]] 922 3.1. Full Finite-State Machine 924 A full diagram of the implemented pEp KeySync FSM can be found at the 925 following URL: 927 https://pep.foundation/dev/repos/internet-drafts/raw- 928 file/tip/misc/figures/sync/sync_fsm_full.svg 930 3.1.1. States 932 3.1.1.1. InitState 934 On initialization, the FSM enters InitState, which evaluates and 935 determines a device's group status. If the device is detected to 936 belong to a Device Group, the FSM transitions to state Grouped. 937 Otherwise, the FSM transitions to state Sole (cf. Section 3.1.2.1). 939 Please find more information in the following code excerpt: 941 state InitState { 942 on Init { 943 if deviceGrouped 944 go Grouped; 945 go Sole; 946 } 947 } 949 3.1.1.2. Sole 951 This is the default state for an ungrouped device. On 952 initialization, a challenge TID is created and sent out inside a 953 Beacon message. It waits also for Beacons from other devices. Upon 954 receipt of a Beacon message from another device, the received 955 challenge TID is compared with the own challenge. The device with 956 the lower challenge TID becomes 'Requester', the one with higher 957 challenge TID becomes 'Offerer'. 959 If determined to be 'Requester', a NegotiationRequest message is 960 sent. 962 The device determined as 'Offerer' receives the NegotiationRequest 963 message, sends a NegotiationOpen message as response and the FSM 964 transitions to state HandshakingOfferer. 966 On receipt of the NegotiationOpen message, the 'Requester' FSM 967 proceeds in one of two ways. If the NegotiationOpen message comes 968 from a Sole 'Offerer' Device, the FSM transitions to state 969 HandshakingRequester. If the NegotiationOpen message comes from a 970 Grouped Device, the FSM transitions to state HandshakingToJoin. 972 Please find more information in the following code excerpt: 974 state Sole timeout=off { 975 on Init { 976 do newChallengeAndNegotiationBase; 977 do showBeingSole; 978 send Beacon; 979 } 981 on KeyGen { 982 send Beacon; 983 } 985 on CannotDecrypt { // cry baby 986 send Beacon; 987 } 989 on Beacon { 990 if sameChallenge { 991 // this is our own Beacon; ignore 992 } 993 else { 994 if weAreOfferer { 995 do useOwnChallenge; 996 send Beacon; 997 } 998 else /* we are requester */ { 999 do openNegotiation; 1000 do tellWeAreNotGrouped; 1001 // requester is sending NegotiationRequest 1002 send NegotiationRequest; 1003 do useOwnChallenge; 1004 } 1005 } 1006 } 1007 on NegotiationRequest { 1008 if sameChallenge { // challenge accepted 1009 if sameNegotiation { 1010 // this is our own NegotiationRequest; ignore 1011 } 1012 else { 1013 do storeNegotiation; 1014 // offerer is accepting 1015 // by confirming NegotiationOpen 1016 send NegotiationOpen; 1017 if partnerIsGrouped 1018 go HandshakingToJoin; 1019 else 1020 go HandshakingOfferer; 1021 } 1022 } 1023 } 1025 on NegotiationOpen if sameNegotiationAndPartner { 1026 // requester is receiving NegotiationOpen 1027 do storeNegotiation; 1028 go HandshakingRequester; 1029 } 1030 } 1032 3.1.1.3. HandshakingOfferer 1034 This state is entered by the 'Offerer' device only. The FSM waits 1035 for the user to compare the Trustwords and to press either of the 1036 following buttons (on the 'Offerer' device): 1038 o Accept: A CommitAcceptOfferer message is sent and the FSM 1039 transitions to state HandshakingPhase1Offerer 1041 o Reject: A CommitReject message is sent, pEp KeySync is disabled, 1042 and the FSM transitions to state End 1044 o Cancel: A Rollback message is sent and the FSM transitions to 1045 state Sole 1047 If the 'Accept' button was pressed on the 'Requester' device, a 1048 CommitAcceptRequester message is received and the FSM transitions to 1049 state HandshakingPhase2Offerer. 1051 If the 'Reject' button was pressed on the 'Requester' device, a 1052 CommitReject message is received. pEp KeySync is disabled and the FSM 1053 transitions to state End. 1055 If the 'Cancel' button was pressed on the 'Requester' device, a 1056 Rollback message is received and the FSM transitions to state Sole. 1058 Please find more information in the following code excerpt: 1060 // handshaking without existing Device group 1061 state HandshakingOfferer timeout=600 { 1062 on Init 1063 do showSoleHandshake; 1065 // Cancel is Rollback 1066 on Cancel { 1067 send Rollback; 1068 go Sole; 1069 } 1071 on Rollback if sameNegotiationAndPartner 1072 go Sole; 1074 // Reject is CommitReject 1075 on Reject { 1076 send CommitReject; 1077 do disable; 1078 go End; 1079 } 1081 on CommitReject if sameNegotiationAndPartner { 1082 do disable; 1083 go End; 1084 } 1086 // Accept means init Phase1Commit 1087 on Accept { 1088 do trustThisKey; 1089 send CommitAcceptOfferer; 1090 go HandshakingPhase1Offerer; 1091 } 1093 // got a CommitAccept from requester 1094 on CommitAcceptRequester if sameNegotiationAndPartner 1095 go HandshakingPhase2Offerer; 1096 } 1098 3.1.1.4. HandshakingRequester 1100 This state is similar to the HandshakingOfferer (cf. 1101 Section 3.1.1.3), but with swapped roles. 1103 This state is entered by the 'Requester' device only. The FSM waits 1104 for the user to compare the Trustwords and to press either of the 1105 following buttons (on the 'Requester' device): 1107 o Accept: A CommitAcceptOfferer message is sent and the FSM 1108 transitions to state HandshakingPhase1Requester 1110 o Reject: A CommitReject message is sent, pEp KeySync is disabled, 1111 and the FSM transitions to state End 1113 o Cancel: A Rollback message is sent and the FSM transitions to 1114 state Sole 1116 If the 'Accept' button was pressed on the 'Offerer' device, a 1117 CommitAcceptOfferer message is received and the FSM transitions to 1118 state HandshakingPhase2Requester. 1120 If the 'Reject' button was pressed on the 'Offerer' device, a 1121 CommitReject message is received. pEp KeySync is disabled and the FSM 1122 transitions to state End. 1124 If the 'Cancel' button was pressed on the 'Offerer' device, a 1125 Rollback message is received and the FSM transitions to state Sole. 1127 Please find more information in the following code excerpt: 1129 state HandshakingRequester timeout=600 { 1130 on Init 1131 do showSoleHandshake; 1133 // Cancel is Rollback 1134 on Cancel { 1135 send Rollback; 1136 go Sole; 1137 } 1139 on Rollback if sameNegotiationAndPartner 1140 go Sole; 1142 // Reject is CommitReject 1143 on Reject { 1144 send CommitReject; 1145 do disable; 1146 go End; 1147 } 1149 on CommitReject if sameNegotiationAndPartner { 1150 do disable; 1151 go End; 1152 } 1154 // Accept means init Phase1Commit 1155 on Accept { 1156 do trustThisKey; 1157 send CommitAcceptRequester; 1158 go HandshakingPhase1Requester; 1159 } 1161 // got a CommitAccept from offerer 1162 on CommitAcceptOfferer if sameNegotiationAndPartner 1163 go HandshakingPhase2Requester; 1164 } 1166 state HandshakingPhase1Offerer { 1167 on Rollback if sameNegotiationAndPartner { 1168 do untrustThisKey; 1169 go Sole; 1170 } 1172 on CommitReject if sameNegotiationAndPartner { 1173 do untrustThisKey; 1174 do disable; 1175 go End; 1176 } 1178 on CommitAcceptRequester if sameNegotiationAndPartner { 1179 go FormingGroupOfferer; 1180 } 1181 } 1183 3.1.1.5. HandshakingPhase1Offerer 1185 This state is entered by the 'Offerer' device only. The FSM waits 1186 for the user to finish the handshake on the 'Requester' device (i.e. 1187 compare the Trustwords and press either of the buttons on the 1188 'Requester' device): 1190 If the 'Accept' button was pressed on the 'Requester' device, a 1191 CommitAcceptRequester message is received and the FSM transitions to 1192 state FormingGroupOfferer. 1194 If the 'Reject' button was pressed on the 'Requester' device, a 1195 CommitReject message is received. pEp KeySync is disabled and the FSM 1196 transitions to state End. 1198 If the 'Cancel' button was pressed on the 'Requester' device, a 1199 Rollback message is received and the FSM transitions to state Sole. 1201 Please find more information in the following code excerpt: 1203 state HandshakingPhase1Offerer { 1204 on Rollback if sameNegotiationAndPartner { 1205 do untrustThisKey; 1206 go Sole; 1207 } 1209 on CommitReject if sameNegotiationAndPartner { 1210 do untrustThisKey; 1211 do disable; 1212 go End; 1213 } 1215 on CommitAcceptRequester if sameNegotiationAndPartner { 1216 go FormingGroupOfferer; 1217 } 1218 } 1220 3.1.1.6. HandshakingPhase1Requester 1222 This state is similar to the HandshakingPhase1Offerer (cf. 1223 Section 3.1.1.5), but with swapped roles. 1225 This state is entered by the 'Requester' device only. The FSM waits 1226 for the user to finish the handshake on the 'Offerer' device (i.e. 1227 compare the Trustwords and press either of the buttons on the 1228 'Offerer' device): 1230 If the 'Accept' button was pressed on the 'Offerer' device, a 1231 CommitAcceptRequester message is received and the FSM transitions to 1232 state FormingGroupOfferer. 1234 If the 'Reject' button was pressed on the 'Offerer' device, a 1235 CommitReject message is received. pEp KeySync is disabled and the FSM 1236 transitions to state End. 1238 If the 'Cancel' button was pressed on the 'Offerer' device, a 1239 Rollback message is received and the FSM transitions to state Sole. 1241 Please find more information in the following code excerpt: 1243 state HandshakingPhase1Requester { 1244 on Rollback if sameNegotiationAndPartner { 1245 do untrustThisKey; 1246 go Sole; 1247 } 1249 on CommitReject if sameNegotiationAndPartner { 1250 do untrustThisKey; 1251 do disable; 1252 go End; 1253 } 1254 on CommitAcceptOfferer if sameNegotiationAndPartner { 1255 go FormingGroupRequester; 1256 } 1257 } 1259 3.1.1.7. HandshakingPhase2Offerer 1261 This state is entered by the 'Offerer' device only. The FSM waits 1262 for the user to compare the Trustwords and to press either of the 1263 following buttons (on the 'Offerer' device): 1265 o Accept: The key used in the handshake is marked 'trusted', a 1266 CommitAcceptOfferer message is sent and the FSM transitions to 1267 state FormingGroupOfferer 1269 o Reject: A CommitReject message is sent, pEp KeySync is disabled, 1270 and the FSM transitions to state End 1272 o Cancel: A Rollback message is sent and the FSM transitions to 1273 state Sole 1275 Please find more information in the following code excerpt: 1277 state HandshakingPhase2Offerer { 1278 on Cancel { 1279 send Rollback; 1280 go Sole; 1281 } 1283 on Reject { 1284 send CommitReject; 1285 do disable; 1286 go End; 1287 } 1289 on Accept { 1290 send CommitAcceptOfferer; 1291 do trustThisKey; 1292 go FormingGroupOfferer; 1293 } 1294 } 1296 3.1.1.8. HandshakingPhase2Requester 1298 This state is similar to the HandshakingPhase2Offerer (cf. 1299 Section 3.1.1.7), but with swapped roles. 1301 This state is entered by the 'Requester' device only. The FSM waits 1302 for the user to compare the Trustwords and to press either of the 1303 following buttons (on the 'Requester' device): 1305 o Accept: The key used in the handshake is marked 'trusted', a 1306 CommitAcceptOfferer message is sent and the FSM transitions to 1307 state FormingGroupRequester 1309 o Reject: A CommitReject message is sent, pEp KeySync is disabled, 1310 and the FSM transitions to state End 1312 o Cancel: A Rollback message is sent and the FSM transitions to 1313 state Sole 1315 Please find more information in the following code excerpt: 1317 state HandshakingPhase2Requester { 1318 on Cancel { 1319 send Rollback; 1320 go Sole; 1321 } 1323 on Reject { 1324 send CommitReject; 1325 do disable; 1326 go End; 1327 } 1329 on Accept { 1330 send CommitAcceptRequester; 1331 do trustThisKey; 1332 go FormingGroupRequester; 1333 } 1334 } 1336 3.1.1.9. FormingGroupOfferer 1338 This state is entered by the 'Offerer' device only. The FSM sends a 1339 OwnKeysOfferer along with its own keys, and waits to receive the keys 1340 from the 'Requester' device. Once received, the 'Requester' keys are 1341 saved and marked as Default Keys. The Device Group is created and 1342 the FSM transitions to state Grouped. 1344 Please find more information in the following code excerpt: 1346 state FormingGroupOfferer { 1347 on Init { 1348 do prepareOwnKeys; 1349 send OwnKeysOfferer; // we're not grouped yet, 1350 // this is our own keys 1351 } 1353 on OwnKeysRequester { 1354 do saveGroupKeys; 1355 do receivedKeysAreDefaultKeys; 1356 do showGroupCreated; 1357 go Grouped; 1358 } 1359 } 1361 3.1.1.10. FormingGroupRequester 1363 This state is entered by the 'Requester' device only. The FSM sends 1364 a OwnKeysRequester along with its own keys, and waits to receive the 1365 keys from the 'Offerer' device. Once received, the 'Offerer' keys 1366 are saved. The own keys are marked as Default Keys. The Device 1367 Group is created and the FSM transitions to state Grouped. 1369 Please find more information in the following code excerpt: 1371 state FormingGroupRequester { 1372 on Init { 1373 do prepareOwnKeys; 1374 send OwnKeysRequester; // we're not grouped yet, 1375 // this is our own keys 1376 } 1378 on OwnKeysOfferer { 1379 do saveGroupKeys; 1380 do ownKeysAreDefaultKeys; 1381 do showGroupCreated; 1382 go Grouped; 1383 } 1384 } 1386 3.1.1.11. Grouped 1388 This is the default state for any grouped device. The device also 1389 waits for Beacons from other devices that are not yet part of the 1390 Device Group. 1392 Upon receipt of a Beacon message from Sole Device, the device sends a 1393 NegotiationRequest message and waits for the NegotiationOpen message. 1395 On receipt of the NegotiationOpen message from the Sole Device the 1396 FSM of the 'Requester' transitions to state HandshakingGrouped. 1398 In this state, various other events are also processed, which do not 1399 result in a transition to another state. 1401 Please find more information in the following code excerpt: 1403 state Grouped timeout=off { 1404 on Init { 1405 do newChallengeAndNegotiationBase; 1406 do showBeingInGroup; 1407 } 1409 on GroupKeys 1410 do saveGroupKeys; 1412 on KeyGen { 1413 do prepareOwnKeys; 1414 send GroupKeys; 1415 } 1417 on Beacon { 1418 do openNegotiation; 1419 do tellWeAreGrouped; 1420 send NegotiationRequest; 1421 do useOwnChallenge; 1422 } 1424 on NegotiationOpen if sameNegotiationAndPartner { 1425 do storeNegotiation; 1426 go HandshakingGrouped; 1427 } 1429 on GroupTrustThisKey 1430 do trustThisKey; 1431 } 1433 3.1.1.12. HandshakingToJoin 1435 This state is entered by a new device only, i.e. a device that is not 1436 yet part of a Device Group. 1438 In this state the FSM waits for the user to compare the Trustwords 1439 and to press either of the following buttons (on the new device): 1441 o Accept: A CommitAccept message is sent and the FSM transitions to 1442 state HandshakingToJoinPhase1 1444 o Reject: A CommitReject message is sent, pEp KeySync is disabled 1445 (on the new device), and the FSM transitions to state End 1447 o Cancel: A Rollback message is sent and the FSM transitions to 1448 state Sole 1450 If the 'Accept' button was pressed on a grouped device, a 1451 CommitAcceptForGroup message is received and the FSM transitions to 1452 state HandshakingToJoinPhase2 1454 If the 'Reject' button was pressed on a grouped device, a 1455 CommitReject message is received. pEp KeySync is disabled (on the new 1456 device) and the FSM transitions to state End. 1458 If the 'Cancel' button was pressed on the 'Requester' device, a 1459 Rollback message is received and the FSM transitions to state Sole. 1461 Please find more information in the following code excerpt: 1463 // sole device handshaking with group 1464 state HandshakingToJoin { 1465 on Init 1466 do showJoinGroupHandshake; 1468 // Cancel is Rollback 1469 on Cancel { 1470 send Rollback; 1471 go Sole; 1472 } 1474 on Rollback if sameNegotiationAndPartner 1475 go Sole; 1477 // Reject is CommitReject 1478 on Reject { 1479 send CommitReject; 1480 do disable; 1481 go End; 1482 } 1484 on CommitAcceptForGroup if sameNegotiationAndPartner 1485 go HandshakingToJoinPhase2; 1487 on CommitReject if sameNegotiationAndPartner { 1488 do disable; 1489 go End; 1490 } 1492 // Accept is Phase1Commit 1493 on Accept { 1494 do trustThisKey; 1495 send CommitAccept; 1496 go HandshakingToJoinPhase1; 1497 } 1498 } 1500 3.1.1.13. HandshakingToJoinPhase1 1502 This state is entered by a new device only, i.e. a device that is not 1503 yet part of a Device Group. The FSM waits for the user to finish the 1504 handshake on a grouped device (i.e. compare the Trustwords and press 1505 either of the buttons on a grouped device): 1507 If the 'Accept' button was pressed on a grouped device, a 1508 CommitAcceptForGroup message is received and the FSM transitions to 1509 state JoiningGroup. 1511 If the 'Reject' button was pressed on a grouped device, a 1512 CommitReject message is received. pEp KeySync is disabled (on the new 1513 device) and the FSM transitions to state End. 1515 If the 'Cancel' button was pressed on the 'Requester' device, a 1516 Rollback message is received and the FSM transitions to state Sole. 1518 Please find more information in the following code excerpt: 1520 state HandshakingToJoinPhase1 { 1521 on Rollback if sameNegotiationAndPartner 1522 go Sole; 1524 on CommitReject if sameNegotiationAndPartner { 1525 do disable; 1526 go End; 1527 } 1529 on CommitAcceptForGroup if sameNegotiationAndPartner 1530 go JoiningGroup; 1531 } 1533 3.1.1.14. HandshakingToJoinPhase2 1535 This state is entered by a new device only, i.e. a device that is not 1536 yet part of a Device Group. 1538 In this state the FSM waits for the user to compare the Trustwords 1539 and to press either of the following buttons (on the new device): 1541 o Accept: A CommitAccept message is sent and the FSM transitions to 1542 state JoiningGroup 1544 o Reject: A CommitReject message is sent, pEp KeySync is disabled 1545 (on the new device), and the FSM transitions to state End 1547 o Cancel: A Rollback message is sent and the FSM transitions to 1548 state Sole 1550 Please find more information in the following code excerpt: 1552 state HandshakingToJoinPhase2 { 1553 on Cancel { 1554 send Rollback; 1555 go Sole; 1556 } 1558 on Reject { 1559 send CommitReject; 1560 do disable; 1561 go End; 1562 } 1564 on Accept { 1565 do trustThisKey; 1566 go JoiningGroup; 1567 } 1568 } 1570 3.1.1.15. JoiningGroup 1572 This state is entered by a new device only, i.e. a device that is not 1573 yet part of a Device Group. 1575 The FSM waits to receive the keys from the active grouped device. 1576 Once received, these are saved and marked as default keys. Then it 1577 sends all keys to the grouped devices and the FSM transitions to 1578 state Grouped. 1580 Please find more information in the following code excerpt: 1582 state JoiningGroup { 1583 on GroupKeys { 1584 do saveGroupKeys; 1585 do receivedKeysAreDefaultKeys; 1586 do prepareOwnKeys; 1587 send GroupKeys; 1588 do showDeviceAdded; 1589 go Grouped; 1590 } 1591 } 1593 3.1.1.16. HandshakingGrouped 1595 This state is entered by grouped devices only, i.e., devices that are 1596 part of a Device Group. 1598 In this state the FSM waits for the user to compare the Trustwords 1599 and to press either of the following buttons (on any grouped device, 1600 which now becomes the 'Active' grouped device): 1602 o Accept: A CommitAcceptForGroup message is sent and the FSM 1603 transitions to state HandshakingGroupedPhase1 1605 o Reject: A CommitReject message is sent and the FSM transitions to 1606 state Grouped 1608 o Cancel: A Rollback message is sent and the FSM transitions to 1609 state Grouped 1611 If the 'Accept' button was pressed on the new device, a CommitAccept 1612 message is received and the FSM transitions to state 1613 HandshakingPhase2 1615 If the 'Reject' button was pressed on the new device, a CommitReject 1616 message is received and the FSM transitions to state Grouped. 1618 If the 'Cancel' button was pressed on the new device, a Rollback 1619 message is received and the FSM transitions to state Grouped. 1621 In this state also a various other events are processed, which do not 1622 result in a transition to another state. 1624 Please find more information in the following code excerpt: 1626 state HandshakingGrouped { 1627 on Init 1628 do showGroupedHandshake; 1630 // Cancel is Rollback 1631 on Cancel { 1632 send Rollback; 1633 go Grouped; 1634 } 1636 on Rollback if sameNegotiationAndPartner 1637 go Grouped; 1639 // Reject is CommitReject 1640 on Reject { 1641 send CommitReject; 1642 go Grouped; 1643 } 1645 on CommitReject if sameNegotiationAndPartner 1646 go Grouped; 1648 // Accept is Phase1Commit 1649 on Accept { 1650 do trustThisKey; 1651 send GroupTrustThisKey; 1652 send CommitAcceptForGroup; 1653 go HandshakingGroupedPhase1; 1654 } 1656 on CommitAccept if sameNegotiationAndPartner 1657 go HandshakingGroupedPhase2; 1659 on GroupTrustThisKey { 1660 do hideHandshakeDialog; 1661 do trustThisKey; 1662 } 1664 on GroupKeys 1665 do saveGroupKeys; 1666 } 1668 3.1.1.17. HandshakingGroupedPhase1 1670 This state is entered by grouped devices only, i.e., devices that are 1671 part of a Device Group. The FSM waits for the user to finish the 1672 handshake on the new device (i.e., compare the Trustwords and press 1673 either of the buttons on the new device): 1675 If the 'Accept' button was pressed on the new device, a CommitAccept 1676 message is received and the FSM transitions to state Grouped 1678 If the 'Reject' button was pressed on the new device, a CommitReject 1679 message is received and the FSM transitions to state Grouped. 1681 If the 'Cancel' button was pressed on the new device, a Rollback 1682 message is received and the FSM transitions to state Grouped. 1684 In this state also a various other events are processed, which do not 1685 result in a transition to another state. 1687 Please find more information in the following code excerpt: 1689 state HandshakingGroupedPhase1 { 1690 on Rollback if sameNegotiationAndPartner 1691 go Grouped; 1693 on CommitReject if sameNegotiationAndPartner 1694 go Grouped; 1696 on CommitAccept if sameNegotiationAndPartner { 1697 do prepareOwnKeys; 1698 send GroupKeys; 1699 go Grouped; 1700 } 1702 on GroupTrustThisKey { 1703 do trustThisKey; 1704 } 1706 on GroupKeys 1707 do saveGroupKeys; 1708 } 1710 3.1.1.18. HandshakingGroupedPhase2 1712 This state is entered by grouped devices only, i.e. devices that are 1713 part of a Device Group. 1715 In this state the FSM waits for the user to compare the Trustwords 1716 and to press either of the following buttons (on any grouped device, 1717 which now becomes the 'Active' grouped device): 1719 o Accept: A CommitAcceptForGroup message is sent and the FSM 1720 transitions to state HandshakingGroupedPhase1 1722 o Reject: A CommitReject message is sent and the FSM transitions to 1723 state Grouped 1725 o Cancel: A Rollback message is sent and the FSM transitions to 1726 state Grouped 1728 In this state also various other events are processed, which do not 1729 result in a transition to another state, but in the execution of 1730 certain actions (e.g., saveGroupKeys). 1732 Please find more information in the following code excerpt: 1734 state HandshakingGroupedPhase2 { 1735 on Cancel { 1736 send Rollback; 1737 go Grouped; 1738 } 1740 on Reject { 1741 send CommitReject; 1742 go Grouped; 1743 } 1745 on Accept { 1746 do trustThisKey; 1747 send GroupTrustThisKey; 1748 do prepareOwnKeys; 1749 send GroupKeys; 1750 go Grouped; 1751 } 1753 on GroupTrustThisKey { 1754 do trustThisKey; 1755 } 1757 on GroupKeys 1758 do saveGroupKeys; 1759 } 1761 3.1.2. Actions 1763 Actions describe internal FSM functions, and fall into two general 1764 types. The first action type is a conditional 'if' statement, which 1765 direct the transitional states within the FSM (cf. 'if' statements; 1766 e.g., 'if deviceGrouped'). The second action type directs state 1767 changes which KeySync implementers can use to drive UI functionality, 1768 such as 'do' statements that trigger dialog box changes (cf 'do' 1769 statements; e.g., 'do hideHandshakeDialog'). 1771 3.1.2.1. deviceGrouped (conditional) 1773 The 'deviceGrouped' conditional evaluates true if a device is already 1774 in a Device Group. This boolean value is available and eventually 1775 altered locally on every KeySync-enabled device. For example, in the 1776 reference implementation, this boolean value is stored in a local SQL 1777 database. 1779 The 'deviceGrouped' value is what the KeySync FSM uses upon 1780 initialization to determine whether a device should transition to 1781 state Sole or state Grouped. 1783 The following code excerpt shows where this action is called: 1785 state InitState { 1786 on Init { 1787 if deviceGrouped 1788 go Grouped; 1789 go Sole; 1790 } 1791 } 1793 3.1.2.2. disable 1795 The 'disable' function may be called in an number of scenarios. For 1796 example, a user has rejected a pEp Handshake on either device 1797 involved in a pEp Handshake. At this time, in all cases, invoking 1798 the 'disable' function results in the FSM transitioning to state End, 1799 which disables the KeySync feature. 1801 The following code excerpt shows where this action is called: 1803 // handshaking without existing Device group 1804 state HandshakingOfferer timeout=600 { 1805 on Init 1806 do showSoleHandshake; 1808 // Cancel is Rollback 1809 on Cancel { 1810 send Rollback; 1811 go Sole; 1812 } 1813 on Rollback if sameNegotiationAndPartner 1814 go Sole; 1816 // Reject is CommitReject 1817 on Reject { 1818 send CommitReject; 1819 do disable; 1820 go End; 1821 } 1823 on CommitReject if sameNegotiationAndPartner { 1824 do disable; 1825 go End; 1826 } 1828 [...] 1830 // handshaking without existing Device group 1831 state HandshakingRequester timeout=600 { 1832 on Init 1833 do showSoleHandshake; 1835 // Cancel is Rollback 1836 on Cancel { 1837 send Rollback; 1838 go Sole; 1839 } 1841 on Rollback if sameNegotiationAndPartner 1842 go Sole; 1844 // Reject is CommitReject 1845 on Reject { 1846 send CommitReject; 1847 do disable; 1848 go End; 1849 } 1851 on CommitReject if sameNegotiationAndPartner { 1852 do disable; 1853 go End; 1854 } 1856 [...] 1858 state HandshakingPhase1Offerer { 1859 on Rollback if sameNegotiationAndPartner { 1860 do untrustThisKey; 1861 go Sole; 1862 } 1864 on CommitReject if sameNegotiationAndPartner { 1865 do untrustThisKey; 1866 do disable; 1867 go End; 1868 } 1870 [...] 1872 state HandshakingPhase1Requester { 1873 on Rollback if sameNegotiationAndPartner { 1874 do untrustThisKey; 1875 go Sole; 1876 } 1878 on CommitReject if sameNegotiationAndPartner { 1879 do untrustThisKey; 1880 do disable; 1881 go End; 1882 } 1884 [...] 1886 state HandshakingToJoinPhase1 { 1887 on Rollback if sameNegotiationAndPartner 1888 go Sole; 1890 on CommitReject if sameNegotiationAndPartner { 1891 do disable; 1892 go End; 1893 } 1895 on CommitAcceptForGroup if sameNegotiationAndPartner 1896 go JoiningGroup; 1897 } 1899 [...] 1901 [[ TODO: More occurrences exist; perhaps it's better 1902 to move to appendix? ]] 1904 3.1.2.3. hideHandshakeDialog 1906 The 'hideHandshakeDialog' function is invoked when a 1907 GroupTrustThisKey message is received by a device which is in the 1908 Grouped state and negotiating the addition of a new device, but 1909 another device within the Device Group has already confirmed the 1910 Trustwords dialog to accept the new device. 1912 This action is intended to send an event to the 'Passive' grouped 1913 devices that forces the closure of any unnecessary dialog boxes. 1915 The following code excerpt shows where this action is called: 1917 state HandshakingGrouped { 1918 on Init 1919 do showGroupedHandshake; 1921 // Cancel is Rollback 1922 on Cancel { 1923 send Rollback; 1924 go Grouped; 1925 } 1927 on Rollback if sameNegotiationAndPartner 1928 go Grouped; 1930 // Reject is CommitReject 1931 on Reject { 1932 send CommitReject; 1933 go Grouped; 1934 } 1936 on CommitReject if sameNegotiationAndPartner 1937 go Grouped; 1939 // Accept is Phase1Commit 1940 on Accept { 1941 do trustThisKey; 1942 send GroupTrustThisKey; 1943 send CommitAcceptForGroup; 1944 go HandshakingGroupedPhase1; 1945 } 1947 on CommitAccept if sameNegotiationAndPartner 1948 go HandshakingGroupedPhase2; 1950 on GroupTrustThisKey { 1951 do hideHandshakeDialog; 1952 do trustThisKey; 1953 } 1955 on GroupKeys 1956 do saveGroupKeys; 1957 } 1959 3.1.2.4. openNegotiation 1961 An 'openNegotiation' action is carried out either by a Sole Device in 1962 the 'Requester' role, or a Grouped device upon receipt of a Beacon 1963 message from another Sole device. Most importantly, this action 1964 ensures that the own TID and the challenge TID of the Sole Device get 1965 combined by the mathematical XOR function. In this way, a common TID 1966 exists which can be used by both devices a user wishes to pair. This 1967 TID is crucial in allowing the devices to recognize themselves in a 1968 particular pairing process, as multiple pairing process can occur 1969 simultaneously. 1971 The following code excerpt shows where this action is called: 1973 state Sole timeout=off { 1974 on Init { 1975 do newChallengeAndNegotiationBase; 1976 do showBeingSole; 1977 send Beacon; 1978 } 1980 on KeyGen { 1981 send Beacon; 1982 } 1984 on CannotDecrypt { // cry baby 1985 send Beacon; 1986 } 1988 on Beacon { 1989 if sameChallenge { 1990 // this is our own Beacon; ignore 1991 } 1992 else { 1993 if weAreOfferer { 1994 do useOwnChallenge; 1995 send Beacon; 1996 } 1997 else /* we are requester */ { 1998 do openNegotiation; 1999 do tellWeAreNotGrouped; 2000 // requester is sending NegotiationRequest 2001 send NegotiationRequest; 2002 do useOwnChallenge; 2003 } 2004 } 2006 [...] 2008 state Grouped timeout=off { 2009 on Init { 2010 do newChallengeAndNegotiationBase; 2011 do showBeingInGroup; 2013 } 2015 on GroupKeys 2016 do saveGroupKeys; 2018 on KeyGen { 2019 do prepareOwnKeys; 2020 send GroupKeys; 2021 } 2023 on Beacon { 2024 do openNegotiation; 2025 do tellWeAreGrouped; 2026 send NegotiationRequest; 2027 do useOwnChallenge; 2028 } 2030 3.1.2.5. ownKeysAreDefaultKeys 2032 [[ TODO ]] 2034 The following code excerpt shows where this action is called: 2036 state FormingGroupOfferer { 2037 on Init { 2038 do prepareOwnKeys; 2039 send OwnKeysOfferer; // we're not grouped yet, 2040 // this is our own keys 2041 } 2043 on OwnKeysRequester { 2044 do saveGroupKeys; 2045 do receivedKeysAreDefaultKeys; 2046 do showGroupCreated; 2047 go Grouped; 2048 } 2049 } 2051 state FormingGroupRequester { 2052 on Init { 2053 do prepareOwnKeys; 2054 send OwnKeysRequester; // we're not grouped yet, 2055 // this is our own keys 2056 } 2058 on OwnKeysOfferer { 2059 do saveGroupKeys; 2060 do ownKeysAreDefaultKeys; 2061 do showGroupCreated; 2062 go Grouped; 2063 } 2064 } 2066 3.1.2.6. newChallengeAndNegotiationBase 2068 [[ TODO ]] 2070 The following code excerpt shows where this action is called: 2072 state Sole timeout=off { 2073 on Init { 2074 do newChallengeAndNegotiationBase; 2075 do showBeingSole; 2076 send Beacon; 2077 } 2079 [...] 2081 state Grouped timeout=off { 2082 on Init { 2083 do newChallengeAndNegotiationBase; 2084 do showBeingInGroup; 2085 } 2087 3.1.2.7. partnerIsGrouped (conditional) 2089 [[ TODO ]] 2091 The following code excerpt shows where this action is called: 2093 state Sole timeout=off { 2095 [...] 2097 on NegotiationRequest { 2098 if sameChallenge { // challenge accepted 2099 if sameNegotiation { 2100 // this is our own NegotiationRequest; ignore 2101 } 2102 else { 2103 do storeNegotiation; 2104 // offerer is accepting by confirming 2105 // NegotiationOpen 2106 send NegotiationOpen; 2107 if partnerIsGrouped 2108 go HandshakingToJoin; 2109 else 2110 go HandshakingOfferer; 2111 } 2112 } 2113 } 2115 3.1.2.8. prepareOwnKeys 2117 [[ TODO ]] 2119 The following code excerpt shows where this action is called: 2121 state FormingGroupOfferer { 2122 on Init { 2123 do prepareOwnKeys; 2124 send OwnKeysOfferer; // we're not grouped yet, 2125 // this is our own keys 2126 } 2128 [...] 2130 [...] 2132 state FormingGroupRequester { 2133 on Init { 2134 do prepareOwnKeys; 2135 send OwnKeysRequester; // we're not grouped yet, 2136 // this is our own keys 2137 } 2139 [...] 2141 [...] 2143 state Grouped timeout=off { 2145 [...] 2147 on KeyGen { 2148 do prepareOwnKeys; 2149 send GroupKeys; 2150 } 2152 [...] 2154 [...] 2156 3.1.2.9. receivedKeysAreDefaultKeys 2158 The 'receivedKeysAreDefaultKeys' action tells the pEp implementer to 2159 set the keys just received as the default for outgoing 2160 communications. 2162 [[ TODO: Clear out, in which cases which keys are used as default 2163 keys. ]] 2165 The following code excerpt shows where this action is called: 2167 state FormingGroupOfferer { 2168 on Init { 2169 do prepareOwnKeys; 2170 send OwnKeysOfferer; // we're not grouped yet, 2171 // this is our own keys 2172 } 2174 on OwnKeysRequester { 2175 do saveGroupKeys; 2176 do receivedKeysAreDefaultKeys; 2177 do showGroupCreated; 2178 go Grouped; 2179 } 2180 } 2182 [...] 2184 state JoiningGroup { 2185 on GroupKeys { 2186 do saveGroupKeys; 2187 do receivedKeysAreDefaultKeys; 2188 do prepareOwnKeys; 2189 send GroupKeys; 2190 do showDeviceAdded; 2191 go Grouped; 2192 } 2193 } 2195 [...] 2197 3.1.2.10. sameChallenge (conditional) 2199 [[ TODO ]] 2201 The following code excerpt shows where this action is called: 2203 state Sole timeout=off { 2204 on Init { 2205 do newChallengeAndNegotiationBase; 2206 do showBeingSole; 2207 send Beacon; 2208 } 2209 on KeyGen { 2210 send Beacon; 2211 } 2213 on CannotDecrypt { // cry baby 2214 send Beacon; 2215 } 2217 on Beacon { 2218 if sameChallenge { 2219 // this is our own Beacon; ignore 2220 } 2221 else { 2222 if weAreOfferer { 2223 do useOwnChallenge; 2224 send Beacon; 2225 } 2226 else /* we are requester */ { 2227 do openNegotiation; 2228 do tellWeAreNotGrouped; 2229 // requester is sending NegotiationRequest 2230 send NegotiationRequest; 2231 do useOwnChallenge; 2232 } 2233 } 2235 on NegotiationRequest { 2236 if sameChallenge { // challenge accepted 2237 if sameNegotiation { 2238 // this is our own NegotiationRequest; ignore 2239 } 2240 else { 2241 do storeNegotiation; 2242 // offerer is accepting by confirming 2243 // NegotiationOpen 2244 send NegotiationOpen; 2245 if partnerIsGrouped 2246 go HandshakingToJoin; 2247 else 2248 go HandshakingOfferer; 2249 } 2250 } 2251 } 2253 [...] 2255 3.1.2.11. sameNegotiation (conditional) 2257 The 'sameNegotiation' action evaluates true if the FSM finds a 2258 NegotiationRequest message that a Sole Device sent out is determined 2259 to be self-originating. The Transaction ID (TID) will be an exact 2260 match upon comparison, and the NegotiationRequest will be ignored as 2261 a result. 2263 The following code excerpt shows where this action is called: 2265 state Sole timeout=off { 2267 [...] 2269 on NegotiationRequest { 2270 if sameChallenge { // challenge accepted 2271 if sameNegotiation { 2272 // this is our own NegotiationRequest; ignore 2273 } 2274 else { 2275 do storeNegotiation; 2276 // offerer is accepting by confirming 2277 // NegotiationOpen 2278 send NegotiationOpen; 2279 if partnerIsGrouped 2280 go HandshakingToJoin; 2281 else 2282 go HandshakingOfferer; 2283 } 2284 } 2285 } 2287 3.1.2.12. sameNegotiationAndPartner (conditional) 2289 [[ TODO ]] 2291 The following code excerpt shows where this action is called: 2293 3.1.2.13. saveGroupKeys 2295 [[ TODO ]] 2297 The following code excerpt shows where this action is called: 2299 3.1.2.14. showBeingInGroup 2301 The 'showBeingInGroup' action (in state Grouped) is used to notify a 2302 pEp implementer that a device is Grouped and to prepare the necessary 2303 structures to potentially carry out KeySync (in case any other device 2304 exists and a Beacon from a Sole Device appears at some point). 2306 The following code excerpt shows where this action is called: 2308 state Grouped timeout=off { 2309 on Init { 2310 do newChallengeAndNegotiationBase; 2311 do showBeingInGroup; 2312 } 2314 3.1.2.15. showBeingSole 2316 The 'showBeingSole' action (in state Sole) is used to notify a pEp 2317 implementer that a device is ungrouped (or: sole) and to prepare the 2318 necessary structures to potentially carry out KeySync (in case any 2319 other device exists and a negotiation starts). 2321 The following code excerpt shows where this action is called: 2323 state Sole timeout=off { 2324 on Init { 2325 do newChallengeAndNegotiationBase; 2326 do showBeingSole; 2327 send Beacon; 2328 } 2330 3.1.2.16. showDeviceAdded 2332 The 'showDeviceAdded' action is used to notify a pEp implementer that 2333 a Sole Device was added to an already existing Device Group. 2335 The following code excerpt shows where this action is called: 2337 state JoiningGroup { 2338 on GroupKeys { 2339 do saveGroupKeys; 2340 do receivedKeysAreDefaultKeys; 2341 do prepareOwnKeys; 2342 send GroupKeys; 2343 do showDeviceAdded; 2344 go Grouped; 2345 } 2346 } 2348 3.1.2.17. showGroupCreated 2350 In both roles a Sole Device can assume (either as Requester or 2351 Offerer), this action 'showGroupCreated' ensures that the pEp 2352 implementer gets a notification that a new Device Group was formed 2353 (both devices coming from Sole state in their respective FSMs). 2355 The following code excerpt shows where this action is called: 2357 state FormingGroupOfferer { 2358 on Init { 2359 do prepareOwnKeys; 2360 send OwnKeysOfferer; // we're not grouped yet, 2361 // this is our own keys 2362 } 2364 on OwnKeysRequester { 2365 do saveGroupKeys; 2366 do receivedKeysAreDefaultKeys; 2367 do showGroupCreated; 2368 go Grouped; 2369 } 2370 } 2372 state FormingGroupRequester { 2373 on Init { 2374 do prepareOwnKeys; 2375 send OwnKeysRequester; // we're not grouped yet, 2376 // this is our own keys 2377 } 2379 on OwnKeysOfferer { 2380 do saveGroupKeys; 2381 do ownKeysAreDefaultKeys; 2382 do showGroupCreated; 2383 go Grouped; 2384 } 2385 } 2387 3.1.2.18. showGroupedHandshake 2389 The 'showGroupedHandshake' action notifies a pEp implementer to show 2390 a pEp Handshake on the own, already Grouped Device (which is thus in 2391 state Grouped). That means, the Handshake should be displayed in a 2392 way indicating there is another (yet) Sole Device willing to join the 2393 Device Group one is already a member of. 2395 The following code excerpt shows where this action is called: 2397 state HandshakingGrouped { 2398 on Init 2399 do showGroupedHandshake; 2401 3.1.2.19. showJoinGroupHandshake 2403 The 'showJoinGroupHandshake' action is used to notify pEp 2404 implementers to show a Handshake dialog when a Sole Device is to be 2405 grouped with an already existing Device Group, such that a user can 2406 'Accept', 'Cancel' or 'Reject' a group joining process. 2408 The following code excerpt shows where this action is called: 2410 // sole device handshaking with group 2411 state HandshakingToJoin { 2412 on Init 2413 do showJoinGroupHandshake; 2415 3.1.2.20. showSoleHandshake 2417 For either the role of the Requester or the Offerer, in case of two 2418 Sole Devices, 'showSoleHandshake' notifies a pEp implementer that a 2419 pEp Handshake dialog between the two devices in negotiation has to be 2420 shown (depending on the role this action is called from two different 2421 states; see code below), such that the user (on both Sole Devices in 2422 user-defined sequence) can either press 'Accept', 'Cancel' or 2423 'Reject' to decide on the group formation process. 2425 The following code excerpt shows where this action is called: 2427 // handshaking without existing Device group 2428 state HandshakingRequester timeout=600 { 2429 on Init 2430 do showSoleHandshake; 2432 [...] 2434 // handshaking without existing Device group 2435 state HandshakingOfferer timeout=600 { 2436 on Init 2437 do showSoleHandshake; 2439 3.1.2.21. storeNegotiation 2441 [[ TODO ]] 2443 The following code excerpt shows where this action is called: 2445 state Sole timeout=off { 2447 [...] 2449 on NegotiationRequest { 2450 if sameChallenge { // challenge accepted 2451 if sameNegotiation { 2452 // this is our own NegotiationRequest; ignore 2453 } 2454 else { 2455 do storeNegotiation; 2456 // offerer is accepting by confirming 2457 // NegotiationOpen 2458 send NegotiationOpen; 2459 if partnerIsGrouped 2460 go HandshakingToJoin; 2461 else 2462 go HandshakingOfferer; 2463 } 2464 } 2465 } 2467 on NegotiationOpen if sameNegotiationAndPartner { 2468 // requester is receiving NegotiationOpen 2469 do storeNegotiation; 2470 go HandshakingRequester; 2471 } 2473 [...] 2475 state Grouped timeout=off { 2477 [...] 2479 on NegotiationOpen if sameNegotiationAndPartner { 2480 do storeNegotiation; 2481 go HandshakingGrouped; 2482 } 2484 [...] 2486 } 2488 3.1.2.22. tellWeAreGrouped 2490 The 'tellWeAreGrouped' action is used in case a device is already is 2491 in state Grouped; it is used to modify KeySync state marking one is 2492 grouped. This plays a role in negotiation with another device being 2493 Sole, such it knows it is about to join an already existing Device 2494 Group. 2496 The following code excerpt shows where this action is called: 2498 state Grouped timeout=off { 2499 on Init { 2500 do newChallengeAndNegotiationBase; 2501 do showBeingInGroup; 2502 } 2504 on GroupKeys 2505 do saveGroupKeys; 2507 on KeyGen { 2508 do prepareOwnKeys; 2509 send GroupKeys; 2510 } 2512 on Beacon { 2513 do openNegotiation; 2514 do tellWeAreGrouped; 2515 send NegotiationRequest; 2516 do useOwnChallenge; 2517 } 2519 3.1.2.23. tellWeAreNotGrouped 2521 The 'tellWeAreNotGroupd' action is used by Sole Devices (thus in 2522 state Sole) which get into the role of being a Requester. This 2523 action modifies KeySync state such as to mark one is a Sole Device 2524 (and not already in a Device Group). That is, the other Sole Device 2525 (in Offerer role) will learn the negotiation is about to form a 2526 Device Group. 2528 The following code excerpt shows where this action is called: 2530 state Sole timeout=off { 2531 on Init { 2532 do newChallengeAndNegotiationBase; 2533 do showBeingSole; 2534 send Beacon; 2535 } 2537 on KeyGen { 2538 send Beacon; 2539 } 2541 on CannotDecrypt { // cry baby 2542 send Beacon; 2543 } 2545 on Beacon { 2546 if sameChallenge { 2547 // this is our own Beacon; ignore 2548 } 2549 else { 2550 if weAreOfferer { 2551 do useOwnChallenge; 2552 send Beacon; 2553 } 2554 else /* we are requester */ { 2555 do openNegotiation; 2556 do tellWeAreNotGrouped; 2557 // requester is sending NegotiationRequest 2558 send NegotiationRequest; 2559 do useOwnChallenge; 2560 } 2561 } 2562 } 2564 3.1.2.24. trustThisKey 2566 The 'trustThisKey' action is executed in all states a user can do 2567 'Accept' of the Handshake dialog. The pEp implementer is told to put 2568 trust on the public key received by the other device, which wants to 2569 get paired. This means, depending on the role or grouping status the 2570 own device is in, this key is candidate to be the new default key. 2571 (Note: The trust also extends to the private key part of the public 2572 key received at a later stage of the FSM - given the user does 2573 effectively 'Accept' on both devices; this trust can also be removed 2574 if a 'Reject' on the other device occurs, cf. Section 3.1.2.25.) 2576 The following code excerpt shows where this action is called: 2578 // handshaking without existing Device group 2579 state HandshakingOfferer timeout=600 { 2581 [...] 2583 // Accept means init Phase1Commit 2584 on Accept { 2585 do trustThisKey; 2586 send CommitAcceptOfferer; 2588 [...] 2590 // handshaking without existing Device group 2591 state HandshakingRequester timeout=600 { 2593 [...] 2595 // Accept means init Phase1Commit 2596 on Accept { 2597 do trustThisKey; 2598 send CommitAcceptRequester; 2599 go HandshakingPhase1Requester; 2600 } 2602 state HandshakingPhase2Offerer { 2604 [...] 2606 on Accept { 2607 send CommitAcceptOfferer; 2608 do trustThisKey; 2609 go FormingGroupOfferer; 2610 } 2611 } 2613 [...] 2615 state HandshakingPhase2Requester { 2617 [...] 2619 on Accept { 2620 send CommitAcceptRequester; 2621 do trustThisKey; 2622 go FormingGroupRequester; 2623 } 2624 } 2626 [...] 2628 state Grouped timeout=off { 2630 [...] 2632 on GroupTrustThisKey 2633 do trustThisKey; 2634 } 2636 [...] 2638 state HandshakingToJoin { 2640 [...] 2642 // Accept is Phase1Commit 2643 on Accept { 2644 do trustThisKey; 2645 send CommitAccept; 2647 [...] 2649 state HandshakingToJoinPhase2 { 2651 [...] 2653 on Accept { 2654 do trustThisKey; 2655 go JoiningGroup; 2656 } 2657 } 2659 [...] 2661 state HandshakingGrouped { 2663 [...] 2665 // Accept is Phase1Commit 2666 on Accept { 2667 do trustThisKey; 2668 send GroupTrustThisKey; 2669 send CommitAcceptForGroup; 2670 go HandshakingGroupedPhase1; 2671 } 2673 [...] 2674 on GroupTrustThisKey { 2675 do hideHandshakeDialog; 2676 do trustThisKey; 2677 } 2679 [...] 2681 state HandshakingGroupedPhase1 { 2683 [...] 2685 on GroupTrustThisKey { 2686 do trustThisKey; 2687 } 2689 [...] 2691 state HandshakingGroupedPhase2 { 2693 [...] 2695 on Accept { 2696 do trustThisKey; 2697 send GroupTrustThisKey; 2698 do prepareOwnKeys; 2699 send GroupKeys; 2700 go Grouped; 2701 } 2703 3.1.2.25. untrustThisKey 2705 If, after an own 'Accept', the other device returns a 'Reject' 2706 action, trust on the other device's public key is removed. The 2707 action 'untrustThisKey' ensures that the public key that has already 2708 been imported is untrusted (cf. Section 3.1.2.24). As a result, the 2709 public key, despite being imported, is never attached to messages 2710 sent to outside peers. 2712 The following code excerpt shows where this action is called: 2714 state HandshakingPhase1Offerer { 2715 on Rollback if sameNegotiationAndPartner { 2716 do untrustThisKey; 2717 go Sole; 2718 } 2720 on CommitReject if sameNegotiationAndPartner { 2721 do untrustThisKey; 2722 do disable; 2723 go End; 2724 } 2726 [...] 2728 state HandshakingPhase1Requester { 2729 on Rollback if sameNegotiationAndPartner { 2730 do untrustThisKey; 2731 go Sole; 2732 } 2734 on CommitReject if sameNegotiationAndPartner { 2735 do untrustThisKey; 2736 do disable; 2737 go End; 2738 } 2740 3.1.2.26. useOwnChallenge 2742 [[ TODO ]] 2744 The following code excerpt shows where this action is called: 2746 state Sole timeout=off { 2748 [...] 2750 on Beacon { 2751 if sameChallenge { 2752 // this is our own Beacon; ignore 2753 } 2754 else { 2755 if weAreOfferer { 2756 do useOwnChallenge; 2757 send Beacon; 2758 } 2759 else /* we are requester */ { 2760 do openNegotiation; 2761 do tellWeAreNotGrouped; 2762 // requester is sending NegotiationRequest 2763 send NegotiationRequest; 2764 do useOwnChallenge; 2765 } 2766 } 2768 [...] 2770 state Sole timeout=off { 2772 [...] 2774 on Beacon { 2775 if sameChallenge { 2776 // this is our own Beacon; ignore 2777 } 2778 else { 2779 if weAreOfferer { 2780 do useOwnChallenge; 2781 send Beacon; 2782 } 2783 else /* we are requester */ { 2784 do openNegotiation; 2785 do tellWeAreNotGrouped; 2786 // requester is sending NegotiationRequest 2787 send NegotiationRequest; 2788 do useOwnChallenge; 2789 } 2790 } 2792 3.2. Messages 2794 [[ TODO ]] 2796 3.2.1. Format 2798 [[ TODO ]] 2800 3.2.2. List of Messages Used in Finite-State Machine 2802 3.2.2.1. Beacon 2804 [[ TODO ]] 2806 Please find more information in the following code excerpt: 2808 message Beacon 2, type=broadcast, security=unencrypted { 2809 field TID challenge; 2810 auto Version version; 2811 } 2813 3.2.2.2. NegotiationRequest 2815 [[ TODO ]] 2817 Please find more information in the following code excerpt: 2819 message NegotiationRequest 3, security=untrusted { 2820 field TID challenge; 2821 auto Version version; 2822 field TID negotiation; 2823 field bool is_group; 2824 } 2826 3.2.2.3. NegotiationOpen 2828 [[ TODO ]] 2830 Please find more information in the following code excerpt: 2832 message NegotiationOpen 4, security=untrusted { 2833 auto Version version; 2834 field TID negotiation; 2835 } 2837 3.2.2.4. Rollback 2839 [[ TODO ]] 2841 Please find more information in the following code excerpt: 2843 message Rollback 5, security=untrusted { 2844 field TID negotiation; 2845 } 2847 3.2.2.5. CommitReject 2849 [[ TODO ]] 2851 Please find more information in the following code excerpt: 2853 message CommitReject 6, security=untrusted { 2854 field TID negotiation; 2855 } 2857 3.2.2.6. CommitAcceptOfferer 2859 [[ TODO ]] 2861 Please find more information in the following code excerpt: 2863 message CommitAcceptOfferer 7, security=untrusted { 2864 field TID negotiation; 2865 } 2867 3.2.2.7. CommitAcceptRequester 2869 [[ TODO ]] 2871 Please find more information in the following code excerpt: 2873 message CommitAcceptRequester 8, security=untrusted { 2874 field TID negotiation; 2875 } 2877 3.2.2.8. CommitAccept 2879 [[ TODO ]] 2881 Please find more information in the following code excerpt: 2883 message CommitAccept 9, security=untrusted { 2884 field TID negotiation; 2885 } 2887 3.2.2.9. CommitAcceptForGroup 2889 [[ TODO ]] 2891 Please find more information in the following code excerpt: 2893 message CommitAcceptForGroup 10, security=untrusted { 2894 field TID negotiation; 2895 } 2897 3.2.2.10. GroupTrustThisKey 2899 [[ TODO ]] 2901 Please find more information in the following code excerpt: 2903 // default: security=trusted only 2904 message GroupTrustThisKey 11 { 2905 field Hash key; 2906 } 2908 3.2.2.11. GroupKeys 2910 [[ TODO ]] 2912 Please find more information in the following code excerpt: 2914 // trust in future 2915 message GroupKeys 12, security=attach_own_keys { 2916 field IdentityList ownIdentities; 2917 } 2919 3.2.2.12. OwnKeysOfferer 2921 [[ TODO ]] 2923 Please find more information in the following code excerpt: 2925 message OwnKeysOfferer 13, security=attach_own_keys { 2926 field IdentityList ownIdentities; 2927 } 2929 3.2.2.13. OwnKeysRequester 2931 [[ TODO ]] 2933 Please find more information in the following code excerpt: 2935 message OwnKeysRequester 14, security=attach_own_keys { 2936 field IdentityList ownIdentities; 2937 } 2939 3.2.3. Example Messages 2941 [[ TODO ]] 2943 4. Security Considerations 2945 [[ TODO ]] 2947 5. Privacy Considerations 2949 [[ TODO ]] 2951 6. IANA Considerations 2953 This document has no actions for IANA. 2955 7. Acknowledgments 2957 The authors would like to thank the following people who have 2958 provided significant contributions to actual Running Code and the 2959 development of this document: Volker Birk and Krista Bennett. 2961 Furthermore, the authors would like to thank the following people who 2962 provided helpful comments and suggestions for this document: Claudio 2963 Luck, Damian Rutz, Kelly Bristol, and Nana Karlstetter. 2965 This work was initially created by pEp Foundation, and then reviewed 2966 and extended with funding by the Internet Society's Beyond the Net 2967 Programme on standardizing pEp. [ISOC.bnet] 2969 8. References 2971 8.1. Normative References 2973 [I-D.birk-pep] 2974 Marques, H. and B. Hoeneisen, "pretty Easy privacy (pEp): 2975 Privacy by Default", draft-birk-pep-03 (work in progress), 2976 March 2019. 2978 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2979 Requirement Levels", BCP 14, RFC 2119, 2980 DOI 10.17487/RFC2119, March 1997, 2981 . 2983 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2984 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2985 . 2987 [RFC7435] Dukhovni, V., "Opportunistic Security: Some Protection 2988 Most of the Time", RFC 7435, DOI 10.17487/RFC7435, 2989 December 2014, . 2991 8.2. Informative References 2993 [I-D.birk-pep-trustwords] 2994 Birk, V., Marques, H., and B. Hoeneisen, "IANA 2995 Registration of Trustword Lists: Guide, Template and IANA 2996 Considerations", draft-birk-pep-trustwords-03 (work in 2997 progress), March 2019. 2999 [I-D.marques-pep-handshake] 3000 Marques, H. and B. Hoeneisen, "pretty Easy privacy (pEp): 3001 Contact and Channel Authentication through Handshake", 3002 draft-marques-pep-handshake-02 (work in progress), March 3003 2019. 3005 [ISOC.bnet] 3006 Simao, I., "Beyond the Net. 12 Innovative Projects 3007 Selected for Beyond the Net Funding. Implementing Privacy 3008 via Mass Encryption: Standardizing pretty Easy privacy's 3009 protocols", June 2017, . 3013 Appendix A. Document Changelog 3015 [[ RFC Editor: This section is to be removed before publication ]] 3017 o draft-hoeneisen-pep-keysync-00: 3019 * Initial version 3021 Appendix B. Open Issues 3023 [[ RFC Editor: This section should be empty and is to be removed 3024 before publication ]] 3026 o Resolve several TODOs / add missing text 3028 Authors' Addresses 3030 Bernie Hoeneisen 3031 Ucom Standards Track Solutions GmbH 3032 CH-8046 Zuerich 3033 Switzerland 3035 Phone: +41 44 500 52 40 3036 Email: bernie@ietf.hoeneisen.ch (bernhard.hoeneisen AT ucom.ch) 3037 URI: https://ucom.ch/ 3039 Hernani Marques 3040 pEp Foundation 3041 Oberer Graben 4 3042 CH-8400 Winterthur 3043 Switzerland 3045 Email: hernani.marques@pep.foundation 3046 URI: https://pep.foundation/