idnits 2.17.1 draft-hoeneisen-pep-keysync-01.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 (October 31, 2019) is 1639 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-04 ** 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-04 == Outdated reference: A later version (-05) exists of draft-marques-pep-handshake-03 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: May 3, 2020 K. Bristol 6 pEp Foundation 7 October 31, 2019 9 pretty Easy privacy (pEp): Key Synchronization Protocol (KeySync) 10 draft-hoeneisen-pep-keysync-01 12 Abstract 14 This document describes the pEp KeySync protocol, which is designed 15 to perform secure peer-to-peer synchronization of private keys across 16 devices belonging to the same user. 18 Modern users of messaging systems typically have multiple devices for 19 communicating, and attempting to use encryption on all of these 20 devices often leads to situations where messages cannot be decrypted 21 on a given device due to missing private key data. Current 22 approaches to resolve key synchronicity issues are cumbersome and 23 potentially unsecure. The pEp KeySync protocol is designed to 24 facilitate this personal key synchronization in a user-friendly 25 manner. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on May 3, 2020. 44 Copyright Notice 46 Copyright (c) 2019 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (https://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 63 1.2. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.3. Problem Statement . . . . . . . . . . . . . . . . . . . . 5 65 1.4. Main Challenge . . . . . . . . . . . . . . . . . . . . . 5 66 1.5. Approach . . . . . . . . . . . . . . . . . . . . . . . . 5 67 2. General Description . . . . . . . . . . . . . . . . . . . . . 5 68 2.1. Use Cases for pEp KeySync . . . . . . . . . . . . . . . . 6 69 2.1.1. Form Device Group . . . . . . . . . . . . . . . . . . 6 70 2.1.2. Add New Device to Existing Device Group . . . . . . . 7 71 2.1.3. Exchange Private Keys . . . . . . . . . . . . . . . . 7 72 2.1.4. Leave Device Group . . . . . . . . . . . . . . . . . 7 73 2.1.5. Remove other Device from Device Group . . . . . . . . 8 74 2.2. Interaction Diagrams . . . . . . . . . . . . . . . . . . 8 75 2.2.1. Form Device Group . . . . . . . . . . . . . . . . . . 9 76 2.2.2. Add New Device to Existing Device Group . . . . . . . 17 77 2.2.3. Exchange Private Keys . . . . . . . . . . . . . . . . 24 78 2.2.4. Leave Device Group . . . . . . . . . . . . . . . . . 24 79 2.2.5. Remove other Device from Device Group . . . . . . . . 24 80 3. Security Considerations . . . . . . . . . . . . . . . . . . . 24 81 4. Privacy Considerations . . . . . . . . . . . . . . . . . . . 24 82 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 83 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24 84 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 85 7.1. Normative References . . . . . . . . . . . . . . . . . . 25 86 7.2. Informative References . . . . . . . . . . . . . . . . . 25 87 Appendix A. Reference Implementation . . . . . . . . . . . . . . 26 88 A.1. Full Finite-State Machine Diagram . . . . . . . . . . . . 26 89 A.1.1. States . . . . . . . . . . . . . . . . . . . . . . . 26 90 A.1.2. Actions . . . . . . . . . . . . . . . . . . . . . . . 35 91 A.1.3. Transitions . . . . . . . . . . . . . . . . . . . . . 39 92 A.2. Messages . . . . . . . . . . . . . . . . . . . . . . . . 39 93 A.2.1. Format . . . . . . . . . . . . . . . . . . . . . . . 40 94 A.2.2. List of Messages Used in Finite-State Machine . . . . 40 95 A.2.3. Example Messages . . . . . . . . . . . . . . . . . . 43 96 Appendix B. Finite-State Machine Code . . . . . . . . . . . . . 43 97 Appendix C. Document Changelog . . . . . . . . . . . . . . . . . 54 98 Appendix D. Open Issues . . . . . . . . . . . . . . . . . . . . 55 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55 101 1. Introduction 103 The pretty Easy privacy (pEp) [I-D.birk-pep] protocols describe a set 104 of conventions for the automation of operations traditionally seen as 105 barriers to the use and deployment of secure end-to-end interpersonal 106 messaging. These include, but are not limited to, key management, 107 key discovery, and private key handling. 109 This document specifies the pEp KeySync protocol, a means for secure, 110 decentralized, peer-to-peer synchronization of private keys across 111 devices belonging to the same user, allowing that user to send and 112 receive encrypted communications from any of their devices. 114 For pEp implementations, pEp KeySync is a critical part of the 115 broader pEp Sync protocol, which is designed to be extensible to 116 allow for the synchronization of additional user data, such as 117 configuration settings and peer trust status information across a 118 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. Requirements Language 126 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 127 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 128 document are to be interpreted as described in [RFC2119]. 130 1.2. Terms 132 The following terms are defined for the scope of this document: 134 o pEp Handshake: The process of one user contacting another over an 135 independent channel in order to verify Trustwords (or fingerprints 136 as a fallback). This can be done in-person or through established 137 verbal communication channels, like a phone call. 138 [I-D.marques-pep-handshake] 140 Note: In pEp KeySync, the Handshake is used to authenticate own 141 devices (the user normally compares the Trustwords directly by 142 looking at the screens of the devices involved). 144 o Trustwords: A scalar-to-word representation of 16-bit numbers (0 145 to 65535) to natural language words. When doing a Handshake, 146 peers are shown combined Trustwords of both public keys involved 147 to ease the comparison. [I-D.birk-pep-trustwords] 149 o Trust On First Use (TOFU): cf. [RFC7435], which states: "In a 150 protocol, TOFU calls for accepting and storing a public key or 151 credential associated with an asserted identity, without 152 authenticating that assertion. Subsequent communication that is 153 authenticated using the cached key or credential is secure against 154 an MiTM attack, if such an attack did not succeed during the 155 vulnerable initial communication." 157 o Man-in-the-middle (MITM) attack: cf. [RFC4949], which states: "A 158 form of active wiretapping attack in which the attacker intercepts 159 and selectively modifies communicated data to masquerade as one or 160 more of the entities involved in a communication association." 162 o Identity: The combination of a unique user identifier plus a 163 specific address (email, network ID, URI, etc.). A single user 164 may have multiple identities. See also [RFC4949]. 166 o Device Group: All of a user's devices which have successfully 167 completed the KeySync process, and are now configured to share 168 user data, such as cryptographic keys, trust information, 169 calendars, configurations, and other data as a result of that 170 process. This data is synchronized through a common channel for a 171 given identity. For example, an identity might be a specific 172 email address, and the common channel would be a mailbox for that 173 email address. 175 o Sole Device: A device which is not part of a Device Group. 177 o Grouped Device: A device which is already part of a Device Group. 179 o Beacon (message): A technical text message that is broadcast by 180 Sole Devices and transmitted through a message sent to the channel 181 of an identity. Other Sole Devices, or a Grouped Device of the 182 same unique identity and using that identity's channel, can 183 interpret this Beacon in order to initiate negotiation for the 184 formation of a Device Group. 186 o Transaction ID (TID): A UUID version 4, variant 1 number generated 187 by each device during the pEp KeySync process in order to identify 188 the respective devices involved. 190 o Default Key: A key which is actually used for a given identity. 192 o Own Key: A Default Key for an own identity. 194 1.3. Problem Statement 196 Secure and private digital communication is becoming a necessity for 197 many people. Encryption protocols which utilize key pairs are the 198 most popular and easily implemented methods to ensure a message is 199 authentic and can be trusted. 201 However, most modern users have multiple devices for communicating, 202 and attempting to use encryption on all of these devices often leads 203 to situations where messages cannot be decrypted on a given device 204 due to missing private key data. For example, Alice sends an 205 encrypted message to Bob, using the public key of a key pair that Bob 206 generated on his laptop. When Bob attempts to decrypt the message on 207 his mobile phone, the private key that he generated on his laptop is 208 not available. As a result, Bob must either use his laptop to 209 decrypt the message, or attempt to copy the correct private key to 210 his mobile device, which may expose his private key to potential 211 leaks or theft. 213 1.4. Main Challenge 215 The main challenge that pEp KeySync is designed to overcome is to 216 perform the synchronization in a secure manner so that private keys 217 are not leaked or exposed to theft. 219 Note: The case of an adversary getting physical access to the device 220 itself is beyond the scope of this document. 222 1.5. Approach 224 The basic approach to solving the multiple-device decryption problem 225 is to synchronize private keys among the devices of a user in a 226 secure manner. pEp achieves this by having a user form a Device Group 227 among their devices. During this process, a Handshake process 228 occurs, and the user will be presented with a Trustwords dialog 229 between any two devices at a time for pairing purposes. (cf. 230 [I-D.birk-pep-trustwords]) Simply put, a user MUST manually complete 231 the Trustwords dialog before the automatic and security-sensitive 232 transfer of private key information can occur. 234 2. General Description 236 The pEp KeySync protocol allows a user to securely synchronize 237 private key data for multiple identities across their various 238 devices. 240 This synchronization process is decentralized and performed as a two- 241 phase commit protocol structure (2PC). This structure ensures 242 consensus among the devices at all stages of the KeySync process. 244 KeySync's 2PC transaction is accomplished through the implementation 245 of a Finite-State Machine (FSM) on each pEp-enabled device. This FSM 246 not only sends and receives network traffic, which allows devices to 247 communicate with each other throughout the KeySync process, but also 248 interacts with the pEp engine itself. 250 Once activated, the pEp KeySync protocol initiates the formation of a 251 Device Group, and the user is guided through a Handshake process on 252 their respective devices. A user can choose to reject or cancel this 253 process at any time, from either device, and private key data is not 254 exchanged until the group formation process is verified on both 255 devices. 257 Once a Device Group is formed, a user can add additional devices to 258 their group through the same joining procedure. Upon adding the new 259 device to the existing Device Group, key data is synchronized among 260 all Grouped Devices, allowing a user to communicate privately from 261 any of their secure identities. 263 2.1. Use Cases for pEp KeySync 265 This section describes ideal-condition use cases for pEp KeySync. 266 The focus is on the core procedures and on the scenarios where 267 everything works. Unexpected user behavior, error handling, race 268 conditions, etc., are generally omitted from this section in order to 269 focus on the general concepts of pEp KeySync. Additional use cases 270 will be discussed in further detail throughout Appendix A. 272 2.1.1. Form Device Group 274 Our user, Alice, has two devices that are configured with pEp- 275 implementing messaging clients and share the same identity for her 276 preferred communication channel. In our example, this is a 277 communication channel with an email address. Let us call these 278 devices Alice_Mobile and Alice_Tablet. Each device already has its 279 own key pair, which was automatically generated by the pEp protocol. 280 Neither device knows anything about the other. 282 Alice wants full communication capability from both of her devices, 283 but currently cannot do so, as the devices do not know about each 284 other. Alice will use pEp KeySync to form a Device Group and add her 285 devices to it. This allows for the exchange of private key data 286 among its devices, allowing Alice to have full communication 287 capability on both of her devices. 289 2.1.2. Add New Device to Existing Device Group 291 Sometime after devices Alice_Mobile and Alice_Tablet have formed a 292 Device Group (cf. Section 2.1.1), Alice buys another device, 293 Alice_Laptop, which is also configured with pEp-implementing 294 messaging clients and shares the same identity for her preferred 295 communication channel (the aforementioned email address). 296 Alice_Laptop also has a key pair, which was automatically generated 297 by the pEp protocol, just as the Grouped Devices Alice_Mobile and 298 Alice_Tablet have. But while the Grouped Devices know each other and 299 have exchanged private keys, Alice_Laptop and the Grouped Devices 300 don't know each other. Thus, Alice does not have full communication 301 capability across the three devices. 303 As before with devices Alice_Mobile and Alice_Tablet, Alice will use 304 pEp KeySync to add device Alice_Laptop to the existing Device Group, 305 allowing all three devices to exchange private key information, and 306 Alice to have access to her messages from any of them. 308 2.1.3. Exchange Private Keys 310 All devices from Alice are part of a Device Group (cf. Section 2.1.1 311 and Section 2.1.2). However, as keys may expire or get reset, it is 312 inevitable that new key pairs will be generated. For Alice to 313 maintain her ability to read all encrypted messages on all devices, 314 any new private key needs to be shared with the other devices in the 315 device group. All devices in Alice's Device Group will share the 316 latest private keys as they are generated, keeping all of her devices 317 up to date and functioning as desired. 319 2.1.4. Leave Device Group 321 Alice decides that her mobile phone, Alice_Mobile, should no longer 322 have access to all private keys of the Device Group. Alice can 323 manually tell her mobile phone to leave the Device Group by turning 324 off the pEp Sync feature on her device, which deactivates KeySync. 325 The Device Group is dissolved, and Sync is disabled on her mobile 326 phone. This action also initiates the pEp KeyReset protocol, which 327 resets keys for all own identities. 329 In the future, if Alice desires, she can re-add her mobile phone to a 330 Device Group, but she will first have to re-enable Sync, and then 331 initiate the joining procedure again (cf. Section 2.1.1 and 332 Section 2.1.2). 334 2.1.5. Remove other Device from Device Group 336 One of Alice's devices may be stolen or become otherwise compromised. 337 She needs to ensure that the affected device no longer receives 338 updates to private keys from the other devices in her Device Group. 339 Using one of her remaining Grouped Devices, Alice can disable pEp 340 Sync (and thus KeySync) on her remaining devices. This action 341 dissolves the Device Group and initiates the pEp KeyReset protocol. 343 2.2. Interaction Diagrams 345 The following interaction diagrams depict what happens during Alice's 346 KeySync scenarios in a simplified manner. For each scenario, we 347 first present a successful case, then an unsuccessful case and, 348 finally, a case that has been interrupted, or discontinued. Some 349 details are skipped here for the sake of readability. Descriptions 350 of the interactions are included after each diagram. 352 Each pEp-enabled device runs its own Finite-State Machine (FSM), 353 which interact with each other throughout the KeySync process, and 354 drive the UI options presented to the user. All messages are 355 'broadcast' between devices. The TIDs added to each message allow 356 the identification of received messages which pertain to the ongoing 357 transaction and its sender. 359 For events requiring user interaction in order to proceed, it does 360 not matter which device has the specified option chosen first unless 361 otherwise indicated. For example, if an event states that the 362 'Offerer' chooses 'Accept' to continue, the process will be 363 unaffected if the 'Requester' device does so first. The only 364 difference is that the order of the roles for the remainder of the 365 given scenario will be swapped. 367 2.2.1. Form Device Group 369 2.2.1.1. Successful Case 371 ,-. 372 `-' 373 /|\ 374 ,----------------. | ,------------------. 375 |'Offerer' device| / \ |'Requester' device| 376 `-------+--------' User `--------+---------' 377 | | | 378 | | | 379 | 1(r). Beacon (challenge TID) | 380 |<--------------------------------------------| 381 | | | 382 | 1(o). Beacon (challenge TID) | 383 |-------------------------------------------->| 384 | | | 385 | 2. NegotiationRequest | 386 |<--------------------------------------------| 387 | | | 388 | | 3. Display Trustwords| 389 | |<- - - - - - - - - - -| 390 | | | 391 | 4. NegotiationOpen | 392 |-------------------------------------------->| 393 | | | 394 | 5. Display Trustwords| | 395 | - - - - - - - - - - >| | 396 | | | 397 | ,-----------------------------. | 398 | |Handshake (user comparison | | 399 | |of Trustwords) successful | | 400 | `-----------------------------' | 401 ,-----------------------------------. | 402 |User presses 'Accept' button | | 403 |on 'Requester' device | | 404 `-----------------------------------' | 405 | | 6. Accept | 406 | | - - - - - - - - - - >| 407 | | | 408 | 7. CommitAcceptRequester | 409 |<--------------------------------------------| 410 | | | 411 ,-----------------------------------. | 412 |User presses 'Accept' button | | 413 |on 'Offerer' device | | 414 `-----------------------------------' | 415 | 8. Accept | | 416 |<- - - - - - - - - - -| | 417 | | | 418 | 9. CommitAcceptOfferer | 419 |-------------------------------------------->| 420 | | | 421 | 10. OwnKeysOfferer + keys | 422 |-------------------------------------------->| 423 | | | 424 | | ,----------------------. 425 | | |Requester is Grouped | 426 | | `----------------------' 427 | 11. OwnKeysRequester + keys | 428 |<--------------------------------------------| 429 | | | 430 ,--------------------. | | 431 |Offerer is Grouped | | | 432 `--------------------' | | 433 | | | 434 ,-------+--------. User ,--------+---------. 435 |'Offerer' device| ,-. |'Requester' device| 436 `----------------' `-' `------------------' 437 /|\ 438 | 439 / \ 441 As depicted above, a user intends to form a Device Group in order to 442 securely share key material among its members. The group is formed 443 by an 'Offerer' device and a 'Requester' device. The names 'Offerer' 444 and 'Requester' are derived from the FSM, in which the device roles 445 are defined during the start sequence, which is necessary for the FSM 446 to work as intended. 448 During initialization of pEp KeySync, each device generates a 449 Transaction-ID (TID). These TIDs are sent as a challenge in a Beacon 450 over the mutual channel, and the device roles of 'Offerer' and 451 'Requester' are determined by the numeric value of each device's 452 unique TID. 454 1. Every device sends a Beacon message containing a challenge TID. 455 Upon receipt of a Beacon message from another device, the 456 received challenge TID is compared with the device's own 457 challenge TID. The device which has a TID with a lower 458 numerical value is assigned as the 'Requester', and the other 459 device is automatically assigned as the 'Offerer'. 461 Note: The 'Offerer' device MUST NOT start a negotiation. In the 462 event the earlier Beacon message is lost, the 'Offerer' device 463 re-sends its own Beacon and waits for a response. Message 1(r) 464 depicts the Beacon message sent by the 'Requester' device and is 465 not required for the process to continue. 467 2. After determination of the role, the 'Requester' device sends a 468 NegotiationRequest message. 470 3. The 'Requester' device displays the Trustwords to the user. 472 4. Upon receipt of the NegotiationRequest message, the 'Offerer' 473 device sends a NegotiationOpen message. 475 5. The 'Offerer' device displays the Trustwords to the user. 477 6. The user compares the Trustwords of both devices. As the 478 Trustwords are the same on both devices, the user chooses the 479 'Accept' option on the 'Requester' device. 481 7. On receipt of the user's 'Accept', the 'Requester' device sends 482 a CommitAcceptRequester message. 484 The 'Offerer' device receives this message and waits for the 485 user to choose 'Accept'. 487 8. The user compares the Trustwords of both devices and chooses the 488 'Accept' option on the 'Offerer' device. 490 9. Once the user chooses 'Accept', the 'Offerer' device sends a 491 CommitAcceptRequester message. 493 10. The 'Offerer' device then sends an OwnKeysOfferer message along 494 with the user's local key pairs (private and public keys) to 495 to be synchronized. 497 11. Upon receipt of the OwnKeysOfferer message, the 'Requester' 498 device is grouped and sends an OwnKeysRequester message along 499 with the user's local key pairs (private and public keys) to be 500 synchronized. 502 Upon receipt of the OwnKeysRequester message, the 'Offerer' 503 device is also grouped. The formation of the Device Group has 504 been successful. 506 2.2.1.2. Unsuccessful Case 508 ,-. 509 `-' 510 /|\ 511 ,----------------. | ,------------------. 512 |'Offerer' device| / \ |'Requester' device| 513 `-------+--------' User `--------+---------' 514 | | | 515 | | | 516 ,--------------------------------------------------------------!. 517 |Messages (1-5) are same as in the successful case (see above) |_\ 518 `----------------------------------------------------------------' 519 | | | 520 | | | 521 | ,-----------------------------. | 522 | |Handshake (user comparison | | 523 | |of Trustwords) unsuccessful | | 524 | `-----------------------------' | 525 | ,------------------------------------. 526 | |User presses 'Reject' button | 527 | |on 'Requester' device | 528 | `------------------------------------' 529 | | R6. Reject | 530 | | - - - - - - - - - - >| 531 | | | 532 | R7. CommitReject | 533 |<-------------------------------------------| 534 | | | 535 ,--------------------------------------------------------------!. 536 | Devices (still not grouped) will not try again |_\ 537 `----------------------------------------------------------------' 538 | | | 539 ,-------+--------. User ,--------+---------. 540 |'Offerer' device| ,-. |'Requester' device| 541 `----------------' `-' `------------------' 542 /|\ 543 | 544 / \ 546 For unsuccessful KeySync attempts, messages 1-5 are the same as in a 547 successful attempt (see above), but once the Trustwords are shown, 548 events are as follows: 550 R6. The user compares the Trustwords of both devices. As the 551 Trustwords do not match, the user chooses the 'Reject' option 552 on the 'Requester' device. 554 R7. On receipt of the user's 'Reject', the 'Requester' device sends 555 a CommitReject message. 557 Once the CommitReject message is sent or received, respectively, the 558 devices cannot form a Device Group, and pEp KeySync is disabled on 559 both devices. As a result, there are no further attempts to form a 560 Device Group involving either of these two devices. KeySync may be 561 re-enabled in the pEp settings on the affected device(s). 563 2.2.1.3. Discontinuation Case 565 ,-. 566 `-' 567 /|\ 568 ,----------------. | ,------------------. 569 |'Offerer' device| / \ |'Requester' device| 570 `-------+--------' User `--------+---------' 571 | | | 572 | | | 573 ,--------------------------------------------------------------!. 574 |Messages (1-5) are same as in the successful case (see above) |_\ 575 `----------------------------------------------------------------' 576 | | | 577 | | | 578 | ,-----------------------------. | 579 | |Handshake (user comparison | | 580 | |of Trustwords) discontinued | | 581 | `-----------------------------' | 582 | ,------------------------------------. 583 | |User presses 'Cancel' button | 584 | |on 'Requester' device | 585 | `------------------------------------' 586 | | C6. Cancel | 587 | | - - - - - - - - - - >| 588 | | | 589 | C7. Rollback | 590 |<-------------------------------------------| 591 | | | 592 ,--------------------------------------------------------------!. 593 | Devices (still not grouped) will try again |_\ 594 `----------------------------------------------------------------' 595 | | | 596 ,-------+--------. User ,--------+---------. 597 |'Offerer' device| ,-. |'Requester' device| 598 `----------------' `-' `------------------' 599 /|\ 600 | 601 / \ 603 For discontinued (canceled) KeySync attempts, messages 1-5 are the 604 same as in a successful attempt (see above), but once the Trustwords 605 are shown, events are as follows: 607 C6. The user decides to discontinue the process and chooses the 608 'Cancel' option on the 'Requester' device. 610 C7. On receipt of the user's 'Cancel', the 'Requester' device sends 611 a rollback message. 613 The devices do not form a Device Group. KeySync remains enabled on 614 both devices, and forming a Device Group can start again. 616 2.2.2. Add New Device to Existing Device Group 618 2.2.2.1. Successful Case 620 ,-------. ,-. 621 |New | `-' ,--------. ,--------. 622 |device | /|\ |Active | |Passive | 623 |to join| | |device | |devices | 624 |group | / \ |in group| |in group| 625 `---+---' User `---+----' `---+----' 626 | | | | 627 | | | | 628 | 1. Beacon | | 629 |--------------------------------->| | 630 | | | | 631 | | 1. Beacon | | 632 |----------------------------------------------------->| 633 | | | | 634 | 2(p). NegotiationRequest | 635 |<-----------------------------------------------------| 636 | | | | 637 | | 3(p) Display Trustwords | 638 | |<- - - - - - - - - - - - - - - - - - | 639 | | | | 640 | 4(p) NegotiationOpen | 641 |----------------------------------------------------->| 642 | | | | 643 | 2(a). NegotiationRequest | | 644 |<---------------------------------| | 645 | | | | 646 | | 3(a). Display | | 647 | | Trustwords | | 648 | |<- - - - - - - - | | 649 | | | | 650 | 4(a). NegotiationOpen | | 651 |--------------------------------->| | 652 | | | | 653 | 5. Display | | | 654 | Trustwords | | | 655 | - - - - - - - >| | | 656 | | | | 657 | ,-----------------------------. | | 658 | |Handshake (user comparison | | | 659 | |of Trustwords) successful | | | 660 | `-----------------------------' | | 661 | ,------------------------------. | 662 | |User presses 'Accept' button | | 663 | |on a device in group | | 664 | `------------------------------' | 665 | | 6. Accept | | 666 | | - - - - - - - ->| | 667 | | | | 668 | | | 7. GroupTrust | 669 | | | ThisKey | 670 | | |------------------>| 671 | | | | 672 | 8. CommitAcceptForGroup | | 673 |<---------------------------------| | 674 | | | | 675 ,------------------------------. | | 676 |User presses 'Accept' button | | | 677 |on new device | | | 678 `------------------------------' | | 679 | 9. Accept | | | 680 |<- - - - - - - -| | | 681 | | | | 682 | 10. CommitAccept | | 683 |--------------------------------->| | 684 | | | | 685 | 11. GroupKeys (key data) | | 686 |<---------------------------------| | 687 | | | | 688 ,------------. | | | 689 |New device | | | | 690 |is grouped | | | | 691 `------------' | | | 692 | 12. GroupKeys (key data) | | 693 |--------------------------------->| | 694 | | | | 695 | | 12. GroupKeys (key data) | 696 |----------------------------------------------------->| 697 | | | | 698 | | | | 699 ,---+---. User ,---+----. ,---+----. 700 |New | ,-. |Active | |Passive | 701 |device | `-' |device | |devices | 702 |to join| /|\ |in group| |in group| 703 |group | | `--------' `--------' 704 `-------' / \ 706 As depicted above, a user intends to add a new device to an existing 707 Device Group. 709 1. During initialization of pEp KeySync, the new device sends a 710 Beacon message. 712 Note: In the diagram, all messages marked "1. Beacon" are a 713 single message, but drawn separately in order to convey that the 714 message is sent to all devices in the Device Group. 716 2. Upon receipt of a Beacon message from a device not part of a 717 Device Group, all Grouped Devices send a NegotiationRequest 718 message. 720 Note: Messages 2(a) and 2(p) are different instances of the 721 NegotiationRequest message type. 723 3. All Grouped Devices display the Trustwords to the user. 725 4. Upon receipt of every NegotiationRequest message, the New Device 726 sends a NegotiationOpen message. 728 Note: Messages 4(a) and 4(p) are different instances of the 729 NegotiationOpen message type. 731 5. The new device displays the Trustwords to the user. 733 6. The user compares the Trustwords of both devices and chooses the 734 'Accept' option on one of the Grouped Devices. 736 Note 1: The Grouped Device that the user chooses the 'Accept' 737 option from assumes the role of the active device for the Device 738 Group. 740 7. On receipt of the user's 'Accept', the Active Grouped Device 741 sends a TrustThisKey message to the passive Grouped Devices. 743 8. The Active Grouped Device also sends a CommitAcceptForGroup 744 message to the new device. Upon receipt, the new device waits 745 for the user to choose 'Accept'. 747 9. The user compares the Trustwords of both devices and chooses the 748 'Accept' option on the new device. 750 10. Once the user chooses 'Accept', the new device sends a 751 CommitAccept message to the Device Group. 753 11. The new device then sends a GroupKeys message which contains its 754 own private keys. 756 12. Upon receipt of the GroupKeys message from the new device, the 757 Active Grouped Device FSM transitions to state Grouped, adds the 758 new device's keys to the GroupKeys, and sends a GroupKeys 759 message to the entire Device Group. The new device has 760 successfully joined the Device Group and all keys are 761 synchronized among the devices. 763 Note: In the diagram, all messages marked "12. GroupKeys + keys" are 764 a single message, but drawn separately in order to convey that the 765 message is sent to all devices in the Device Group. 767 2.2.2.2. Unsuccessful Case 769 ,-------. ,-. 770 |New | `-' ,--------. ,--------. 771 |device | /|\ |Active | |Passive | 772 |to join| | |device | |devices | 773 |group | / \ |in group| |in group| 774 `---+---' User `---+----' `---+----' 775 | | | | 776 | | | | 777 ,---------------------------------------------------------------!. 778 |Messages (1-5) are same as in the successful case (see above) |_\ 779 `-----------------------------------------------------------------' 780 | | | | 781 | | | | 782 | ,-----------------------------. | | 783 | |Handshake (user comparison | | | 784 | |of Trustwords) unsuccessful | | | 785 | `-----------------------------' | | 786 | ,------------------------------. | 787 | |User presses 'Reject' button | | 788 | |on a device in group | | 789 | `------------------------------' | 790 | | R6. Reject | | 791 | | - - - - - - - ->| | 792 | | | | 793 | R7. CommitReject | | 794 |<---------------------------------| | 795 | | | | 796 | | | R7. CommitReject | 797 | | |------------------>| 798 | | | | 799 ,----------!. | | | 800 |New device|_\ | | | 801 |(still not | | | | 802 |grouped) | | | | 803 |will not | | | | 804 |try again | | | | 805 `------------' | | | 806 | | | | 807 ,---+---. User ,---+----. ,---+----. 808 |New | ,-. |Active | |Passive | 809 |device | `-' |device | |devices | 810 |to join| /|\ |in group| |in group| 811 |group | | `--------' `--------' 812 `-------' / \ 814 For unsuccessful KeySync attempts, messages 1-5 are the same as in a 815 successful attempt (see above), but once the Trustwords are shown, 816 events are as follows: 818 R6. The user compares the Trustwords displayed on both devices. 819 If the Trustwords do not match, the user chooses the 'Reject' 820 option on one of the Grouped Devices. This issues a 821 'CommitReject' message to the FSM as well as all devices in the 822 Device Group. 824 R7. Upon receiving the 'Reject' message from the Device Group, the 825 'Requester' device sends a 'CommitReject' message to the FSM. 827 Note: In the diagram, all messages marked "R7. CommitReject" 828 are a single message, but drawn separately in order to convey 829 that the message is sent to all devices in the Device Group. 831 Once the CommitReject message is sent or received, respectively, the 832 new device cannot join the Device Group, and pEp KeySync is disabled 833 on the new device. As a result, there are no further attempts to 834 join a Device Group by the new device. pEp KeySync may be re-enabled 835 in the pEp settings on the affected device. 837 2.2.2.3. Discontinuation Case 839 ,-------. ,-. 840 |New | `-' ,--------. ,--------. 841 |device | /|\ |Active | |Passive | 842 |to join| | |device | |devices | 843 |group | / \ |in group| |in group| 844 `---+---' User `---+----' `---+----' 845 | | | | 846 | | | | 847 ,---------------------------------------------------------------!. 848 |Messages (1-5) are same as in the successful case (see above) |_\ 849 `-----------------------------------------------------------------' 850 | | | | 851 | | | | 852 | ,-----------------------------. | | 853 | |Handshake (user comparison | | | 854 | |of Trustwords) discontinued | | | 855 | `-----------------------------' | | 856 | ,------------------------------. | 857 | |User presses 'Cancel' button | | 858 | |on a device in group | | 859 | `------------------------------' | 860 | | C6. Cancel | | 861 | | - - - - - - - ->| | 862 | | | | 863 | C7. Rollback | | 864 |<---------------------------------| | 865 | | | | 866 | | | C7. Rollback | 867 | | |------------------>| 868 | | | | 869 ,----------!. | | | 870 |New device|_\ | | | 871 |(still not | | | | 872 |grouped) | | | | 873 |will try | | | | 874 |again | | | | 875 `------------' | | | 876 | | | | 877 ,---+---. User ,---+----. ,---+----. 878 |New | ,-. |Active | |Passive | 879 |device | `-' |device | |devices | 880 |to join| /|\ |in group| |in group| 881 |group | | `--------' `--------' 882 `-------' / \ 884 For discontinued (canceled) KeySync attempts, messages 1-5 are the 885 same as in a successful attempt (see above), but once the Trustwords 886 are shown, events are as follows: 888 C6. The user decides to discontinue the process and chooses the 889 'Cancel' option on one of the Grouped Devices. 891 C7. On receipt of the 'Cancel' from the 'Offerer' device, the 892 'Requester' device sends a rollback message to the FSM. 894 Note: In the diagram, all messages marked "C7. Rollback" 895 are a single message, but drawn separately in order to convey 896 that the message is sent to all devices in the Device Group. 898 The new device does not join the Device Group. KeySync remains 899 enabled and joining a Device Group can start again at any time. 901 2.2.3. Exchange Private Keys 903 [[ TODO ]] 905 2.2.4. Leave Device Group 907 [[ TODO ]] 909 2.2.5. Remove other Device from Device Group 911 [[ TODO ]] 913 3. Security Considerations 915 [[ TODO ]] 917 4. Privacy Considerations 919 [[ TODO ]] 921 5. IANA Considerations 923 This document has no actions for IANA. 925 6. Acknowledgments 927 The authors would like to thank the following people who have 928 provided significant contributions to actual Running Code and the 929 development of this document: Volker Birk and Krista Bennett. 931 Furthermore, the authors would like to thank the following people who 932 provided helpful comments and suggestions for this document: Claudio 933 Luck, Damian Rutz, Damiano Boppart, and Nana Karlstetter. 935 This work was initially created by pEp Foundation, and then reviewed 936 and extended with funding by the Internet Society's Beyond the Net 937 Programme on standardizing pEp. [ISOC.bnet] 939 7. References 941 7.1. Normative References 943 [I-D.birk-pep] 944 Marques, H., Luck, C., and B. Hoeneisen, "pretty Easy 945 privacy (pEp): Privacy by Default", draft-birk-pep-04 946 (work in progress), July 2019. 948 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 949 Requirement Levels", BCP 14, RFC 2119, 950 DOI 10.17487/RFC2119, March 1997, 951 . 953 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 954 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 955 . 957 [RFC7435] Dukhovni, V., "Opportunistic Security: Some Protection 958 Most of the Time", RFC 7435, DOI 10.17487/RFC7435, 959 December 2014, . 961 7.2. Informative References 963 [I-D.birk-pep-trustwords] 964 Hoeneisen, B. and H. Marques, "IANA Registration of 965 Trustword Lists: Guide, Template and IANA Considerations", 966 draft-birk-pep-trustwords-04 (work in progress), July 967 2019. 969 [I-D.marques-pep-handshake] 970 Marques, H. and B. Hoeneisen, "pretty Easy privacy (pEp): 971 Contact and Channel Authentication through Handshake", 972 draft-marques-pep-handshake-03 (work in progress), July 973 2019. 975 [ISOC.bnet] 976 Simao, I., "Beyond the Net. 12 Innovative Projects 977 Selected for Beyond the Net Funding. Implementing Privacy 978 via Mass Encryption: Standardizing pretty Easy privacy's 979 protocols", June 2017, . 983 Appendix A. Reference Implementation 985 [[ Note: The full Finite-State Machine code can be found in 986 Appendix B. This section is not a complete reference at this time. 987 The authors intend to refine this section in future revisions of this 988 document. ]] 990 The pEp KeySync Finite-State Machine is based on a two-phase commit 991 protocol (2PC) structure. This section describes the states, 992 actions, events, and messages which comprise the pEp KeySync FSM, and 993 are intended to allow readers to understand the general functionality 994 and message flow of the FSM. 996 States are used to direct actions, events, and messages. Actions 997 describe internal FSM functions, and fall into two general types. 998 The first action type directs the state transitions within the FSM, 999 and the second type drives UI functionality. Events are exchanged 1000 both between negotiation partners as well as the pEp engine itself to 1001 trigger actions and send messages. Messages contain information to 1002 ensure the integrity of the KeySync session as well as additional 1003 data, depending on the type of message (cf. Appendix A.2). 1005 A.1. Full Finite-State Machine Diagram 1007 A full diagram of the implemented pEp KeySync FSM can be found at the 1008 following URL: 1010 https://pep.foundation/dev/repos/internet-drafts/raw- 1011 file/tip/misc/figures/sync/sync_fsm_full.svg 1013 A.1.1. States 1015 A.1.1.1. InitState 1017 On initialization, the FSM enters InitState, which evaluates and 1018 determines a device's group status. If the device is detected to 1019 belong to a Device Group, the FSM transitions to state Grouped. 1020 Otherwise, the FSM transitions to state Sole (cf. Appendix A.1.2.1). 1022 A.1.1.2. Sole 1024 This is the default FSM state for an ungrouped device. 1026 On initialization, a challenge TID is created and sent out inside of 1027 a Beacon message along with the device's current state. The FSM also 1028 listens for Beacons from other devices. Upon receipt of a Beacon 1029 message from another device, the received challenge TID is compared 1030 with the own challenge. The device with the lower challenge TID is 1031 assigned the 'Requester' role, and the other device is automatically 1032 assigned the 'Offerer' role. 1034 If a device is determined to be the 'Requester', it issues a 1035 NegotiationRequest event to the 'Offerer'. 1037 When the 'Offerer' device receives this NegotiationRequest message, 1038 it responds with a NegotiationOpen message, and the 'Offerer' FSM 1039 transitions to state HandshakingOfferer while it awaits the 1040 'Requester' device response. 1042 On receipt of the 'Offerer' device's NegotiationOpen message, the 1043 'Requester' FSM proceeds in one of two ways, depending on the 1044 'Offerer' device state: 1046 o Sole: The 'Requester' FSM transitions to state 1047 HandshakingRequester. 1049 o Grouped: The 'Requester' FSM transitions to state 1050 HandshakingToJoin. 1052 A.1.1.3. HandshakingOfferer 1054 This state can only be entered by the 'Offerer' device in a Sole 1055 state, and drives user interface options, including the Trustwords 1056 dialog. The user is prompted to compare Trustwords and choose from 1057 the following options: 1059 o Accept: A CommitAcceptOfferer message is sent to the 'Requester' 1060 device, and the FSM transitions to state HandshakingPhase1Offerer 1061 while it waits for a response. 1063 o Reject: A CommitReject message is sent to the 'Requester' device, 1064 pEp KeySync is disabled, and the FSM transitions to state End. 1066 o Cancel: A Rollback message is sent to the 'Requester' device, and 1067 the FSM transitions to state Sole. 1069 Once the user selects one of the above options on the 'Offerer' 1070 device, the FSM waits for a response from the 'Requester' device. 1071 When this response is received, the 'Offerer' FSM performs a 1072 sameNegotiationAndPartner conditional check to verify the session 1073 integrity. If this conditional returns 'true', the FSM proceeds as 1074 follows, depending on the message received: 1076 o CommitAcceptRequester: The 'Requester' device public key is 1077 trusted, and the FSM transitions to state 1078 HandshakingPhase2Offerer. 1080 o CommitReject: pEp KeySync is disabled, and the FSM transitions to 1081 state End. 1083 o Rollback: The FSM transitions to state Sole. 1085 A.1.1.4. HandshakingRequester 1087 This state can only be entered by the 'Requester' device in a Sole 1088 state, and drives user interface options, including the Trustwords 1089 dialog. The user is prompted to compare Trustwords, and choose from 1090 the following options: 1092 o Accept: A CommitAcceptRequester message is sent to the 'Offerer' 1093 device, the 'Offerer' public key is trusted, and the FSM 1094 transitions to state HandshakingPhase1Requester while it waits for 1095 a response. 1097 o Reject: A CommitReject message is sent to the 'Offerer' device, 1098 pEp KeySync is disabled, and the FSM transitions to state End. 1100 o Cancel: A Rollback message is sent to the 'Offerer' device, and 1101 the FSM transitions to state Sole. 1103 Once the user selects one of the above options on the 'Requester' 1104 device, the FSM waits for a response from the 'Offerer' device. When 1105 this response is received, the 'Requester' FSM performs a 1106 sameNegotiationAndPartner conditional check to verify the session 1107 integrity. If this conditional returns 'true', the FSM proceeds as 1108 follows, depending on the message received: 1110 o CommitAcceptOfferer: The FSM transitions to state 1111 HandshakingPhase2Requester. 1113 o CommitReject: pEp KeySync is disabled, and the FSM transitions to 1114 state End. 1116 o Rollback: The FSM transitions to state Sole. 1118 A.1.1.5. HandshakingPhase1Offerer 1120 This state can only be entered by the 'Offerer' device in a Sole 1121 state. 1123 This state awaits and processes the response from a 'Requester' 1124 device in state HandshakingRequester. When this response is 1125 received, the 'Offerer' FSM performs a sameNegotiationAndPartner 1126 conditional check to verify the session integrity. If this 1127 conditional returns 'true', the FSM proceeds as follows, depending on 1128 the message received: 1130 o CommitAcceptRequester: The FSM transitions to state 1131 FormingGroupOfferer. 1133 o CommitReject: The 'Requester' public key is mistrusted, pEp 1134 KeySync is disabled, and the FSM transitions to state End. 1136 o Rollback: The 'Requester' public key is mistrusted, and the FSM 1137 transitions to state Sole. 1139 A.1.1.6. HandshakingPhase1Requester 1141 This state can only be entered by the 'Requester' device in a Sole 1142 state. 1144 This state awaits and processes the response from an 'Offerer' device 1145 in state HandshakingOfferer. When this response is received, the 1146 'Requester' FSM performs a sameNegotiationAndPartner conditional 1147 check to verify the session integrity. If this conditional returns 1148 'true', the FSM proceeds as follows, depending on the message 1149 received: 1151 o CommitAcceptOfferer: The FSM transitions to state 1152 FormingGroupRequester. 1154 o CommitReject: The 'Offerer' public key is mistrusted, pEp KeySync 1155 is disabled, and the FSM transitions to state End. 1157 o Rollback: The 'Offerer' public key is mistrusted, and the FSM 1158 transitions to state Sole. 1160 A.1.1.7. HandshakingPhase2Offerer 1162 This state can only be entered by the 'Offerer' device in a Sole 1163 state. 1165 The FSM waits for the 'Offerer' device in state 1166 HandshakingPhase1Offerer to process the 'Requester' device response. 1167 Once that is done, the following UI options are displayed for the 1168 'Offerer' device: 1170 o Accept: The 'Requester' public key used in the Handshake is marked 1171 'trusted', a CommitAcceptOfferer message is issued to the 1172 'Requester', and the FSM transitions to state FormingGroupOfferer. 1174 o Reject: A CommitReject message is issued to the 'Requester' 1175 device, pEp KeySync is disabled, and the FSM transitions to state 1176 End. 1178 o Cancel: A Rollback message is issued to the 'Requester' device, 1179 and the FSM transitions to state Sole. 1181 A.1.1.8. HandshakingPhase2Requester 1183 This state can only be entered by the 'Requester' device in a Sole 1184 state. 1186 The FSM waits for the 'Requester' device in state 1187 HandshakingPhase1Requester to process the 'Offerer' device response. 1188 Once that is done, the following UI options are displayed for the 1189 'Requester' device: 1191 o Accept: The 'Offerer' public key used in the Handshake is marked 1192 'trusted', a CommitAcceptRequester message is issued to the 1193 'Offerer' device, and the FSM transitions to state 1194 FormingGroupRequester. 1196 o Reject: A CommitReject message is issued to the 'Offerer' device, 1197 pEp KeySync is disabled, and the FSM transitions to state End. 1199 o Cancel: A Rollback message is issued to the 'Offerer' device, and 1200 the FSM transitions to state Sole. 1202 A.1.1.9. FormingGroupOfferer 1204 This state can only be entered by the 'Offerer' device in a Sole 1205 state. 1207 In this state, the user is given two options: Initialize the final 1208 step of the KeySync process (exchange of private key information), or 1209 Cancel. 1211 o Init: The FSM prepares the Own Keys on the 'Offerer' device for 1212 synchronization. The FSM then issues an OwnKeysOfferer message 1213 which contains these keys, triggers a UI event to indicate that 1214 Device Group formation is in progress, and awaits a response from 1215 the 'Requester' device. 1217 Once the 'Requester' responds with a OwnKeysRequester message, the 1218 'Requester' device keys are received, combined with the 'Offerer' 1219 keys, and saved in a shared GroupKeys array (saveGroupKeys). The 1220 'Requester' device keys are marked as default for those respective 1221 identities (receivedKeysAreDefaultKeys). A UI event 1222 (showGroupCreated) indicates that the Device Group process is 1223 complete, and the FSM transitions to state Grouped. 1225 o Cancel: A Rollback message is issued to the 'Requester' device, 1226 and the FSM transitions to state Sole. No private key data is 1227 exchanged. 1229 A.1.1.10. FormingGroupRequester 1231 This state can only be entered by the 'Requester' device in a Sole 1232 state. 1234 In this state, the user is given two options: Initialize the final 1235 step of the KeySync process (exchange of private key information), or 1236 Cancel. 1238 o Init: The FSM triggers a UI event to indicate that Device Group 1239 formation is in progress, and awaits an OwnKeysOfferer response 1240 from the 'Offerer' device. 1242 o Cancel: A Rollback message is issued to the 'Requester' device, 1243 and the FSM transitions to state Sole. No private key data is 1244 exchanged. 1246 Once an OwnKeysOfferer message is received, the 'Requester' FSM saves 1247 the 'Offerer' keys in a shared GroupKeys array (saveGroupKeys), and 1248 prepares the device's Own Keys for synchronization. The 'Requester' 1249 device keys are marked as default for those respective identities 1250 (ownKeysAreDefaultKeys). The FSM then issues an OwnKeysRequester 1251 message which contains these keys. A UI event (showGroupCreated) 1252 indicates that the Device Group process is complete, and the FSM 1253 transitions to state Grouped. 1255 A.1.1.11. Grouped 1257 This is the default state for any Grouped Device. 1259 On initialization, this state generates a new challenge TID and shows 1260 the device as being in the Grouped state. This device state also 1261 listens for Beacons from other devices that are not yet part of the 1262 Device Group. 1264 Upon receipt of a Beacon message from Sole Device, the device sends a 1265 NegotiationRequest message and waits for the Sole Device to respond 1266 with a NegotiationOpen message. 1268 On receipt of the NegotiationOpen message from the Sole Device, the 1269 FSM of the Grouped Device stores the negotiation information and 1270 transitions to state HandshakingGrouped. 1272 In this state, other events may also be processed, but these events 1273 do not result in a transition to another state. 1275 A.1.1.12. HandshakingToJoin 1277 This state can only be entered by a device in the Sole state that is 1278 attempting to join an existing Device Group. 1280 In this state, the FSM waits for the user to compare the Trustwords 1281 and to choose from the following options on the new device: 1283 o Accept: A CommitAccept message is sent and the FSM transitions to 1284 state HandshakingToJoinPhase1. 1286 o Reject: A CommitReject message is sent, pEp KeySync is disabled 1287 (on the new device), and the FSM transitions to state End. 1289 o Cancel: A Rollback message is sent and the FSM transitions to 1290 state Sole. 1292 If the 'Accept' option is chosen on a Grouped Device, a 1293 CommitAcceptForGroup message is received and the FSM transitions to 1294 state HandshakingToJoinPhase2. 1296 If the 'Reject' option is chosen on a Grouped Device, a CommitReject 1297 message is received. pEp KeySync is disabled (on the new device) and 1298 the FSM transitions to state End. 1300 If the 'Cancel' option is chosen on the 'Requester' device, a 1301 Rollback message is received and the FSM transitions to state Sole. 1303 A.1.1.13. HandshakingToJoinPhase1 1305 This state is entered by a new device only, i.e. a device that is not 1306 yet part of a Device Group. The FSM waits for the user to finish the 1307 Handshake on a Grouped Device (the user compares the Trustwords and 1308 chooses from the options presented): 1310 If the 'Accept' option is chosen on a Grouped Device, a 1311 CommitAcceptForGroup message is received and the FSM transitions to 1312 state JoiningGroup. 1314 If the 'Reject' option is chosen on a Grouped Device, a CommitReject 1315 message is received. pEp KeySync is disabled (on the new device) and 1316 the FSM transitions to state End. 1318 If the 'Cancel' option is chosen on the 'Requester' device, a 1319 Rollback message is received and the FSM transitions to state Sole. 1321 A.1.1.14. HandshakingToJoinPhase2 1323 This state is entered by a new device only, i.e. a device that is not 1324 yet part of a Device Group. 1326 In this state, the FSM waits for the user to compare the Trustwords 1327 and to choose from the following options on the new device: 1329 o Accept: A CommitAccept message is sent and the FSM transitions to 1330 state JoiningGroup. 1332 o Reject: A CommitReject message is sent, pEp KeySync is disabled 1333 (on the new device), and the FSM transitions to state End. 1335 o Cancel: A Rollback message is sent and the FSM transitions to 1336 state Sole. 1338 A.1.1.15. JoiningGroup 1340 This state is entered by a new device only, i.e. a device that is not 1341 yet part of a Device Group. 1343 The FSM waits to receive the keys from the active Grouped Device. 1344 Once received, these are saved and marked as Default Keys. Then it 1345 sends all keys to the Grouped Devices and the FSM transitions to 1346 state Grouped. 1348 A.1.1.16. HandshakingGrouped 1350 This state is entered by Grouped Devices only, i.e., devices that are 1351 part of a Device Group. 1353 In this state the FSM waits for the user to compare the Trustwords 1354 and to choose any of the following options from any Grouped Device, 1355 which will now become the Active Grouped Device: 1357 o Accept: A CommitAcceptForGroup message is sent and the FSM 1358 transitions to state HandshakingGroupedPhase1. 1360 o Reject: A CommitReject message is sent and the FSM transitions to 1361 state Grouped. 1363 o Cancel: A Rollback message is sent and the FSM transitions to 1364 state Grouped. 1366 If the 'Accept' option is chosen on the new device, a CommitAccept 1367 message is received and the FSM transitions to state 1368 HandshakingPhase2. 1370 If the 'Reject' option is chosen on the new device, a CommitReject 1371 message is received and the FSM transitions to state Grouped. 1373 If the 'Cancel' option is chosen on the new device, a Rollback 1374 message is received and the FSM transitions to state Grouped. 1376 Note: In this state, other events are processed, but these events do 1377 not result in a transition to another state and are not discussed 1378 here. 1380 A.1.1.17. HandshakingGroupedPhase1 1382 This state is entered by Grouped Devices only, i.e., devices that are 1383 already part of a Device Group. The FSM waits for the user to finish 1384 the Handshake on the new device (the user compares the Trustwords and 1385 chooses from the options presented): 1387 If the 'Accept' option is chosen on the new device, a CommitAccept 1388 message is received and the FSM transitions to state Grouped. 1390 If the 'Reject' option is chosen on the new device, a CommitReject 1391 message is received and the FSM transitions to state Grouped. 1393 If the 'Cancel' option is chosen on the new device, a Rollback 1394 message is received and the FSM transitions to state Grouped. 1396 In this state also a various other events are processed, which do not 1397 result in a transition to another state. 1399 A.1.1.18. HandshakingGroupedPhase2 1401 This state is entered by Grouped Devices only, i.e. devices that are 1402 already part of a Device Group. 1404 In this state the FSM waits for the user to compare the Trustwords 1405 and to choose from the following options from any Grouped Device, 1406 which will now become the Active Grouped Device: 1408 o Accept: A CommitAcceptForGroup message is sent and the FSM 1409 transitions to state HandshakingGroupedPhase1 1411 o Reject: A CommitReject message is sent and the FSM transitions to 1412 state Grouped 1414 o Cancel: A Rollback message is sent and the FSM transitions to 1415 state Grouped 1417 In this state also various other events are processed, which do not 1418 result in a transition to another state, but in the execution of 1419 certain actions (e.g., saveGroupKeys). 1421 A.1.2. Actions 1423 A.1.2.1. deviceGrouped (conditional) 1425 The 'deviceGrouped' conditional evaluates true if a device is already 1426 in a Device Group. This boolean value is available and eventually 1427 altered locally on every KeySync-enabled device. For example, in the 1428 reference implementation, this boolean value is stored in a local SQL 1429 database. 1431 The 'deviceGrouped' value is what the KeySync FSM uses upon 1432 initialization to determine whether a device should transition to 1433 state Sole or state Grouped. 1435 A.1.2.2. disable 1437 The 'disable' action may be called in an number of scenarios. For 1438 example, a user has rejected a pEp Handshake on either device 1439 involved in a pEp Handshake. At this time, in all cases, invoking 1440 the 'disable' function results in the FSM transitioning to state End, 1441 which disables the KeySync feature. pEp KeySync can be manually re- 1442 enabled in the pEp settings on an affected device. 1444 A.1.2.3. hideHandshakeDialog 1446 During the negotiation process for adding a new device to an existing 1447 Device Group, any device in that group can be used to complete the 1448 handshaking process and, as a result, each device in a Device Group 1449 will display the Handshake dialog options. Once this process is 1450 performed on one of the Grouped Devices, that device becomes the 1451 Active Grouped Device, and a GroupTrustThisKey message is sent to the 1452 other (now Passive) Grouped Devices. Upon receipt of the 1453 GroupTrustThisKey message, the 'hideHandshakeDialog' action is 1454 invoked, and is intended to force the closure of the extra Handshake 1455 dialog boxes. 1457 A.1.2.4. openNegotiation 1459 An 'openNegotiation' action is carried out either by a Sole Device in 1460 the 'Requester' role, or a Grouped device upon receipt of a Beacon 1461 message from another Sole Device. Most importantly, this action 1462 ensures that the own TID and the challenge TID of the Sole Device get 1463 combined by the mathematical XOR function. In this way, a common TID 1464 exists which can be used by both devices a user wishes to pair. This 1465 TID is crucial in allowing the devices to recognize themselves in a 1466 particular pairing process, as multiple pairing process can occur 1467 simultaneously. 1469 A.1.2.5. ownKeysAreDefaultKeys 1471 The ownKeysAreDefaultKeys action is invoked by the 'Requester' device 1472 during the final step of Device Group formation between two Sole 1473 devices, and ensures that the Own Keys for the identities on the 1474 'Requester' device are set as the default for those respective 1475 identities. 1477 A.1.2.6. newChallengeAndNegotiationBase 1479 The newChallengeAndNegotiationBase action is invoked by a device 1480 during an Init event in either the Sole or Grouped state, and serves 1481 to clear and generate a new challenge TID and negotiation state. 1483 A.1.2.7. partnerIsGrouped (conditional) 1485 The partnerIsGrouped conditional evaluates whether a negotiation 1486 partner is already in a Device Group or not, which determines if the 1487 new device will be joining the Device Group or forming a new Device 1488 Group with another device in the Sole state. If this boolean 1489 evaluates true, then the FSM transitions to HandshakingToJoin. If 1490 not, the FSM proceeds with the negotiation process for two Sole 1491 Devices seeking to form a new Device Group. 1493 A.1.2.8. prepareOwnKeys 1495 The prepareOwnKeys action is invoked during the latter phases of the 1496 KeySync protocol for both new and existing Device Group joining 1497 processes. This action indicates to a device that all key 1498 information that has been selected for synchronization should be 1499 prepared for sending to the other negotiation partner. 1501 A.1.2.9. receivedKeysAreDefaultKeys 1503 The receivedKeysAreDefaultKeys action marks the keys received during 1504 Device Group formation as the Default Keys for the respective 1505 identities of the device which sent them. 1507 A.1.2.10. sameChallenge (conditional) 1509 The sameChallenge action compares the challenge TIDs sent in Beacons. 1510 If this boolean evaluates 'true', the received challenge TID 1511 originated from that device, meaning that the received Beacon has 1512 come back to us and we can ignore it. If the boolean evaluates 1513 'false', then the TID comparison takes place and the roles of 1514 'Offerer' and 'Requester' are assigned. The lower of the two numbers 1515 is the 'Requester'. 1517 A.1.2.11. sameNegotiation (conditional) 1519 As with sameChallenge, the sameNegotiation action evaluates 'true' if 1520 the FSM finds a NegotiationRequest message that a Sole Device sent 1521 out is determined to be self-originating. The Transaction ID (TID) 1522 will be an exact match upon comparison, and the NegotiationRequest 1523 will be ignored as a result. 1525 A.1.2.12. sameNegotiationAndPartner (conditional) 1527 The sameNegotiationAndPartner action serves as a session fidelity 1528 check. If this boolean evaluates 'true', it confirms that the pEp 1529 KeySync session in progress is the same throughout, and that the 1530 negotiation partner has not changed. 1532 A.1.2.13. saveGroupKeys 1534 The saveGroupKeys action directs the addition of any keys received 1535 during a KeySync process to a GroupKeys array, along with any 1536 existing Own or Grouped Device Keys. 1538 A.1.2.14. showBeingInGroup 1540 A.1.2.15. showBeingSole 1542 The 'showBeingSole' action in state Sole drives a UI event that can 1543 be used to notify a pEp user that their device is Sole (ungrouped), 1544 and guide the user through creation or joining of a Device Group. 1545 This action also prepares the necessary structures to potentially 1546 initiate KeySync, in the event a Beacon from another device is 1547 received. 1549 A.1.2.16. showDeviceAdded 1551 The 'showDeviceAdded' action drives a UI event that is used to notify 1552 a pEp user that a Sole Device was added to an already existing Device 1553 Group. 1555 A.1.2.17. showGroupCreated 1557 In either role that a Sole Device can assume ('Requester' or 1558 'Offerer'), the action 'showGroupCreated' drives a UI event which 1559 notifies a user that a new Device Group was formed from two Sole 1560 Devices. 1562 A.1.2.18. showGroupedHandshake 1564 The 'showGroupedHandshake' action drives a UI event on a Grouped 1565 device, which a pEp implementer should use to display a pEp Handshake 1566 dialog. This dialog should indicate that there is a new Sole Device 1567 that is requesting to join the Device Group that this Grouped device 1568 belongs to. 1570 A.1.2.19. showJoinGroupHandshake 1572 The 'showJoinGroupHandshake' action drives a UI event on a Sole 1573 Device attempting to join an existing Device Group, and should be 1574 used by pEp implementers to show a Handshake dialog on the Sole 1575 Device. 1577 A.1.2.20. showSoleHandshake 1579 For cases where two Sole Devices are attempting to form a new Device 1580 Group, the showSoleHandshake action drives a UI event which a pEp 1581 implementer should use to display a pEp Handshake dialog to each of 1582 the devices in negotiation. 1584 A.1.2.21. storeNegotiation 1586 The storeNegotiation action saves the received non-own negotiation 1587 information, which is used by the sameNegotiationAndPartner action to 1588 perform a session fidelity check (cf. Appendix A.1.2.11). 1590 A.1.2.22. tellWeAreGrouped 1592 The tellWeAreGrouped action is used by devices already in the Grouped 1593 state. It is sent in a Beacon and indicates to Sole Devices that 1594 they are entering a negotiation with a Grouped device. For the Sole 1595 Device, receiving this action determines which state the FSM will 1596 transition to next. 1598 A.1.2.23. tellWeAreNotGrouped 1600 The 'tellWeAreNotGrouped' action is used by Sole Devices which are 1601 assigned the role of 'Requester' upon challenge TID comparison, and 1602 is sent along with a NegotiationRequest event to indicate to the 1603 'Offerer' device that they are entering into a negotiation request 1604 with a Sole Device. 1606 A.1.2.24. trustThisKey 1608 The trustThisKey action is executed in all states when a user chooses 1609 'Accept' on the Handshake dialog. Trust for the public key from the 1610 negotiation partner is granted so the rest of the KeySync process can 1611 be conducted securely. The trust also extends to the private key 1612 portion of the key pair at later stage in the KeySync process, so 1613 long as the user continues to choose 'Accept' on both devices. If 1614 the process is canceled or rejected at any point after the public key 1615 trust has been granted, that trust will be removed (cf. 1616 Appendix A.1.2.25). 1618 A.1.2.25. untrustThisKey 1620 If the 'Cancel' or 'Reject' options are chosen at any point during 1621 the KeySync process after a negotiation partner's public key has been 1622 trusted, trust on that public key is removed (cf. 1623 Appendix A.1.2.24). The untrustThisKey action ensures that the 1624 negotiation partner's public key can never be attached to messages 1625 sent to outside peers from the recipient device. 1627 A.1.2.26. useOwnChallenge 1629 Once a Beacon is received by a device in either the Sole or Grouped 1630 state, the useOwnChallenge action attaches the device's generated 1631 challenge TID to an outgoing Beacon or NegotiationRequest event for 1632 comparison and session verification purposes. 1634 A.1.3. Transitions 1636 Transitions are changes between states within the FSM, and are 1637 indicated by the 'go' command throughout the code. Please see the 1638 desired State for additional information on why and when these 1639 changes are triggered. 1641 A.2. Messages 1643 [[ TODO ]] 1645 A.2.1. Format 1647 [[ TODO ]] 1649 A.2.2. List of Messages Used in Finite-State Machine 1651 A.2.2.1. Beacon 1653 [[ TODO ]] 1655 Please find more information in the following code excerpt: 1657 message Beacon 2, type=broadcast, security=unencrypted { 1658 field TID challenge; 1659 auto Version version; 1660 } 1662 A.2.2.2. NegotiationRequest 1664 [[ TODO ]] 1666 Please find more information in the following code excerpt: 1668 message NegotiationRequest 3, security=untrusted { 1669 field TID challenge; 1670 auto Version version; 1671 field TID negotiation; 1672 field bool is_group; 1673 } 1675 A.2.2.3. NegotiationOpen 1677 [[ TODO ]] 1679 Please find more information in the following code excerpt: 1681 message NegotiationOpen 4, security=untrusted { 1682 auto Version version; 1683 field TID negotiation; 1684 } 1686 A.2.2.4. Rollback 1688 [[ TODO ]] 1690 Please find more information in the following code excerpt: 1692 message Rollback 5, security=untrusted { 1693 field TID negotiation; 1694 } 1696 A.2.2.5. CommitReject 1698 [[ TODO ]] 1700 Please find more information in the following code excerpt: 1702 message CommitReject 6, security=untrusted { 1703 field TID negotiation; 1704 } 1706 A.2.2.6. CommitAcceptOfferer 1708 [[ TODO ]] 1710 Please find more information in the following code excerpt: 1712 message CommitAcceptOfferer 7, security=untrusted { 1713 field TID negotiation; 1714 } 1716 A.2.2.7. CommitAcceptRequester 1718 [[ TODO ]] 1720 Please find more information in the following code excerpt: 1722 message CommitAcceptRequester 8, security=untrusted { 1723 field TID negotiation; 1724 } 1726 A.2.2.8. CommitAccept 1728 [[ TODO ]] 1730 Please find more information in the following code excerpt: 1732 message CommitAccept 9, security=untrusted { 1733 field TID negotiation; 1734 } 1736 A.2.2.9. CommitAcceptForGroup 1738 [[ TODO ]] 1740 Please find more information in the following code excerpt: 1742 message CommitAcceptForGroup 10, security=untrusted { 1743 field TID negotiation; 1744 } 1746 A.2.2.10. GroupTrustThisKey 1748 [[ TODO ]] 1750 Please find more information in the following code excerpt: 1752 // default: security=trusted only 1753 message GroupTrustThisKey 11 { 1754 field Hash key; 1755 } 1757 A.2.2.11. GroupKeys 1759 [[ TODO ]] 1761 Please find more information in the following code excerpt: 1763 // trust in future 1764 message GroupKeys 12, security=attach_own_keys { 1765 field IdentityList ownIdentities; 1766 } 1768 A.2.2.12. OwnKeysOfferer 1770 [[ TODO ]] 1772 Please find more information in the following code excerpt: 1774 message OwnKeysOfferer 13, security=attach_own_keys { 1775 field IdentityList ownIdentities; 1776 } 1778 A.2.2.13. OwnKeysRequester 1780 [[ TODO ]] 1782 Please find more information in the following code excerpt: 1784 message OwnKeysRequester 14, security=attach_own_keys { 1785 field IdentityList ownIdentities; 1786 } 1788 A.2.3. Example Messages 1790 [[ TODO ]] 1792 Appendix B. Finite-State Machine Code 1794 Below is the full code for the pEp KeySync FSM, including messages 1795 and external events. 1797 fsm KeySync 1, threshold=300 { 1798 version 1, 2; 1800 state InitState { 1801 on Init { 1802 if deviceGrouped 1803 go Grouped; 1804 go Sole; 1805 } 1806 } 1808 state Sole timeout=off { 1809 on Init { 1810 do newChallengeAndNegotiationBase; 1811 do showBeingSole; 1812 send Beacon; 1813 } 1814 on KeyGen { 1815 send Beacon; 1816 } 1818 on CannotDecrypt { // cry baby 1819 send Beacon; 1820 } 1822 on Beacon { 1823 if sameChallenge { 1824 // this is our own Beacon; ignore 1825 } 1826 else { 1827 if weAreOfferer { 1828 do useOwnChallenge; 1829 send Beacon; 1830 } 1831 else /* we are requester */ { 1832 do openNegotiation; 1833 do tellWeAreNotGrouped; 1834 // requester is sending NegotiationRequest 1835 send NegotiationRequest; 1836 do useOwnChallenge; 1837 } 1838 } 1839 } 1841 on NegotiationRequest { 1842 if sameChallenge { // challenge accepted 1843 if sameNegotiation { 1844 // this is our own NegotiationRequest; ignore 1845 } 1846 else { 1847 do storeNegotiation; 1848 // offerer is accepting by 1849 // confirming NegotiationOpen 1850 send NegotiationOpen; 1851 if partnerIsGrouped 1852 go HandshakingToJoin; 1853 else 1854 go HandshakingOfferer; 1855 } 1856 } 1857 } 1859 on NegotiationOpen if sameNegotiationAndPartner { 1860 // requester is receiving NegotiationOpen 1861 do storeNegotiation; 1862 go HandshakingRequester; 1863 } 1864 } 1866 // handshaking without existing Device group 1867 state HandshakingOfferer timeout=600 { 1868 on Init 1869 do showSoleHandshake; 1871 // Cancel is Rollback 1872 on Cancel { 1873 send Rollback; 1874 go Sole; 1875 } 1877 on Rollback if sameNegotiationAndPartner 1878 go Sole; 1880 // Reject is CommitReject 1881 on Reject { 1882 send CommitReject; 1883 do disable; 1884 go End; 1885 } 1887 on CommitReject if sameNegotiationAndPartner { 1888 do disable; 1889 go End; 1890 } 1892 // Accept means init Phase1Commit 1893 on Accept { 1894 do trustThisKey; 1895 send CommitAcceptOfferer; 1896 go HandshakingPhase1Offerer; 1897 } 1899 // got a CommitAccept from requester 1900 on CommitAcceptRequester if sameNegotiationAndPartner 1901 go HandshakingPhase2Offerer; 1902 } 1904 // handshaking without existing Device group 1905 state HandshakingRequester timeout=600 { 1906 on Init 1907 do showSoleHandshake; 1909 // Cancel is Rollback 1910 on Cancel { 1911 send Rollback; 1912 go Sole; 1913 } 1915 on Rollback if sameNegotiationAndPartner 1916 go Sole; 1918 // Reject is CommitReject 1919 on Reject { 1920 send CommitReject; 1921 do disable; 1922 go End; 1923 } 1925 on CommitReject if sameNegotiationAndPartner { 1926 do disable; 1927 go End; 1928 } 1930 // Accept means init Phase1Commit 1931 on Accept { 1932 do trustThisKey; 1933 send CommitAcceptRequester; 1934 go HandshakingPhase1Requester; 1935 } 1937 // got a CommitAccept from offerer 1938 on CommitAcceptOfferer if sameNegotiationAndPartner 1939 go HandshakingPhase2Requester; 1940 } 1942 state HandshakingPhase1Offerer { 1943 on Rollback if sameNegotiationAndPartner { 1944 do untrustThisKey; 1945 go Sole; 1946 } 1948 on CommitReject if sameNegotiationAndPartner { 1949 do untrustThisKey; 1950 do disable; 1951 go End; 1952 } 1954 on CommitAcceptRequester if sameNegotiationAndPartner { 1955 go FormingGroupOfferer; 1956 } 1957 } 1958 state HandshakingPhase1Requester { 1959 on Rollback if sameNegotiationAndPartner { 1960 do untrustThisKey; 1961 go Sole; 1962 } 1964 on CommitReject if sameNegotiationAndPartner { 1965 do untrustThisKey; 1966 do disable; 1967 go End; 1968 } 1970 on CommitAcceptOfferer if sameNegotiationAndPartner { 1971 go FormingGroupRequester; 1972 } 1973 } 1975 state HandshakingPhase2Offerer { 1976 on Cancel { 1977 send Rollback; 1978 go Sole; 1979 } 1981 on Reject { 1982 send CommitReject; 1983 do disable; 1984 go End; 1985 } 1987 on Accept { 1988 send CommitAcceptOfferer; 1989 do trustThisKey; 1990 go FormingGroupOfferer; 1991 } 1992 } 1994 state HandshakingPhase2Requester { 1995 on Cancel { 1996 send Rollback; 1997 go Sole; 1998 } 2000 on Reject { 2001 send CommitReject; 2002 do disable; 2003 go End; 2004 } 2005 on Accept { 2006 send CommitAcceptRequester; 2007 do trustThisKey; 2008 go FormingGroupRequester; 2009 } 2010 } 2012 state FormingGroupOfferer { 2013 on Init { 2014 do prepareOwnKeys; 2015 send OwnKeysOfferer; // not grouped yet, 2016 // this are our own keys 2017 do showFormingGroup; 2018 } 2020 on Cancel { 2021 send Rollback; 2022 go Sole; 2023 } 2025 on Rollback 2026 go Sole; 2028 on OwnKeysRequester { 2029 do saveGroupKeys; 2030 do receivedKeysAreDefaultKeys; 2031 do showGroupCreated; 2032 go Grouped; 2033 } 2034 } 2036 state FormingGroupRequester { 2037 on Init 2038 do showFormingGroup; 2040 on Cancel { 2041 send Rollback; 2042 go Sole; 2043 } 2045 on Rollback 2046 go Sole; 2048 on OwnKeysOfferer { 2049 do saveGroupKeys; 2050 do prepareOwnKeys; 2051 do ownKeysAreDefaultKeys; 2052 send OwnKeysRequester; 2053 do showGroupCreated; 2054 go Grouped; 2055 } 2056 } 2058 state Grouped timeout=off { 2059 on Init { 2060 do newChallengeAndNegotiationBase; 2061 do showBeingInGroup; 2062 } 2064 on GroupKeys 2065 do saveGroupKeys; 2067 on KeyGen { 2068 do prepareOwnKeys; 2069 send GroupKeys; 2070 } 2072 on Beacon { 2073 do openNegotiation; 2074 do tellWeAreGrouped; 2075 send NegotiationRequest; 2076 do useOwnChallenge; 2077 } 2079 on NegotiationOpen if sameNegotiationAndPartner { 2080 do storeNegotiation; 2081 go HandshakingGrouped; 2082 } 2084 on GroupTrustThisKey 2085 do trustThisKey; 2086 } 2088 // sole device handshaking with group 2089 state HandshakingToJoin { 2090 on Init 2091 do showJoinGroupHandshake; 2093 // Cancel is Rollback 2094 on Cancel { 2095 send Rollback; 2096 go Sole; 2097 } 2099 on Rollback if sameNegotiationAndPartner 2100 go Sole; 2102 // Reject is CommitReject 2103 on Reject { 2104 send CommitReject; 2105 do disable; 2106 go End; 2107 } 2109 on CommitAcceptForGroup if sameNegotiationAndPartner 2110 go HandshakingToJoinPhase2; 2112 on CommitReject if sameNegotiationAndPartner { 2113 do disable; 2114 go End; 2115 } 2117 // Accept is Phase1Commit 2118 on Accept { 2119 do trustThisKey; 2120 send CommitAccept; 2121 go HandshakingToJoinPhase1; 2122 } 2123 } 2125 state HandshakingToJoinPhase1 { 2126 on Rollback if sameNegotiationAndPartner 2127 go Sole; 2129 on CommitReject if sameNegotiationAndPartner { 2130 do disable; 2131 go End; 2132 } 2134 on CommitAcceptForGroup if sameNegotiationAndPartner 2135 go JoiningGroup; 2136 } 2138 state HandshakingToJoinPhase2 { 2139 on Cancel { 2140 send Rollback; 2141 go Sole; 2142 } 2144 on Reject { 2145 send CommitReject; 2146 do disable; 2147 go End; 2148 } 2149 on Accept { 2150 do trustThisKey; 2151 go JoiningGroup; 2152 } 2153 } 2155 state JoiningGroup { 2156 on GroupKeys { 2157 do saveGroupKeys; 2158 do receivedKeysAreDefaultKeys; 2159 do prepareOwnKeys; 2160 send GroupKeys; 2161 do showDeviceAdded; 2162 go Grouped; 2163 } 2164 } 2166 state HandshakingGrouped { 2167 on Init 2168 do showGroupedHandshake; 2170 // Cancel is Rollback 2171 on Cancel { 2172 send Rollback; 2173 go Grouped; 2174 } 2176 on Rollback if sameNegotiationAndPartner 2177 go Grouped; 2179 // Reject is CommitReject 2180 on Reject { 2181 send CommitReject; 2182 go Grouped; 2183 } 2185 on CommitReject if sameNegotiationAndPartner 2186 go Grouped; 2188 // Accept is Phase1Commit 2189 on Accept { 2190 do trustThisKey; 2191 send GroupTrustThisKey; 2192 send CommitAcceptForGroup; 2193 go HandshakingGroupedPhase1; 2194 } 2196 on CommitAccept if sameNegotiationAndPartner 2197 go HandshakingGroupedPhase2; 2199 on GroupTrustThisKey { 2200 do hideHandshakeDialog; 2201 do trustThisKey; 2202 } 2204 on GroupKeys 2205 do saveGroupKeys; 2206 } 2208 state HandshakingGroupedPhase1 { 2209 on Rollback if sameNegotiationAndPartner 2210 go Grouped; 2212 on CommitReject if sameNegotiationAndPartner 2213 go Grouped; 2215 on CommitAccept if sameNegotiationAndPartner { 2216 do prepareOwnKeys; 2217 send GroupKeys; 2218 go Grouped; 2219 } 2221 on GroupTrustThisKey { 2222 do trustThisKey; 2223 } 2225 on GroupKeys 2226 do saveGroupKeys; 2227 } 2229 state HandshakingGroupedPhase2 { 2230 on Cancel { 2231 send Rollback; 2232 go Grouped; 2233 } 2235 on Reject { 2236 send CommitReject; 2237 go Grouped; 2238 } 2240 on Accept { 2241 do trustThisKey; 2242 send GroupTrustThisKey; 2243 do prepareOwnKeys; 2244 send GroupKeys; 2245 go Grouped; 2246 } 2248 on GroupTrustThisKey { 2249 do trustThisKey; 2250 } 2252 on GroupKeys 2253 do saveGroupKeys; 2254 } 2256 external Accept 129; 2257 external Reject 130; 2258 external Cancel 131; 2260 // beacons are always broadcasted 2262 message Beacon 2, type=broadcast, security=unencrypted { 2263 field TID challenge; 2264 auto Version version; 2265 } 2267 message NegotiationRequest 3, security=untrusted { 2268 field TID challenge; 2269 auto Version version; 2270 field TID negotiation; 2271 field bool is_group; 2272 } 2274 message NegotiationOpen 4, security=untrusted { 2275 auto Version version; 2276 field TID negotiation; 2277 } 2279 message Rollback 5, security=untrusted { 2280 field TID negotiation; 2281 } 2283 message CommitReject 6, security=untrusted { 2284 field TID negotiation; 2285 } 2287 message CommitAcceptOfferer 7, security=untrusted { 2288 field TID negotiation; 2289 } 2291 message CommitAcceptRequester 8, security=untrusted { 2292 field TID negotiation; 2294 } 2296 message CommitAccept 9, security=untrusted { 2297 field TID negotiation; 2298 } 2300 message CommitAcceptForGroup 10, security=untrusted { 2301 field TID negotiation; 2302 } 2304 // default: security=trusted only 2305 message GroupTrustThisKey 11 { 2306 field Hash key; 2307 } 2309 // trust in future 2310 message GroupKeys 12, security=attach_own_keys { 2311 field IdentityList ownIdentities; 2312 } 2314 message OwnKeysOfferer 13, security=attach_own_keys { 2315 field IdentityList ownIdentities; 2316 } 2318 message OwnKeysRequester 14, security=attach_own_keys { 2319 field IdentityList ownIdentities; 2320 } 2321 } 2323 Appendix C. Document Changelog 2325 [[ RFC Editor: This section is to be removed before publication ]] 2327 o draft-hoeneisen-pep-KeySync-00: 2329 * Initial version 2331 o draft-hoeneisen-pep-KeySync-01: 2333 * Major rewrite of upper sections 2335 * Adjust to reflect code changes 2337 * Move Finite-State Machine reference and code to Appendices A & 2338 B 2340 Appendix D. Open Issues 2342 [[ RFC Editor: This section should be empty and is to be removed 2343 before publication ]] 2345 o Resolve several TODOs / add missing text 2347 LocalWords: Boppart boolean showFormingGroup broadcasted 2349 Authors' Addresses 2351 Bernie Hoeneisen 2352 Ucom Standards Track Solutions GmbH 2353 CH-8046 Zuerich 2354 Switzerland 2356 Phone: +41 44 500 52 40 2357 Email: bernie@ietf.hoeneisen.ch (bernhard.hoeneisen AT ucom.ch) 2358 URI: https://ucom.ch/ 2360 Hernani Marques 2361 pEp Foundation 2362 Oberer Graben 4 2363 CH-8400 Winterthur 2364 Switzerland 2366 Email: hernani.marques@pep.foundation 2367 URI: https://pep.foundation/ 2369 Kelly Bristol 2370 pEp Foundation 2371 Oberer Graben 4 2372 CH-8400 Winterthur 2373 Switzerland 2375 Email: kelly@pep-project.org 2376 URI: https://pep.foundation/