idnits 2.17.1 draft-pep-keysync-02.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 14, 2020) is 1372 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-05 ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Downref: Normative reference to an Informational RFC: RFC 7435 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group V. Birk 3 Internet-Draft B. Hoeneisen 4 Intended status: Standards Track K. Bristol 5 Expires: January 15, 2021 pEp Foundation 6 July 14, 2020 8 pretty Easy privacy (pEp): Key Synchronization Protocol (KeySync) 9 draft-pep-keysync-02 11 Abstract 13 This document describes the pEp KeySync protocol, which is designed 14 to perform secure peer-to-peer synchronization of private keys across 15 devices belonging to the same user. 17 Modern users of messaging systems typically have multiple devices for 18 communicating, and attempting to use encryption on all of these 19 devices often leads to situations where messages cannot be decrypted 20 on a given device due to missing private key data. Current 21 approaches to resolve key synchronicity issues are cumbersome and 22 potentially insecure. The pEp KeySync protocol is designed to 23 facilitate this personal key synchronization in a user-friendly 24 manner. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on January 15, 2021. 43 Copyright Notice 45 Copyright (c) 2020 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (https://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 62 1.2. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.3. Problem Statement . . . . . . . . . . . . . . . . . . . . 5 64 1.4. Main Challenge . . . . . . . . . . . . . . . . . . . . . 5 65 1.5. Approach . . . . . . . . . . . . . . . . . . . . . . . . 5 66 2. General Description . . . . . . . . . . . . . . . . . . . . . 6 67 2.1. Use Cases for pEp KeySync . . . . . . . . . . . . . . . . 6 68 2.1.1. Form Device Group . . . . . . . . . . . . . . . . . . 6 69 2.1.2. Add New Device to Existing Device Group . . . . . . . 7 70 2.1.3. Exchange Private Keys . . . . . . . . . . . . . . . . 7 71 2.1.4. Leave Device Group . . . . . . . . . . . . . . . . . 7 72 2.1.5. Remove other Device from Device Group . . . . . . . . 8 73 2.2. Interaction Diagrams . . . . . . . . . . . . . . . . . . 8 74 2.2.1. Form Device Group . . . . . . . . . . . . . . . . . . 9 75 2.2.2. Add New Device to Existing Device Group . . . . . . . 17 76 2.2.3. Exchange Private Keys . . . . . . . . . . . . . . . . 24 77 2.2.4. Leave Device Group . . . . . . . . . . . . . . . . . 24 78 2.2.5. Remove other Device from Device Group . . . . . . . . 24 79 3. Security Considerations . . . . . . . . . . . . . . . . . . . 24 80 4. Privacy Considerations . . . . . . . . . . . . . . . . . . . 24 81 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 82 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 25 83 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 84 7.1. Normative References . . . . . . . . . . . . . . . . . . 25 85 7.2. Informative References . . . . . . . . . . . . . . . . . 25 86 Appendix A. Reference Implementation . . . . . . . . . . . . . . 26 87 A.1. Description of Finite State Machine . . . . . . . . . . . 26 88 A.1.1. States . . . . . . . . . . . . . . . . . . . . . . . 27 89 A.1.2. Conditions . . . . . . . . . . . . . . . . . . . . . 37 90 A.1.3. Actions . . . . . . . . . . . . . . . . . . . . . . . 38 91 A.1.4. Transitions . . . . . . . . . . . . . . . . . . . . . 44 92 A.1.5. Events . . . . . . . . . . . . . . . . . . . . . . . 44 93 A.1.6. Messages . . . . . . . . . . . . . . . . . . . . . . 46 94 Appendix B. Code excerpts . . . . . . . . . . . . . . . . . . . 48 95 B.1. Finite State Machine . . . . . . . . . . . . . . . . . . 48 96 B.2. ASN.1 Type Definitions . . . . . . . . . . . . . . . . . 63 97 Appendix C. Document Changelog . . . . . . . . . . . . . . . . . 64 98 Appendix D. Open Issues . . . . . . . . . . . . . . . . . . . . 64 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 64 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 single 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] 139 Note: In pEp KeySync, the Handshake is used to authenticate own 140 devices (the user normally compares the Trustwords directly by 141 looking at the screens of the devices involved). 143 o Trustwords: A scalar-to-word representation of 16-bit numbers (0 144 to 65535) to natural language words. When doing a Handshake, 145 peers are shown combined Trustwords of both public keys involved 146 to ease the comparison. [I-D.birk-pep-trustwords] 148 o Trust On First Use (TOFU): cf. [RFC7435], which states: "In a 149 protocol, TOFU calls for accepting and storing a public key or 150 credential associated with an asserted identity, without 151 authenticating that assertion. Subsequent communication that is 152 authenticated using the cached key or credential is secure against 153 an MiTM attack, if such an attack did not succeed during the 154 vulnerable initial communication." 156 o Man-in-the-middle (MITM) attack: cf. [RFC4949], which states: "A 157 form of active wiretapping attack in which the attacker intercepts 158 and selectively modifies communicated data to masquerade as one or 159 more of the entities involved in a communication association." 161 o Identity: The combination of a unique user identifier plus a 162 specific address (email, network ID, URI, etc.). A single user 163 may have multiple identities. See also [RFC4949]. 165 o Device Group: All of a user's devices which have successfully 166 completed the KeySync process, and are now configured to share 167 user data, such as cryptographic keys, trust information, 168 calendars, configurations, and other data as a result of that 169 process. This data is synchronized through a common channel for a 170 given identity. For example, if a user's identity is tied to a 171 specific email address, the common channel for this identity could 172 be an inbox. 174 o Sole Device: A device which is not part of a Device Group. 176 o Grouped Device: A device which is already part of a Device Group. 178 o Beacon (message): A technical text message that is broadcast by 179 Sole Devices and transmitted through a message sent to the channel 180 of an identity. Other Sole Devices, or a Grouped Device of the 181 same unique identity and using that identity's channel, can 182 interpret this Beacon in order to initiate negotiation for the 183 formation of a Device Group. 185 o Transaction ID (TID): A UUID version 4, variant 1 number generated 186 by each device during the pEp KeySync process in order to identify 187 the respective devices involved. 189 o Default Key: A key which is actually used for a given identity. 191 o Own Key: A Default Key for an own identity. 193 1.3. Problem Statement 195 Secure and private digital communication is becoming a necessity for 196 many people. Encryption protocols which utilize key pairs are the 197 most popular and easily implemented methods to ensure a message is 198 authentic and can be trusted. 200 However, most modern users have multiple devices for communicating, 201 and attempting to use encryption on all of these devices often leads 202 to situations where messages cannot be decrypted on a given device 203 due to missing private key data. For example, Alice sends an 204 encrypted message to Bob, using the public key of a key pair that Bob 205 generated on his laptop. When Bob attempts to decrypt the message on 206 his mobile phone, the private key that he generated on his laptop is 207 not available. As a result, Bob must either use his laptop to 208 decrypt the message, or attempt to copy the correct private key to 209 his mobile device, which may expose his private key to potential 210 leaks or theft. 212 1.4. Main Challenge 214 The main challenge that pEp KeySync is designed to overcome is to 215 perform the synchronization in a secure manner so that private keys 216 are not leaked or exposed to theft. 218 Note: The case of an adversary getting physical access to the device 219 itself is beyond the scope of this document. 221 1.5. Approach 223 The basic approach to solving the multiple-device decryption problem 224 is to synchronize private keys among the devices of a user in a 225 secure manner. pEp achieves this by giving users the option to form a 226 Device Group with their devices. When the user initiates this 227 process, a Handshake occurs, and the user is presented with a 228 Trustwords dialog for pairing purposes. (cf. 229 [I-D.birk-pep-trustwords]) Simply put, the user MUST complete this 230 Trustwords dialog before the automatic and security-sensitive 231 transfer of private key information can occur. 233 2. General Description 235 The pEp KeySync protocol allows a user to securely synchronize 236 private key data for multiple identities across their various 237 devices. This synchronization process is decentralized and performed 238 as a two-phase commit protocol structure (2PC). This structure 239 ensures consensus among the devices at all stages of the KeySync 240 process. 242 KeySync's 2PC transaction is accomplished through the implementation 243 of a Finite State Machine (FSM) on each pEp-enabled device. This FSM 244 not only sends and receives network traffic, which allows devices to 245 communicate with each other throughout the KeySync process, but also 246 interacts with the pEp engine itself. 248 Once activated by the user, pEp KeySync initiates the formation of a 249 Device Group, and the user is guided through a Handshake process on 250 their respective devices. A user can choose to reject or cancel this 251 process at any time, from either device, and private key data is not 252 exchanged until the group formation process is verified on both 253 devices. 255 Once a Device Group is formed, a user can add additional devices to 256 their group through the same joining procedure. Upon adding the new 257 device to the existing Device Group, key data is synchronized among 258 all Grouped Devices, allowing a user to communicate privately from 259 any of their secure identities. 261 2.1. Use Cases for pEp KeySync 263 This section describes ideal-condition use cases for pEp KeySync. 264 The focus is on the core procedures and on the scenarios where 265 everything works. Unexpected user behavior, error handling, race 266 conditions, etc., are generally omitted from this section in order to 267 focus on the general concepts of pEp KeySync. Additional use cases 268 will be discussed in further detail throughout Appendix A. 270 2.1.1. Form Device Group 272 Our user, Alice, has two devices that are configured with pEp- 273 implementing messaging clients and share the same identity for her 274 preferred communication channel. In our example, this communication 275 channel is the inbox for a specific email address, alice@example.org, 276 which Alice has configured on each device. Let us call these devices 277 Alice_Mobile and Alice_Tablet. Each device already has its own 278 dedicated key pair, which was automatically generated by the pEp 279 protocol when Alice configured her email inbox on her respective 280 devices. 282 When Alice sends an email from Alice_Mobile, it is encrypted by the 283 key for that specific device, as are any replies she might receive. 284 If she wishes to read that email (or replies to it) on Alice_Tablet, 285 she is unable to do so because the key pair for Alice_Tablet is 286 different. Alice wants to read all of her encrypted communications 287 on both of her devices, but currently cannot do so, as the devices do 288 not have any secure, established connection to each other and thus 289 cannot share key pair data without compromising her privacy. Alice 290 will use pEp KeySync to form a Device Group and add her devices to 291 it. pEp KeySync provides a secure connection for Alice to exchange 292 private key data among her devices, which will allow her to have full 293 access to all of her encrypted messages on both devices. 295 2.1.2. Add New Device to Existing Device Group 297 Sometime after devices Alice_Mobile and Alice_Tablet have formed a 298 Device Group (cf. Section 2.1.1), Alice buys another device, 299 Alice_Laptop, which is also configured with pEp-implementing 300 messaging clients and shares the same identity for her preferred 301 communication channel (the aforementioned email address). 302 Alice_Laptop also has a key pair, which was automatically generated 303 by the pEp protocol, just as the Grouped Devices Alice_Mobile and 304 Alice_Tablet have. But while the Grouped Devices know each other and 305 have exchanged private keys, Alice_Laptop and the Grouped Devices 306 don't have any connection to each other. Thus, Alice does not have 307 full, encrypted communication capability across the three devices. 309 As before with devices Alice_Mobile and Alice_Tablet, Alice will use 310 pEp KeySync to add device Alice_Laptop to the existing Device Group, 311 allowing all three devices to exchange private key information, and 312 Alice to have full access to her messages from any of them. 314 2.1.3. Exchange Private Keys 316 All devices from Alice are part of a Device Group (cf. Section 2.1.1 317 and Section 2.1.2). However, as keys may expire or get reset, it is 318 inevitable that new key pairs will be generated. For Alice to 319 maintain her ability to read all encrypted messages on all devices, 320 any new private key needs to be shared with the other devices in the 321 device group. All devices in Alice's Device Group will share the 322 latest private keys as they are generated, keeping all of her devices 323 up to date and functioning as desired. 325 2.1.4. Leave Device Group 327 Alice decides that her mobile phone, Alice_Mobile, should no longer 328 have access to all private keys of the Device Group. Alice can 329 manually tell her mobile phone to leave the Device Group by turning 330 off the pEp Sync feature on her device, which deactivates KeySync. 331 The Device Group is dissolved, and Sync is disabled on her mobile 332 phone. This action also initiates the pEp KeyReset protocol, which 333 resets keys for all own identities. 335 In the future, if Alice desires, she can re-add her mobile phone to a 336 Device Group, but she will first have to re-enable Sync, and then 337 initiate the joining procedure again (cf. Section 2.1.1 and 338 Section 2.1.2). 340 2.1.5. Remove other Device from Device Group 342 One of Alice's devices may be stolen or become otherwise compromised. 343 She needs to ensure that the affected device no longer receives 344 updates to private keys from the other devices in her Device Group. 345 Using one of her remaining Grouped Devices, Alice can disable pEp 346 Sync (and thus KeySync) on her remaining devices. This action 347 dissolves the Device Group and initiates the pEp KeyReset protocol. 349 2.2. Interaction Diagrams 351 The following interaction diagrams depict what happens during Alice's 352 KeySync scenarios in a simplified manner. For each scenario, we 353 first present a successful case, then an unsuccessful case and, 354 finally, a case that has been interrupted, or discontinued. Some 355 details are skipped here for the sake of readability. Descriptions 356 of the interactions are included after each diagram. 358 Each pEp-enabled device runs its own Finite State Machine (FSM), 359 which interact with each other throughout the KeySync process, and 360 drive the UI options presented to Alice (the 'User' in all diagrams, 361 unless otherwise noted). All messages are 'broadcast' between 362 devices. The TIDs added to each message allow the identification of 363 received messages which pertain to the ongoing transaction and the 364 device which sent it. 366 For events requiring Alice's interaction in order to proceed, it does 367 not matter which device has the specified option chosen first unless 368 otherwise indicated. For example, if an event states that Alice must 369 choose 'Accept' on the 'Offerer' device in order to continue, the 370 process will be unaffected if she does so on the 'Requester' device 371 first. The only difference is that the order of the roles for the 372 remainder of the given scenario will be swapped. 374 2.2.1. Form Device Group 376 2.2.1.1. Successful Case 378 ,-. 379 `-' 380 /|\ 381 | 382 ,----------------. / \ ,------------------. 383 |'Offerer' device| User |'Requester' device| 384 `-------+--------' | `--------+---------' 385 | | | 386 | | | 387 | 1(r). Beacon (challenge TID) | 388 |<--------------------------------------------| 389 | | | 390 | 1(o). Beacon (challenge TID) | 391 |-------------------------------------------->| 392 | | | 393 | 2. NegotiationRequest | 394 |<--------------------------------------------| 395 | | | 396 | | 3. Display Trustwords| 397 | |<- - - - - - - - - - -| 398 | | | 399 | 4. NegotiationOpen | 400 |-------------------------------------------->| 401 | | | 402 | 5. Display Trustwords| | 403 | - - - - - - - - - - >| | 404 | | | 405 | ,-----------------------------. | 406 | |Handshake (user comparison | | 407 | |of Trustwords) successful | | 408 | `-----------------------------' | 409 | | | 410 ,-----------------------------------. | 411 |User presses 'Accept' button | | 412 |on 'Requester' device | | 413 `-----------------------------------' | 414 | | 6. Accept | 415 | | - - - - - - - - - - >| 416 | | | 417 | 7. CommitAcceptRequester | 418 |<--------------------------------------------| 419 | | | 420 | | | 421 ,-----------------------------------. | 422 |User presses 'Accept' button | | 423 |on 'Offerer' device | | 424 `-----------------------------------' | 425 | 8. Accept | | 426 |<- - - - - - - - - - -| | 427 | | | 428 | 9. CommitAcceptOfferer | 429 |-------------------------------------------->| 430 | | | 431 | 10. OwnKeysRequester + keys | 432 |<--------------------------------------------| 433 | | | 434 ,--------------------. | | 435 |Offerer is Grouped | | | 436 `--------------------' | | 437 | | | 438 | 11. OwnKeysOfferer + keys | 439 |-------------------------------------------->| 440 | | | 441 | | ,----------------------. 442 | | |Requester is Grouped | 443 | | `----------------------' 444 | | | 445 | | | 446 ,-------+--------. | ,--------+---------. 447 |'Offerer' device| User |'Requester' device| 448 `----------------' ,-. `------------------' 449 `-' 450 /|\ 451 | 452 / \ 454 As depicted above, our user, Alice, intends to form a Device Group in 455 order to securely share key material between her devices. The group 456 is formed by an 'Offerer' device and a 'Requester' device. The names 457 'Offerer' and 'Requester' are derived from the FSM (cf. 458 Appendix A.1), in which the device roles are defined during the start 459 sequence, which is necessary for the FSM to work as intended. 461 During initialization of pEp KeySync, each device generates a 462 Transaction-ID (TID). These TIDs are sent as a Challenge in a Beacon 463 over the mutual channel, and the device roles of 'Offerer' and 464 'Requester' are determined by the numeric value of each device's 465 unique TID. 467 1. Every device sends a Beacon message containing a Challenge TID. 468 Upon receipt of a Beacon message from another device, the 469 received Challenge TID is compared with the device's own 470 Challenge TID. The device which has a TID with a lower 471 numerical value is assigned as the 'Requester', and the other 472 device is automatically assigned as the 'Offerer'. 474 Note: The 'Offerer' device MUST NOT start a negotiation. In the 475 event the earlier Beacon message is lost, the 'Offerer' device 476 re-sends its own Beacon and waits for a response. Message 1(r) 477 depicts the Beacon message sent by the 'Requester' device and is 478 not required for the process to continue. 480 2. After determination of the role, the 'Requester' device sends a 481 NegotiationRequest message. 483 3. The 'Requester' device displays the Trustwords to Alice. 485 4. Upon receipt of the NegotiationRequest message, the 'Offerer' 486 device sends a NegotiationOpen message. 488 5. The 'Offerer' device displays the Trustwords to Alice. 490 6. Alice compares the Trustwords of both devices. As the 491 Trustwords are the same on both devices, she chooses the 492 'Accept' option on the 'Requester' device. 494 Note: Alice may choose 'Accept' on the 'Offerer' device first, 495 in which case the sequence of the messages is slightly different 496 (i.e. message 8 is sent before message 6). However, the result 497 will be exactly the same. 499 7. On receipt of Alice's 'Accept' from the 'Offerer' device, the 500 'Requester' device sends a CommitAcceptRequester message. 502 The 'Offerer' device receives this message and waits for Alice 503 to choose 'Accept'. 505 8. Alice compares the Trustwords of both devices and chooses the 506 'Accept' option on the 'Offerer' device. 508 9. Once Alice chooses 'Accept', the 'Offerer' device sends a 509 CommitAcceptOfferer message. 511 10. Upon receipt of the CommitAcceptOfferer message, the 'Requester' 512 device sends an OwnKeysRequester message along with Alice's 513 local key pairs (private and public keys) to be synchronized. 515 11. Upon receipt of the OwnKeysRequester message, the 'Offerer' 516 device saves the 'Requester' device keys and combines them with 517 the existing 'Offerer' device keys. This means that the 518 'Offerer' device is grouped. 520 The 'Offerer' device sends an OwnKeysOfferer message along with 521 its own existing local key pairs (private and public keys) to be 522 synchronized. 524 Upon receipt of the OwnKeysOfferer message, the 'Requester' 525 device saves the 'Offerer' keys combined with the 'Requester' 526 keys. This means that the 'Requester' device is also grouped. 528 The formation of the Device Group has been successful. 530 2.2.1.2. Unsuccessful Case 532 ,-. 533 `-' 534 /|\ 535 | 536 ,----------------. / \ ,------------------. 537 |'Offerer' device| User |'Requester' device| 538 `-------+--------' | `--------+---------' 539 | | | 540 | | | 541 ,--------------------------------------------------------------!. 542 |Messages (1-5) are same as in the successful case (see above) |_\ 543 `----------------------------------------------------------------' 544 | | | 545 | | | 546 | ,-----------------------------. | 547 | |Handshake (user comparison | | 548 | |of Trustwords) unsuccessful | | 549 | `-----------------------------' | 550 | ,------------------------------------. 551 | |User presses 'Reject' button | 552 | |on 'Requester' device | 553 | `------------------------------------' 554 | | R6. Reject | 555 | | - - - - - - - - - - >| 556 | | | 557 | R7. CommitReject | 558 |<-------------------------------------------| 559 | | | 560 ,--------------------------------------------------------------!. 561 | Devices (still not grouped) will not try again |_\ 562 `----------------------------------------------------------------' 563 | | | 564 ,-------+--------. | ,--------+---------. 565 |'Offerer' device| User |'Requester' device| 566 `----------------' ,-. `------------------' 567 `-' 568 /|\ 569 | 570 / \ 572 For unsuccessful KeySync attempts, messages 1-5 are the same as in a 573 successful attempt (see above), but once the Trustwords are shown, 574 events are as follows: 576 R6. Our user, Alice, compares the Trustwords of both devices. As the 577 Trustwords do not match, she chooses the 'Reject' option on the 578 'Requester' device. 580 Note: The user may choose 'Reject' on the 'Offerer' device, in 581 which case the origin and/or destination of the messages 582 change. However, the result will be exactly the same. 584 R7. Once Alice chooses the 'Reject' option, the 'Requester' device 585 sends a CommitReject message to the 'Offerer' device. 587 Once the CommitReject message is sent and received by the respective 588 devices, they cannot form a Device Group, and pEp KeySync is disabled 589 on both devices. As a result, there are no further attempts to form 590 a Device Group involving either of these two devices. KeySync may be 591 re-enabled in the pEp settings on the affected device(s). 593 2.2.1.3. Discontinuation Case 595 ,-. 596 `-' 597 /|\ 598 | 599 ,----------------. / \ ,------------------. 600 |'Offerer' device| User |'Requester' device| 601 `-------+--------' | `--------+---------' 602 | | | 603 | | | 604 ,--------------------------------------------------------------!. 605 |Messages (1-5) are same as in the successful case (see above) |_\ 606 `----------------------------------------------------------------' 607 | | | 608 | | | 609 | ,-----------------------------. | 610 | |Handshake (user comparison | | 611 | |of Trustwords) discontinued | | 612 | `-----------------------------' | 613 | ,------------------------------------. 614 | |User presses 'Cancel' button | 615 | |on 'Requester' device | 616 | `------------------------------------' 617 | | C6. Cancel | 618 | | - - - - - - - - - - >| 619 | | | 620 | C7. Rollback | 621 |<-------------------------------------------| 622 | | | 623 ,--------------------------------------------------------------!. 624 | Devices (still not grouped) will try again |_\ 625 `----------------------------------------------------------------' 626 | | | 627 ,-------+--------. | ,--------+---------. 628 |'Offerer' device| User |'Requester' device| 629 `----------------' ,-. `------------------' 630 `-' 631 /|\ 632 | 633 / \ 635 For discontinued (canceled) KeySync attempts, messages 1-5 are the 636 same as in a successful attempt (see above), but once the Trustwords 637 are shown, events are as follows: 639 C6. Our user, Alice, decides to discontinue the process and chooses 640 the 'Cancel' option on the 'Requester' device. 642 Note: The user may choose 'Cancel' on the 'Offerer' device, in 643 which case the origin and/or destination of the messages 644 change. However, the result will be exactly the same. 646 C7. Once Alice chooses the 'Cancel' option, the 'Requester' device 647 sends a rollback message to the 'Offerer' device. 649 The devices do not form a Device Group. KeySync remains enabled on 650 both devices, and Alice can attempt to form a Device Group again. 652 2.2.2. Add New Device to Existing Device Group 654 2.2.2.1. Successful Case 656 ,-------. ,-. 657 |New | `-' ,--------. ,--------. 658 |device | /|\ |Active | |Passive | 659 |to join| | |device | |devices | 660 |group | / \ |in group| |in group| 661 `---+---' User `---+----' `---+----' 662 | | | | 663 | | | | 664 | 1. Beacon | | 665 |--------------------------------->|------------------>| 666 | | | | 667 | 2(w). NegotiationRequestGrouped | | 668 |<---------------------------------| | 669 | | | | 670 | 2(l). NegotiationRequestGrouped (discarded) | 671 |<-----------------------------------------------------| 672 | | | | 673 | 3. NegotiationOpen | | 674 |--------------------------------->| | 675 | 4. Display | | | 676 | Trustwords | | | 677 | - - - - - - - >| | | 678 | | | 5. GroupHandshake | 679 | | 6(w). Display |------------------>| 680 | | Trustwords | | 681 | |<- - - - - - - - | | 682 | | | | 683 | | 6(l) Display Trustwords | 684 | |<- - - - - - - - - - - - - - - - - - | 685 | | | | 686 | ,-----------------------------. | | 687 | |Handshake (user comparison | | | 688 | |of Trustwords) successful | | | 689 | `-----------------------------' | | 690 | | | | 691 | ,------------------------------. | 692 | |User presses 'Accept' button | | 693 | |on a device in group | | 694 | `------------------------------' | 695 | | 7. Accept | | 696 | | - - - - - - - ->| | 697 | | | 8. GroupTrust | 698 | | | ThisKey | 699 | | |------------------>| 700 | | | | 701 | 9. CommitAcceptForGroup | | 702 |<---------------------------------| | 703 | | | | 704 ,------------------------------. | | 705 |User presses 'Accept' button | | | 706 |on new device | | | 707 `------------------------------' | | 708 | 10. Accept | | | 709 |<- - - - - - - -| | | 710 | | | | 711 | 11. CommitAccept | | 712 |--------------------------------->| | 713 | | | | 714 | 12. GroupKeysForNewMember (key data) | 715 |<---------------------------------| | 716 | | | | 717 ,------------. | | | 718 |New device | | | | 719 |is grouped | | | | 720 `------------' | | | 721 | | | | 722 | 13. GroupKeysAndClose (key data) | | 723 |--------------------------------->| | 724 | | | | 725 | | ,------------. | 726 | | |New device | | 727 | | |is accepted | | 728 | | `------------' | 729 | | | | 730 | 13. GroupKeysAndClose (key data) | 731 |----------------------------------------------------->| 732 | | | | 733 | | | ,------------. 734 | | | |New device | 735 | | | |is accepted | 736 | | | `------------' 737 | | | | 738 ,---+---. User ,---+----. ,---+----. 739 |New | ,-. |Active | |Passive | 740 |device | `-' |device | |devices | 741 |to join| /|\ |in group| |in group| 742 |group | | `--------' `--------' 743 `-------' / \ 745 As depicted above, our user, Alice, intends to add a new device to 746 her existing Device Group. 748 1. When Alice initializes the pEp KeySync process, the new device 749 sends a Beacon message. 751 2. Upon receipt of a Beacon message from this new, ungrouped 752 device, all Grouped Devices in Alice's existing Device Group 753 send a NegotiationRequestGrouped message to the New Device. 755 Note: Messages 2(w) and 2(l) are instances of the same 756 (NegotiationRequestGrouped) message type sent from the Grouped 757 Devices. Only the first NegotiationRequestGrouped message 758 received by the New Device is acknowledged. In this example, 759 2(w) (the "winner") is processed, while message 2(l) (the 760 "loser") will be ignored and discarded. The result will be the 761 same, no matter which NegotiationRequestGrouped message is 762 processed first. 764 3. Upon receipt of the NegotiationRequestGrouped message 2(w), the 765 New Device answers with a NegotiationOpen message to the device 766 that issued the "winning" NegotiationRequestGrouped message. 768 4. The New Device displays the Trustwords to Alice. 770 5. Upon receipt of the NegotiationOpen message, the "winner" device 771 sends a GroupHandshake message to the "loser" device(s), in 772 order to activate the Trustwords dialog on all Grouped Devices. 774 6. All Grouped Devices display the Trustwords to the user. 776 Note: Messages 6(w) and 6(l) are instances of the same action on 777 different devices. 779 7. Alice compares the Trustwords of all devices and chooses the 780 'Accept' option on any of the Grouped Devices. 782 Note 1: The Grouped Device that Alice chooses the 'Accept' 783 option on assumes the role of the Active Device for the 784 remainder of the KeySync process, while the other device(s) in 785 the Device Group are assigned the passive role. 787 Note 2: Alice may choose 'Accept' on the new device first, in 788 which case sequence of the messages is slightly different (i.e. 789 message 10 is sent before message 7). However, the result will 790 be exactly the same. 792 8. Once Alice chooses the 'Accept' option, the Active Device sends 793 a GroupTrustThisKey message to the Passive Device(s) in the 794 existing Device Group. 796 9. The Active Device also sends a CommitAcceptForGroup message to 797 the new device. Upon receipt, the New Device waits for Alice to 798 choose 'Accept'. 800 10. Alice compares the Trustwords on both the New Device and the 801 Active Device, then chooses the 'Accept' option on the new 802 device. 804 11. Once Alice chooses 'Accept', the New Device sends a CommitAccept 805 message to the Active Device. 807 12. Upon receipt of the CommitAccept message, the Active Device 808 device sends a GroupKeysForNewMember message to the New Device, 809 along with Alice's local key pairs (private and public keys) for 810 synchronization. 812 13. The New Device receives the GroupKeysForNewMember message and 813 saves the received keys combined with its own keys. The new 814 device has successfully joined the Device Group. 816 The New Device sends a GroupKeysAndClose message to all devices 817 in the Device Group, along with its own original local key pairs 818 (private and public keys) for synchronization. 820 Note: In the diagram, all messages marked "13. 821 GroupKeysAndClose (key data)" are a single message, but drawn 822 separately in order to convey that the message is sent to all 823 devices in the Device Group. 825 Upon receipt of the GroupKeysAndClose message from the New 826 Device, the Active and Passive Devices save the New Device keys 827 and combine them with their own keys. All keys are now 828 synchronized among the devices. 830 Note: There is no Event Handler to process the GroupKeysAndClose 831 message explicitly, as all decryptable messages containing keys 832 are implicitly processed and the received keys saved. 834 [[ TODO: Decide whether the implicit importing keys should 835 rather be replaced by explicit actions in Event Handlers. ]] 837 2.2.2.2. Unsuccessful 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-6) are same as in the successful case (see above) |_\ 849 `-----------------------------------------------------------------' 850 | | | | 851 | | | | 852 | ,-----------------------------. | | 853 | |Handshake (user comparison | | | 854 | |of Trustwords) unsuccessful | | | 855 | `-----------------------------' | | 856 | ,------------------------------. | 857 | |User presses 'Reject' button | | 858 | |on a device in group | | 859 | `------------------------------' | 860 | | R7. Reject | | 861 | | - - - - - - - ->| | 862 | | | | 863 | R8. CommitReject | | 864 |<---------------------------------|------------------>| 865 | | | | 866 ,----------!. | | | 867 |New device|_\ | | | 868 |(still not | | | | 869 |grouped) | | | | 870 |will not | | | | 871 |try again | | | | 872 `------------' | | | 873 | | | | 874 ,---+---. User ,---+----. ,---+----. 875 |New | ,-. |Active | |Passive | 876 |device | `-' |device | |devices | 877 |to join| /|\ |in group| |in group| 878 |group | | `--------' `--------' 879 `-------' / \ 881 For unsuccessful KeySync attempts, messages 1-6 are the same as in a 882 successful attempt (see above), but once the Trustwords are shown, 883 events are as follows: 885 R7. Our user, Alice, compares the Trustwords displayed on both 886 devices. If the Trustwords do not match, she chooses the 887 'Reject' option on one of the Grouped Devices (which becomes 888 the Active Device). 890 Note: Alice may choose 'Reject' on the new device, in which 891 case the origin and/or destination of the messages 892 change. However, the result will be exactly the same. 894 R8. Upon receipt of the 'Reject' event, the Active Device sends 895 a CommitReject message to both the New Device which attempted to 896 join, and the Passive Device(s) in the Device Group. 898 Note: In the diagram, "R8. CommitReject" represents the message 899 that is sent to all devices participating in the handshake. 901 Once the CommitReject message is sent and received by the respective 902 devices, they cannot form a Device Group, and pEp KeySync is disabled 903 on the New Device. pEp KeySync may be re-enabled in the pEp settings 904 on the affected device. 906 2.2.2.3. Discontinuation Case 908 ,-------. ,-. 909 |New | `-' ,--------. ,--------. 910 |device | /|\ |Active | |Passive | 911 |to join| | |device | |devices | 912 |group | / \ |in group| |in group| 913 `---+---' User `---+----' `---+----' 914 | | | | 915 | | | | 916 ,---------------------------------------------------------------!. 917 |Messages (1-6) are same as in the successful case (see above) |_\ 918 `-----------------------------------------------------------------' 919 | | | | 920 | | | | 921 | ,-----------------------------. | | 922 | |Handshake (user comparison | | | 923 | |of Trustwords) discontinued | | | 924 | `-----------------------------' | | 925 | ,------------------------------. | 926 | |User presses 'Cancel' button | | 927 | |on a device in group | | 928 | `------------------------------' | 929 | | C7. Cancel | | 930 | | - - - - - - - ->| | 931 | | | | 932 | C8. Rollback | | 933 |<---------------------------------|------------------>| 934 | | | | 935 ,----------!. | | | 936 |New device|_\ | | | 937 |(still not | | | | 938 |grouped) | | | | 939 |will try | | | | 940 |again | | | | 941 `------------' | | | 942 | | | | 943 ,---+---. User ,---+----. ,---+----. 944 |New | ,-. |Active | |Passive | 945 |device | `-' |device | |devices | 946 |to join| /|\ |in group| |in group| 947 |group | | `--------' `--------' 948 `-------' / \ 950 For discontinued (canceled) KeySync attempts, messages 1-6 are the 951 same as in a successful attempt (see above), but once the Trustwords 952 are shown, events are as follows: 954 C7. Our user, Alice, decides to discontinue the process and chooses 955 the 'Cancel' option on one of the Grouped Devices (which becomes 956 the Active Device). 958 Note: Alice may choose 'Cancel' on the New Device, in which 959 case the origin and/or destination of the messages 960 change. However, the result will be the same. 962 C8. When Alice chooses 'Cancel', the Active Device sends a Rollback 963 message to both the New Device and any Passive Devices in the 964 Device Group. 966 Note: In the diagram, all messages marked "C8. Rollback" 967 represents the message that is sent to all devices participating 968 in the handshake. 970 The new device does not join the Device Group. KeySync remains 971 enabled and joining a Device Group can start again at any time. 973 2.2.3. Exchange Private Keys 975 [[ TODO ]] 977 2.2.4. Leave Device Group 979 [[ TODO ]] 981 2.2.5. Remove other Device from Device Group 983 [[ TODO ]] 985 3. Security Considerations 987 [[ TODO ]] 989 4. Privacy Considerations 991 [[ TODO ]] 993 5. IANA Considerations 995 This document has no actions for IANA. 997 6. Acknowledgments 999 The authors would like to thank the following people who provided 1000 substantial contributions, helpful comments or suggestions for this 1001 document: Berna Alp, Claudio Luck, Damian Rutz, Damiano Boppart, 1002 Hernani Marques, Itzel Vazquez Sandoval, Krista Bennett, Nana 1003 Karlstetter, and Sofia Balicka. 1005 This work was initially created by pEp Foundation, and then reviewed 1006 and extended with funding by the Internet Society's Beyond the Net 1007 Programme on standardizing pEp. [ISOC.bnet] 1009 7. References 1011 7.1. Normative References 1013 [I-D.birk-pep] 1014 Birk, V., Marques, H., and B. Hoeneisen, "pretty Easy 1015 privacy (pEp): Privacy by Default", draft-birk-pep-05 1016 (work in progress), November 2019. 1018 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1019 Requirement Levels", BCP 14, RFC 2119, 1020 DOI 10.17487/RFC2119, March 1997, 1021 . 1023 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1024 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1025 . 1027 [RFC7435] Dukhovni, V., "Opportunistic Security: Some Protection 1028 Most of the Time", RFC 7435, DOI 10.17487/RFC7435, 1029 December 2014, . 1031 7.2. Informative References 1033 [I-D.birk-pep-trustwords] 1034 Hoeneisen, B. and H. Marques, "IANA Registration of 1035 Trustword Lists: Guide, Template and IANA Considerations", 1036 draft-birk-pep-trustwords-05 (work in progress), January 1037 2020. 1039 [I-D.marques-pep-handshake] 1040 Marques, H. and B. Hoeneisen, "pretty Easy privacy (pEp): 1041 Contact and Channel Authentication through Handshake", 1042 draft-marques-pep-handshake-05 (work in progress), July 1043 2020. 1045 [ISOC.bnet] 1046 Simao, I., "Beyond the Net. 12 Innovative Projects 1047 Selected for Beyond the Net Funding. Implementing Privacy 1048 via Mass Encryption: Standardizing pretty Easy privacy's 1049 protocols", June 2017, . 1053 Appendix A. Reference Implementation 1055 [[ Note: The full Finite State Machine code can be found in 1056 Appendix B.1. This section is not a complete reference at this time. 1057 The authors intend to refine this section in future revisions of this 1058 document. ]] 1060 The pEp KeySync Finite State Machine is based on a two-phase commit 1061 protocol (2PC) structure. This section describes the states, 1062 actions, events, and messages which comprise the pEp KeySync FSM, and 1063 are intended to allow readers to understand the general functionality 1064 and message flow of the FSM. 1066 States are used to direct actions, events, and messages. Actions 1067 describe internal FSM functions, and fall into two general types. 1068 The first action type directs the state transitions within the FSM, 1069 and the second type drives UI functionality. Events are exchanged 1070 both between negotiation partners as well as the pEp engine itself to 1071 trigger actions and send messages. Messages contain information to 1072 ensure the integrity of the KeySync session as well as additional 1073 data, depending on the type of message (cf. Appendix A.1.6). 1075 A.1. Description of Finite State Machine 1077 A full diagram of the implemented pEp KeySync FSM can be found at the 1078 following URL: 1080 https://gitea.pep.foundation/pEp.foundation/internet- 1081 drafts/raw/branch/master/misc/doc/figures/sync/sync_fsm_full.svg 1083 For convenience (better readability), there is also a simplified 1084 diagram of the implemented pEp KeySync FSM, which does not contain 1085 the transitions that occur when choosing the 'Cancel' or 'Reject' 1086 options. The simplified diagram can be found at the following URL: 1088 https://gitea.pep.foundation/pEp.foundation/internet- 1089 drafts/raw/branch/master/misc/doc/figures/sync/ 1090 sync_fsm_simplified.svg 1092 A.1.1. States 1094 A.1.1.1. InitState 1096 On initialization, the FSM enters InitState, which evaluates and 1097 determines a device's group status. If the device is detected to 1098 belong to a Device Group, it issues a SynchronizeGroupKeys message to 1099 the Grouped Devices (to request an update on the Group Keys), and the 1100 FSM transitions to state Grouped. Otherwise, the FSM transitions to 1101 state Sole (cf. Appendix A.1.2.1). 1103 A.1.1.2. Sole 1105 This is the default FSM state for an ungrouped device. 1107 On initialization, a Challenge TID is created and sent out inside of 1108 a Beacon message along with the device's current state. 1110 The FSM also listens for Beacons from other devices. Upon receipt of 1111 a Beacon message from another device, the received Challenge TID is 1112 compared with the own Challenge. The device with the lower Challenge 1113 TID is assigned the 'Requester' role, and the other device is 1114 automatically assigned the 'Offerer' role. If a device is determined 1115 to be the 'Offerer', it resends the Beacon. If a device is 1116 determined to be the 'Requester', it issues a NegotiationRequest 1117 event to the 'Offerer'. 1119 When the 'Offerer' device receives this NegotiationRequest message, 1120 it responds with a NegotiationOpen message, and the 'Offerer' FSM 1121 transitions to state HandshakingOfferer where it awaits the 1122 'Requester' device response. 1124 On receipt of a Grouped device's NegotiationRequestGrouped message, 1125 it responds with a NegotiationOpen message, and the 'Requester' FSM 1126 transitions to state HandshakingToJoin. 1128 On receipt of the 'Offerer' device's NegotiationOpen message, the 1129 'Requester' FSM transitions to state HandshakingRequester. 1131 In this state, other events may also be processed, but these events 1132 do not result in a transition to another state. 1134 A.1.1.3. HandshakingOfferer 1136 This state can only be entered by the 'Offerer' device from Sole 1137 state. 1139 On initialization, it drives user interface options, including the 1140 Trustwords dialog. The user is prompted to compare Trustwords and 1141 choose from the following options: 1143 o Accept: The 'Requester' public key used in the Handshake is 1144 trusted, and the FSM transitions to state 1145 HandshakingPhase1Offerer. 1147 o Reject: A CommitReject message is sent to the 'Requester' device, 1148 pEp KeySync is disabled, and the FSM transitions to state End. 1150 o Cancel: A Rollback message is sent to the 'Requester' device, and 1151 the FSM transitions to state Sole. 1153 If the user selects one of the above options on the 'Requester' 1154 device, the 'Requester' FSM sends a response to the 'Offerer' device. 1155 When this response is received, the 'Offerer' FSM performs a 1156 sameNegotiation conditional check on the current negotiation session 1157 to verify that the current session has not been disrupted or 1158 compromised. If this conditional returns 'true', the FSM proceeds as 1159 follows, depending on the message received: 1161 o CommitAcceptRequester: The 'Requester' FSM transitions to state 1162 HandshakingPhase2Offerer. 1164 o CommitReject: pEp KeySync is disabled, and the FSM transitions to 1165 state End. 1167 o Rollback: The FSM transitions to state Sole. 1169 A.1.1.4. HandshakingRequester 1171 This state can only be entered by the 'Requester' device from Sole 1172 state. 1174 On initialization, it drives user interface options, including the 1175 Trustwords dialog. The user is prompted to compare Trustwords, and 1176 choose from the following options: 1178 o Accept: The 'Offerer' public key is trusted, a 1179 CommitAcceptRequester message is sent to the 'Offerer' device, and 1180 the FSM transitions to state HandshakingPhase1Requester. 1182 o Reject: A CommitReject message is sent to the 'Offerer' device, 1183 pEp KeySync is disabled, and the FSM transitions to state End. 1185 o Cancel: A Rollback message is sent to the 'Offerer' device, and 1186 the FSM transitions to state Sole. 1188 If the user selects the 'Cancel' or the 'Reject' options on the 1189 'Offerer' device, the 'Offerer' FSM sends a response to the 1190 'Requester' device. When this response is received, the 'Requester' 1191 FSM performs a sameNegotiation conditional check on the current 1192 negotiation session to verify that the current session has not been 1193 disrupted or compromised. If this conditional returns 'true', the 1194 FSM proceeds as follows, depending on the message received: 1196 o CommitReject: pEp KeySync is disabled, and the FSM transitions to 1197 state End. 1199 o Rollback: The FSM transitions to state Sole. 1201 A.1.1.5. HandshakingPhase1Offerer 1203 This state can only be entered by the 'Offerer' device from 1204 HandshakingOfferer state. 1206 In this state the FSM awaits and processes the response from a 1207 'Requester' device in state HandshakingRequester. When this response 1208 is received, the 'Offerer' FSM performs a sameNegotiation conditional 1209 check on the current negotiation session to verify that the current 1210 session has not been disrupted or compromised. If this conditional 1211 returns 'true', the FSM proceeds as follows, depending on the message 1212 received: 1214 o CommitAcceptRequester: A CommitAcceptOfferer message is sent to 1215 the 'Requester' device, and the FSM transitions to state 1216 FormingGroupOfferer. 1218 o CommitReject: The 'Requester' public key is mistrusted, pEp 1219 KeySync is disabled, and the FSM transitions to state End. 1221 o Rollback: The 'Requester' public key is mistrusted, and the FSM 1222 transitions to state Sole. 1224 A.1.1.6. HandshakingPhase1Requester 1226 This state can only be entered by the 'Requester' device from 1227 HandshakingRequester state. 1229 In this state the FSM awaits and processes the response from an 1230 'Offerer' device in state HandshakingOfferer or 1231 HandshakingPhase2Offerer. When this response is received, the 1232 'Requester' FSM performs a sameNegotiation conditional check on the 1233 current negotiation session to verify that the current session has 1234 not been disrupted or compromised. If this conditional returns 1235 'true', the FSM proceeds as follows, depending on the message 1236 received: 1238 o CommitAcceptOfferer: The FSM prepares the Own Keys on the 1239 'Requester' device for synchronization. The FSM then issues an 1240 OwnKeysRequester message to the 'Offerer', which contains these 1241 keys, and transitions to state FormingGroupRequester. 1243 o CommitReject: The 'Offerer' public key is mistrusted, pEp KeySync 1244 is disabled, and the FSM transitions to state End. 1246 o Rollback: The 'Offerer' public key is mistrusted, and the FSM 1247 transitions to state Sole. 1249 A.1.1.7. HandshakingPhase2Offerer 1251 This state can only be entered by the 'Offerer' device from a 1252 HandshakingOfferer state. 1254 In this state the FSM waits for the user's response on the 'Offerer' 1255 device. The user is still prompted to compare Trustwords and choose 1256 from the following options: 1258 o Accept: The 'Requester' public key used in the Handshake is 1259 trusted, a CommitAcceptOfferer message is issued to the 1260 'Requester', and the FSM transitions to state FormingGroupOfferer. 1262 o Reject: A CommitReject message is issued to the 'Requester' 1263 device, pEp KeySync is disabled, and the FSM transitions to state 1264 End. 1266 o Cancel: A Rollback message is issued to the 'Requester' device, 1267 and the FSM transitions to state Sole. 1269 A.1.1.8. FormingGroupOfferer 1271 This state can only be entered by the 'Offerer' device from 1272 HandshakingPhase1Offerer or HandshakingPhase2Offerer state. 1274 On initialization, the FSM prepares the Own Keys on the 'Offerer' 1275 device for synchronization and makes a backup of these Own Keys. 1276 Then it waits for the OwnKeysRequester message from the 'Requester', 1277 which contains the Own Keys and the information about all Own 1278 Identities of the 'Requester'. 1280 When this message is received, the 'Offerer' FSM performs a 1281 sameNegotiation conditional check on the current negotiation session 1282 to verify that the current session has not been disrupted or 1283 compromised. If this conditional returns 'true', the FSM saves the 1284 'Requester' keys combined with the 'Offerer' keys in a shared 1285 GroupKeys array (saveGroupKeys) and the 'Requester' device keys are 1286 marked as default for those respective identities 1287 (receivedKeysAreDefaultKeys). Then, the FSM prepares the Own Keys on 1288 the 'Offerer' device for synchronization. Because the Keys are 1289 already set to those of the 'Requester' device, it is taking its 1290 former Own Keys and Own Identities from the backup (cf. above). The 1291 Offerer sends the OwnKeysOfferer message (with Key material of its 1292 Own Keys and Own Identities) to the 'Requester', a UI event 1293 (showGroupCreated) indicates that the Device Group process is 1294 complete, and the FSM transitions to state Grouped. 1296 Note: In case the 'Requester' device has transitioned to Sole state 1297 due to a Cancel, this OwnKeysOfferer message will not processed by 1298 the 'Requester' device. 1300 In case a (delayed) Cancel arrives (which normally cannot happen), a 1301 Rollback message is issued to the 'Requester' device, and the FSM 1302 transitions to state Sole. 1304 In case a (delayed) Rollback message is received (which normally 1305 cannot happen), the FSM transitions to state Sole. 1307 A.1.1.9. FormingGroupRequester 1309 This state can only be entered by the 'Requester' device from a 1310 HandshakingPhase1Requester state. 1312 In this state the FSM awaits and processes the message OwnKeysOfferer 1313 from an 'Offerer' device in state HandshakingPhase1Offerer or 1314 HandshakingPhase2Offerer. 1316 When this message is received, the 'Requester' FSM performs a 1317 sameNegotiation conditional check on the current negotiation session 1318 to verify that the current session has not been disrupted or 1319 compromised. If this conditional returns 'true', the FSM saves the 1320 'Offerer' keys in a shared GroupKeys array (saveGroupKeys), and 1321 prepares the device's Own Keys for synchronization. The 'Requester' 1322 device keys are marked as default for those respective identities 1323 (ownKeysAreDefaultKeys). A UI event (showGroupCreated) indicates 1324 that the Device Group process is complete, and the FSM transitions to 1325 state Grouped. 1327 In case a (delayed) Cancel arrives (which normally cannot happen), a 1328 Rollback message is issued to the 'Offerer' device, and the FSM 1329 transitions to state Sole. 1331 Note: In case the 'Offerer' device has already transitioned to 1332 Grouped state, this Rollback message will not be processed by the 1333 'Offerer' device. 1335 In case a (delayed) Rollback message is received (which normally 1336 cannot happen), the FSM transitions to state Sole. 1338 A.1.1.10. Grouped 1340 This is the default state for any Grouped Device. 1342 On initialization, this state generates a new Challenge TID and shows 1343 the device as being in the Grouped state. A UI event 1344 (showBeingInGroup) indicates that the Device is part of a Device 1345 Group. 1347 In this state the FSM also listens for Beacons from other devices 1348 that are not yet part of the Device Group. 1350 Upon receipt of a Beacon message from Sole Device, the device sends a 1351 NegotiationRequestGrouped message and waits for the Sole Device to 1352 respond with a NegotiationOpen message. 1354 On receipt of the NegotiationOpen message from the Sole Device, the 1355 FSM of the Grouped Device stores the negotiation information and 1356 transitions to state HandshakingGrouped. 1358 In this state, other events may also be processed, but these events 1359 do not result in a transition to another state. 1361 A.1.1.11. HandshakingToJoin 1363 This state can only be entered by a device in the Sole state that is 1364 attempting to join an existing Device Group. 1366 On initialization, this state drives user interface options, 1367 including the Trustwords dialog for joining a Device Group. The user 1368 on the new device is prompted to compare Trustwords and choose from 1369 the following options: 1371 o Accept: The existing Device Group's public key used in the 1372 Handshake is trusted, and the FSM transitions to state 1373 HandshakingToJoinPhase1. 1375 o Reject: A CommitReject message is sent to the existing Device 1376 Group, pEp KeySync is disabled (on new device), and the FSM 1377 transitions to state End. 1379 o Cancel: A Rollback message is sent to the existing Device Group, 1380 and the FSM transitions to state Sole. 1382 If the user selects one of the above options on a device that is part 1383 of the existing Device Group, its FSM sends a response to the new 1384 device. When this response is received, the FSM of the new device 1385 performs a sameNegotiation conditional check on the current 1386 negotiation session to verify that the current session has not been 1387 disrupted or compromised. If this conditional returns 'true', the 1388 FSM proceeds as follows, depending on the message received: 1390 o CommitAcceptForGroup: The FSM of the new device transitions to 1391 state HandshakingToJoinPhase2. 1393 o CommitReject: pEp KeySync is disabled (on the new device), and the 1394 FSM transitions to state End. 1396 o Rollback: The FSM transitions to state Sole. 1398 A.1.1.12. HandshakingToJoinPhase1 1400 This state is entered by a new device only, i.e. a device that is not 1401 yet part of a Device Group. 1403 In this state the FSM awaits and processes the response from a device 1404 that is part of the existing Device Group. When this response is 1405 received, the FSM of the new device performs a sameNegotiation 1406 conditional check on the current negotiation session to verify that 1407 the current session has not been disrupted or compromised. If this 1408 conditional returns 'true', the FSM proceeds as follows, depending on 1409 the message received: 1411 o CommitAcceptForGroup: A CommitAccept message is sent to the 1412 existing Device Group, and the The FSM transitions to state 1413 JoiningGroup. 1415 o CommitReject: The existing Device Group's public key is 1416 mistrusted, pEp KeySync is disabled (on the new device), and the 1417 FSM transitions to state End. 1419 o Rollback: The existing Device Group's public key is mistrusted, 1420 and the FSM transitions to state Sole. 1422 A.1.1.13. HandshakingToJoinPhase2 1424 This state is entered by a new device only, i.e. a device that is not 1425 yet part of a Device Group. 1427 In this state the FSM waits for the user's response on the new 1428 device. The user is still prompted to compare Trustwords and choose 1429 from the following options: 1431 o Accept: The existing Device Groups's public key used in the 1432 Handshake is trusted, a CommitAccept message is issued to the 1433 'Requester', and the FSM transitions to state JoiningGroup. 1435 o Reject: A CommitReject message is issued to the exiting Device 1436 Group, pEp KeySync is disabled (on the new device), and the FSM 1437 transitions to state End. 1439 o Cancel: A Rollback message is issued to the existing Device Group, 1440 and the FSM transitions to state Sole. 1442 A.1.1.14. JoiningGroup 1444 This state is entered by a new device only, i.e. a device that is not 1445 yet part of a Device Group. 1447 On initialization, the FSM prepares the Own Keys on the new device 1448 for synchronization and makes a backup of these Own Keys. Then it 1449 waits for the OwnKeysForNewMember message from the exiting Device 1450 Group, which contains the Own Keys and the information about all Own 1451 Identities of the existing Device Group. 1453 When this message is received, the FSM of the new device performs a 1454 sameNegotiationAndPartner conditional check on the current 1455 negotiation session to verify that both the current session and 1456 negotiation partner have not been disrupted or compromised. If this 1457 conditional returns 'true', the FSM saves the 'Requester' keys 1458 combined with the keys of the existing group in a shared GroupKeys 1459 array (saveGroupKeys) and the Device Group's keys are marked as 1460 default for those respective identities (receivedKeysAreDefaultKeys). 1461 Then, the FSM prepares the Own Keys on the new device for 1462 synchronization. Because the Keys are already set to the ones of the 1463 existing Device Group, it is taking its former Own Keys and Own 1464 Identities from the backup (cf. above). The new device sends the 1465 GroupKeysAndClose message (with Key material of its Own Keys and Own 1466 Identities) to the Device Group, a UI event (showDeviceAdded) 1467 indicates that the join Device Group process is complete, and the FSM 1468 transitions to state Grouped. 1470 A.1.1.15. HandshakingGrouped 1472 This state is entered by Grouped Devices only, i.e., devices that are 1473 part of a Device Group. 1475 On initialization, this state drives user interface options, 1476 including the Trustwords dialog. The user is prompted to compare 1477 Trustwords, and choose from the following options on any device 1478 belonging to the existing Device Group: 1480 o Accept: The new device's public key is trusted, and the FSM 1481 transitions to state HandshakingGroupedPhase1. 1483 o Reject: A CommitReject message is sent to the new device and the 1484 FSM transitions to state Grouped. 1486 o Cancel: A Rollback message is sent to the new device, and the FSM 1487 transitions to state Grouped. 1489 If the user selects the 'Cancel' or the 'Reject' options on the new 1490 device, the new device's FSM sends a response to the existing Device 1491 Group. When this response is received, the grouped devices FSM 1492 performs a sameNegotiation conditional check on the current 1493 negotiation session to verify that the current session has not been 1494 disrupted or compromised. If this conditional returns 'true', the 1495 FSM proceeds as follows, depending on the message received: 1497 o CommitReject: The FSM transitions to state Grouped. 1499 o Rollback: The FSM transitions to state Grouped. 1501 When a GroupTrustThisKey message is received from another device 1502 group member, the key received along with this message is trusted. 1503 If the sameNegotiation conditional check returns true, the FSM 1504 transitions to state Grouped. This latter causes any device in a 1505 Device Group, which is not actively taking part in the joining 1506 process, to abort the user prompt to Compare the Trustwords. 1508 Note: In this state, other events are processed, but these events do 1509 not result in a transition to another state and are not discussed 1510 here. 1512 A.1.1.16. HandshakingGroupedPhase1 1514 This state is entered by Grouped Devices only, i.e., devices that are 1515 already part of a Device Group. 1517 On initialization a message GroupTrustThisKey is sent to the other 1518 members of the Device Group and a message CommitAcceptForGroup is 1519 sent to the new device. 1521 In this state the FSM awaits and processes the response from an new 1522 device in state HandshakingToJoin or HandshakingToJoinPhase2. When 1523 this response is received, the grouped device's FSM performs a 1524 sameNegotiation conditional check on the current negotiation session 1525 to verify that the current session has not been disrupted or 1526 compromised. If this conditional returns 'true', the FSM proceeds as 1527 follows, depending on the message received: 1529 o CommitAccept: The FSM prepares the Own Keys on the grouped device 1530 for synchronization. The FSM then issues an 1531 SendGroupKeysForNewMember message to the new device, which 1532 contains these keys. Then a UI event (showDeviceAccepted) 1533 indicates that the new device has been successfully added to the 1534 Device Group, and the FSM transitions to state Grouped. [[ TODO: 1535 Check whether 'go Grouped' should be removed in this event handler 1536 ]] 1538 o CommitReject: The 'Offerer' public key is mistrusted and the FSM 1539 transitions to state Grouped. 1541 o Rollback: The 'Offerer' public key is mistrusted, and the FSM 1542 transitions to state Grouped. 1544 In case a GroupKeysAndClose message arrives from another group 1545 member, the FSM transitions to state Grouped. 1547 In this state also various other events are processed, which do not 1548 result in a transition to another state. 1550 A.1.1.17. GroupKeyResetElection 1552 This state is entered by Grouped Devices only, i.e., devices that are 1553 already part of a Device Group. 1555 It is used to reset keys that have become invalid. 1557 [[ TODO: More detailed description ]] 1559 A.1.2. Conditions 1561 All Conditions can either be true or false on successful execution, 1562 or, if the condition fails, the Finite State Machine is brought into 1563 an error state and reinitialized. 1565 A.1.2.1. deviceGrouped 1567 The 'deviceGrouped' conditional evaluates true if a device is already 1568 in a Device Group. This is determined by checking if there are Group 1569 Keys already. This boolean value is available and eventually altered 1570 locally on every KeySync-enabled device. For example, in the 1571 reference implementation, this boolean value is stored in a local SQL 1572 database. 1574 The 'deviceGrouped' value is what the KeySync FSM uses upon 1575 initialization to determine whether a device should transition to 1576 state Sole or state Grouped. 1578 A.1.2.2. fromGroupMember 1580 The 'fromGroupMember' conditional evaluates true if the incoming Sync 1581 Message is coming from a Device Group member. 1583 A.1.2.3. keyElectionWon 1585 The 'keyElectionWon' conditional evaluates true if our Own Keys are 1586 going to be used as Group Keys. False if the Own Keys of the partner 1587 will be the Group Keys. Calculated by comparing if the FPR of the 1588 Sender Key of the partner is greater than our Default Key for the 1589 Account, which is being used as Active Transport. 1591 A.1.2.4. sameChallenge 1593 The 'sameChallenge' conditional evaluates true if the Challenge of 1594 the incoming Sync Message is identical to the Challenge of the 1595 Device, i.e., this is a Sync Message sent by the originating Device 1596 itself. 1598 A.1.2.5. sameNegotiation 1600 The 'sameNegotiation' conditional is dependent upon the 1601 'storeNegotiation' function, which stores the active negotiation 1602 session while the KeySync process is performed. This conditional 1603 evaluates true if the 'storeNegotiation' value of the incoming Sync 1604 Message is identical to that of the 'storeNegotiation' value that the 1605 Device is in. 1607 This serves as a session fidelity check. If this boolean evaluates 1608 'true', it confirms that the pEp KeySync session in progress is the 1609 same throughout. 1611 A.1.2.6. sameNegotiationAndPartner 1613 Similar to the 'sameNegotiation' conditional, the 1614 'sameNegotiationAndPartner' conditional is dependent upon the 1615 'storeNegotiation' function, which stores the active negotiation 1616 session while the KeySync process is performed. The 1617 'sameNegotiation' conditional evaluates true if both 1618 'storeNegotiation' value of the incoming Sync Message is identical to 1619 that of the 'storeNegotiation' value that the Device is in, AND the 1620 negotiation partner did not change. 1622 This conditional also serves as a session fidelity check. If this 1623 boolean evaluates 'true', it confirms that the pEp KeySync session in 1624 progress is the same throughout, and that the negotiation partner has 1625 not changed. 1627 A.1.2.7. sameResponse 1629 The 'sameResponse' conditional evaluates true if the Response of the 1630 incoming Sync Message is identical to the Response of the Device. In 1631 this case the Response is correctly echoed. 1633 A.1.2.8. weAreOfferer 1635 The 'weAreOfferer' conditional evaluates true if the Challenge of the 1636 incoming Sync Message is greater than the Challenge of the Device. 1637 Otherwise we're the Requester. 1639 A.1.3. Actions 1641 Actions are unconditionally executed. Any or all Actions may fail. 1642 In the event of failure, actions bring the Finite State Machine into 1643 an error state, and the Finite State Machine will be reinitialized. 1645 A.1.3.1. backupOwnKeys 1647 The 'backupOwnKeys' action is to make a backup of all Own Keys, and 1648 allows for restoration of the Own Keys. 1650 A.1.3.2. disable 1652 The 'disable' action does as it implies. This action shuts down the 1653 Finite State Machine and disables KeySync functionality on the 1654 impacted device. It is most commonly called in 'Cancel' or 'Reject' 1655 scenarios. For example, if a user rejects a pEp Handshake on a 1656 device involved in a pEp Handshake, the 'disable' action is called. 1657 Invoking the 'disable' function results in the FSM transitioning to 1658 state End, which automatically disables the KeySync feature. pEp 1659 KeySync can be manually re-enabled in the pEp settings on the 1660 disabled device. 1662 A.1.3.3. newChallengeAndNegotiationBase 1664 The 'newChallengeAndNegotiationBase' action is to randomly compute a 1665 new Challenge and a new Response (Negotiatial Base). 1667 The 'newChallengeAndNegotiationBase' action is invoked by a device 1668 during an Init event in either the Sole or Grouped state, and serves 1669 to clear and generate a new Challenge TID and negotiation state. 1671 A.1.3.4. openNegotiation 1673 The 'openNegotiation' action is to clear Key and Identity of the 1674 partner and to calculate the Negotiation ID from the Negotiation Base 1675 and the Challenge of the partner (by XOR). 1677 An 'openNegotiation' action is carried out either by a Sole Device in 1678 the 'Requester' role, or a Grouped device upon receipt of a Beacon 1679 message from another Sole Device. Most importantly, this action 1680 ensures that the own TID and the Challenge TID of the Sole Device get 1681 combined by the mathematical XOR function. In this way, a common TID 1682 exists which can be used by both devices a user wishes to pair. This 1683 TID is crucial in allowing the devices to recognize themselves in a 1684 particular pairing process, as multiple pairing process can occur 1685 simultaneously. 1687 A.1.3.5. ownKeysAreDefaultKeys 1689 The 'ownKeysAreDefaultKeys' action is to flag Default Keys of Own 1690 Identities as Group Keys. 1692 The ownKeysAreDefaultKeys action is invoked by the 'Requester' device 1693 during the final step of Device Group formation between two Sole 1694 devices, and ensures that the Own Keys for the identities on the 1695 'Requester' device are set as the default for those respective 1696 identities. 1698 A.1.3.6. prepareOwnKeys 1700 The 'prepareOwnKeys' action is to write a list of Own Identities into 1701 the I/O Buffer and load the list of Own Keys into the Device state. 1703 The prepareOwnKeys action is invoked during the latter phases of the 1704 KeySync protocol for both new and existing Device Group joining 1705 processes. This action indicates to a device that all key 1706 information that has been selected for synchronization should be 1707 prepared for sending to the other negotiation partner. 1709 A.1.3.7. prepareOwnKeysFromBackup 1711 The 'prepareOwnKeysFromBackup' action is to restore the formerly 1712 backed up Own Keys (cf. Appendix A.1.3.1) into the I/O Buffer. This 1713 action is similar to prepareOwnKeys (cf. Appendix A.1.3.6). 1715 A.1.3.8. receivedKeysAreDefaultKeys 1717 The 'receivedKeysAreDefaultKeys' action is to set the received Own 1718 Keys as Default Keys for the Own Identities. 1720 A.1.3.9. resetOwnGroupedKeys 1722 The 'resetOwnGroupedKeys' action is to carry out a KeyReset on Own 1723 Group Keys. 1725 A.1.3.10. resetOwnKeysUngrouped 1727 The 'resetOwnKeysUngrouped' action is to carry out a KeyReset on all 1728 Own Keys. 1730 A.1.3.11. saveGroupKeys 1732 The 'saveGroupKeys' action is to load Own Identities from the I/O 1733 Buffer and store them as Own Identities. 1735 The 'saveGroupKeys' action directs the addition of any keys received 1736 during a KeySync process to a GroupKeys array, along with any 1737 existing Own or Grouped Device Keys. 1739 A.1.3.12. showBeingInGroup 1741 The 'showBeingInGroup' action is to signal to the application that 1742 the device is member of a Device Group. 1744 The showBeingInGroup action in state Grouped drives a UI event that 1745 can be used to notify a pEp user that their device belongs to a 1746 Device Group 1748 A.1.3.13. showBeingSole 1750 The 'showBeingSole' action is to signal to the application that the 1751 device is not member of a Device Group. 1753 The 'showBeingSole' action in state Sole drives a UI event that can 1754 be used to notify a pEp user that their device is Sole (ungrouped). 1756 A.1.3.14. showDeviceAccepted 1758 The 'showDeviceAccepted' action is to signal to the application that 1759 the device has been accepted as member of the Device Group. 1761 The 'showDeviceAccepted' action drives a UI event that is used to 1762 notify a pEp user that a Sole Device was accepted as member of an 1763 existing Device Group. 1765 A.1.3.15. showDeviceAdded 1767 The 'showDeviceAdded' action is to signal to the application that the 1768 device has been added as member of the Device Group. 1770 The 'showDeviceAdded' action drives a UI event that is used to notify 1771 a pEp user that a Sole Device was added to an already existing Device 1772 Group. 1774 A.1.3.16. showGroupCreated 1776 The 'showGroupCreated' action is to signal to the application that 1777 the Device Group has been created. 1779 In either role that a Sole Device can assume ('Requester' or 1780 'Offerer'), the action 'showGroupCreated' drives a UI event which 1781 notifies a user that a new Device Group was formed from two Sole 1782 Devices. 1784 A.1.3.17. showGroupedHandshake 1786 The 'showGroupedHandshake' action is to signal to the application of 1787 a Grouped Device that a new device is about to join that Device 1788 Group. 1790 The 'showGroupedHandshake' action drives a UI event on a Grouped 1791 device, which a pEp implementer should use to display a pEp Handshake 1792 dialog. This dialog should indicate that there is a new Sole Device 1793 that is requesting to join the Device Group that this Grouped device 1794 belongs to. 1796 A.1.3.18. showJoinGroupHandshake 1798 The 'showJoinGroupHandshake' action is to signal to the application 1799 of an Ungrouped Device that it is about to join an existing Device 1800 Group. 1802 The 'showJoinGroupHandshake' action drives a UI event on a Sole 1803 Device attempting to join an existing Device Group, and should be 1804 used by pEp implementers to show a Handshake dialog on the Sole 1805 Device. 1807 A.1.3.19. showSoleHandshake 1809 The 'showSoleHandshake' action is to signal to the application of a 1810 Ungrouped Device that it is about to from a new Device Group. 1812 For cases where two Sole Devices are attempting to form a new Device 1813 Group, the showSoleHandshake action drives a UI event, which a pEp 1814 implementer should use to display a pEp Handshake dialog to each of 1815 the devices in negotiation. 1817 A.1.3.20. storeNegotiation 1819 The 'storeNegotiation' action is to store the Negotiation for the 1820 device in the I/O Buffer The Sender FPR and partner's Identity are 1821 both stored for later comparison. 1823 The storeNegotiation action saves the received non-own negotiation 1824 information, which is used e.g. by the sameNegotiation conditional to 1825 perform a session fidelity check (cf. Appendix A.1.2.5). 1827 A.1.3.21. storeThisKey 1829 The 'storeThisKey' action is to load the Sender Key of the partner 1830 from the I/O Buffer and store it for later use. 1832 A.1.3.22. tellWeAreGrouped 1834 The 'tellWeAreGrouped' action is to set the is_grouped Field in the 1835 I/O Buffer to true. 1837 The tellWeAreGrouped action is used by devices already in the Grouped 1838 state. It is sent in a Beacon and indicates to Sole Devices that 1839 they are entering a negotiation with a Grouped device. For the Sole 1840 Device, receiving this action determines which state the FSM will 1841 transition to next. 1843 A.1.3.23. tellWeAreNotGrouped 1845 The 'tellWeAreNotGrouped' action is to set the is_grouped Field in 1846 the I/O Buffer to false. 1848 The 'tellWeAreNotGrouped' action is used by Sole Devices which are 1849 assigned the role of 'Requester' upon Challenge TID comparison, and 1850 is sent along with a NegotiationRequest event to indicate to the 1851 'Offerer' device that they are entering into a negotiation request 1852 with a Sole Device. 1854 A.1.3.24. trustThisKey 1856 The 'trustThisKey' action applies trust to the stored Key of the 1857 negotiation partner and loads this Key into the I/O Buffer. 1859 The trustThisKey action is executed in all states when a user chooses 1860 'Accept' on the Handshake dialog. Trust for the public key from the 1861 negotiation partner is granted so the rest of the KeySync process can 1862 be conducted securely. The trust also extends to the private key 1863 portion of the key pair at later stage in the KeySync process, so 1864 long as the user continues to choose 'Accept' on both devices. If 1865 the process is canceled or rejected at any point after the public key 1866 trust has been granted, that trust will be removed (cf. 1867 Appendix A.1.3.25). 1869 A.1.3.25. untrustThisKey 1871 The 'untrustThisKey' action is to revoke trust from the formerly 1872 stored Key of the partner and clear the Key in the I/O Buffer. 1874 If the 'Cancel' or 'Reject' options are chosen at any point during 1875 the KeySync process after a negotiation partner's public key has been 1876 trusted, trust on that public key is removed (cf. 1877 Appendix A.1.3.24). The untrustThisKey action ensures that the 1878 negotiation partner's public key can never be attached to messages 1879 sent to outside peers from the recipient device. 1881 A.1.3.26. useOwnChallenge 1883 The 'useOwnChallenge' action is to copy the Challenge of the Device 1884 into the I/O Buffer. 1886 Once a Beacon is received by a device in either the Sole or Grouped 1887 state, the useOwnChallenge action attaches the device's generated 1888 Challenge TID to an outgoing Beacon or NegotiationRequest event for 1889 comparison and session verification purposes. 1891 A.1.3.27. useOwnResponse 1893 The 'useOwnResponse' action is to copy the Response of the Device 1894 into the I/O Buffer. 1896 A.1.3.28. useThisKey 1898 The 'useThisKey' action is to copy the stored Sender Key of the 1899 partner into the I/O Buffer. 1901 A.1.4. Transitions 1903 Transitions are changes between states within the FSM, and are 1904 indicated by the 'go' command throughout the code. Please see the 1905 desired State (Appendix A.1.1 and Appendix B.1) for additional 1906 information on why and when these changes are triggered. 1908 A.1.5. Events 1910 While in a State, Events receive incoming messages and prompt the 1911 execution of any event handlers (conditions, actions, messages, or 1912 transitions) contained within. Please refer to the desired State 1913 (Appendix B.1) for additional information on specific event handlers. 1915 A.1.5.1. Init Event 1917 When the FSM transitions to a new state for the first time, the Init 1918 event (if present) is called. Init events typically drive UI actions 1919 and event handlers associated with core functionality of the 1920 protocol. 1922 Example of an Init Event Handler: 1924 on Init { 1925 if deviceGrouped { 1926 send SynchronizeGroupKeys; 1927 go Grouped; 1928 } 1929 go Sole; 1930 } 1932 A.1.5.2. Message Event 1934 If a Sync Message (cf. Appendix A.1.6) arrives through the network 1935 then the Event with the name of the Message occurs. 1937 Example of an Message Event Handler: 1939 In this example an Event Handler is defined, which is executed when a 1940 Beacon Message arrives: 1942 on Beacon { 1943 do openNegotiation; 1944 do tellWeAreGrouped; 1945 do useOwnResponse; 1946 send NegotiationRequestGrouped; 1947 do useOwnChallenge; 1948 } 1950 A.1.5.3. Signaled Events 1952 Events, which don't share their name with a Message, are signaled 1953 from engine code. 1955 Example of an Signaled Event Handler: 1957 The KeyGen Event has no corresponding Message. Therefore, it does 1958 not occur when a Sync Message arrives, but rather when it is signaled 1959 from code: 1961 on KeyGen { 1962 do prepareOwnKeys; 1963 send GroupKeysUpdate; 1964 } 1966 A.1.5.4. External Events 1968 If Events are part of an API then their IDs must be well defined. 1969 Therefore, it is possible to define such IDs in the State Machine. 1970 External Event may be used to signal a User Interaction to the FSM. 1972 Example: 1974 on Accept { 1975 do trustThisKey; 1976 send CommitAcceptRequester; 1977 go HandshakingPhase1Requester; 1978 } 1980 A.1.6. Messages 1982 KeySync is a Network Protocol, which is implemented using Sync 1983 Messages. The Sync Messages for KeySync are defined at the end of 1984 the Finite State Machine code in Appendix B.1. 1986 The wire format of Sync Messages is defined in ASN.1 (cf. 1987 Appendix B.2), using PER. 1989 Sync Messages are transported as Attachments to pEp Messages. Hence 1990 they're carried by the same Transports, which transmit pEp Messages. 1991 Some Sync Messages must be sent in copy on all Transports. Others 1992 are transported on the Active Transport only. The Active Transport 1993 is the transport on which the last Sync Message was received. 1995 A.1.6.1. Message Types 1997 Each Sync Message has a name and an ID. There is different types of 1998 Messages: 2000 o type=broadcast: Messages, which are meant to be copied on all 2001 Transports 2003 o type=anycast: Messages, which are meant to be sent on the Active 2004 Transport only 2006 A.1.6.2. Security Context 2008 Each Sync Message has a Security Context. The available Security 2009 Contexts are: 2011 o security=unencrypted: send and receive as unencrypted but signed 2012 Sync Message 2014 o security=untrusted: only accept when encrypted and signed 2016 o security=trusted (default): only accept when coming over a Trusted 2017 Channel and when originating from the Device Group 2019 o security=attach_own_keys_for_new_member: like security=trusted but 2020 attach all Own Keys for a new Member of the Device Group 2022 o security=attach_own_keys_for_group: like security=trusted but 2023 attach all Own Keys for other Device Group Members. 2025 A.1.6.3. Rate Limit 2027 A Sync Message can have a Rate Limit ratelimit=. That means 2028 it is only possible to send out one message each seconds. 2029 A Rate Limit of 0 means no Rate Limit checking. 2031 Example: 2033 message Beacon 2, type=broadcast, ratelimit=10, security=unencrypted { 2034 field TID challenge; 2035 auto Version version; 2036 } 2038 A.1.6.4. Fields 2040 A Sync Message can have Fields. There is two types of fields: 2041 automatically calculated fields, defined with the auto keyword, and 2042 fields, which are copied in and out from the I/O Buffer, marked with 2043 the fields keyword. 2045 The wire format of the fields is depending on their type. 2047 The types are defined in Appendix B.2. Additionally, the two basic 2048 types bool (ASN.1: BOOLEAN) and int (ASN.1: INTEGER) are supported. 2050 Example for an auto field: 2052 auto Version version; 2054 This field will be filled with the pEp Sync Protocol version. The 2055 Version type is the only automatically calculated type yet. 2057 Example for a field coming from I/O Buffer 2059 field TID challenge; 2061 A.1.6.5. I/O Buffer 2063 There is an I/O Buffer for all Fields which occur in Messages. All 2064 Messages share this I/O Buffer. Fields with the same name share one 2065 space in the I/O Buffer. Hence, the I/O Buffer is built as superset 2066 of all Fields' buffers. 2068 A.1.6.6. Sending 2070 Sending is performed as follows: 2072 1. Calculating all auto Fields and copying the result into the I/O 2073 Buffer 2075 2. Loading all Fields of the Message from I/O Buffer 2077 3. Creating a Sync Message 2079 4. Creating a transporting pEp Message by attaching the Sync Message 2080 using Base Protocol 2082 5. Calling messageToSend() with this pEp Message 2084 Example 2086 send SynchronizeGroupKeys; 2088 A.1.6.7. Receiving 2090 When a Message is being received the field values are being copied 2091 into the I/O Buffer and the corresponding Event is being signaled. 2093 A.1.6.8. Messages used in KeySync 2095 For more information on the messages used in the KeySync Protocol, 2096 see (end of) Appendix B.1. 2098 Appendix B. Code excerpts 2100 B.1. Finite State Machine 2102 Below is the full code for the pEp KeySync FSM, including messages 2103 and external events. 2105 // This file is under BSD License 2.0 2107 // Sync protocol for pEp 2108 // Copyright (c) 2016-2020, pEp foundation 2110 // Written by Volker Birk 2112 include ./fsm.yml2 2114 protocol Sync 1 { 2115 // all messages have a timestamp, time out and are removed after 2116 // timeout 2118 fsm KeySync 1, threshold=300 { 2119 version 1, 2; 2121 state InitState { 2122 on Init { 2123 if deviceGrouped { 2124 send SynchronizeGroupKeys; 2125 go Grouped; 2126 } 2127 go Sole; 2128 } 2129 } 2131 state Sole timeout=off { 2132 on Init { 2133 do newChallengeAndNegotiationBase; 2134 send Beacon; 2135 do showBeingSole; 2136 } 2138 on KeyGen { 2139 send Beacon; 2140 } 2142 on CannotDecrypt { 2143 send Beacon; 2144 } 2146 on Beacon { 2147 if sameChallenge { 2148 } 2149 else { 2150 if weAreOfferer { 2151 do useOwnChallenge; 2152 send Beacon; 2153 } 2154 else /* we are requester */ { 2155 do openNegotiation; 2156 do tellWeAreNotGrouped; 2157 // requester is sending NegotiationRequest 2158 do useOwnResponse; 2159 send NegotiationRequest; 2160 do useOwnChallenge; 2161 } 2162 } 2164 } 2166 // we get this from another sole device 2167 on NegotiationRequest { 2168 if sameChallenge { // challenge accepted 2169 do storeNegotiation; 2170 // offerer is accepting by confirming 2171 // NegotiationOpen 2172 // repeating response is implicit 2173 send NegotiationOpen; 2174 go HandshakingOfferer; 2175 } 2176 } 2178 // we get this from an existing device group 2179 on NegotiationRequestGrouped { 2180 if sameChallenge { // challenge accepted 2181 do storeNegotiation; 2182 // offerer is accepting by confirming 2183 // NegotiationOpen 2184 // repeating response is implicit 2185 send NegotiationOpen; 2186 go HandshakingToJoin; 2187 } 2188 } 2190 on NegotiationOpen { 2191 if sameResponse { 2192 do storeNegotiation; 2193 go HandshakingRequester; 2194 } 2195 } 2196 } 2198 // handshaking without existing Device group 2199 state HandshakingOfferer timeout=600 { 2200 on Init 2201 do showSoleHandshake; 2203 // Cancel is Rollback 2204 on Cancel { 2205 send Rollback; 2206 go Sole; 2207 } 2209 on Rollback { 2210 if sameNegotiation 2211 go Sole; 2213 } 2215 // Reject is CommitReject 2216 on Reject { 2217 send CommitReject; 2218 do disable; 2219 go End; 2220 } 2222 on CommitReject { 2223 if sameNegotiation { 2224 do disable; 2225 go End; 2226 } 2227 } 2229 // Accept means init Phase1Commit 2230 on Accept { 2231 do trustThisKey; 2232 go HandshakingPhase1Offerer; 2233 } 2235 // got a CommitAccept from requester 2236 on CommitAcceptRequester { 2237 if sameNegotiation 2238 go HandshakingPhase2Offerer; 2239 } 2240 } 2242 // handshaking without existing Device group 2243 state HandshakingRequester timeout=600 { 2244 on Init 2245 do showSoleHandshake; 2247 // Cancel is Rollback 2248 on Cancel { 2249 send Rollback; 2250 go Sole; 2251 } 2253 on Rollback { 2254 if sameNegotiation 2255 go Sole; 2256 } 2258 // Reject is CommitReject 2259 on Reject { 2260 send CommitReject; 2261 do disable; 2262 go End; 2263 } 2265 on CommitReject { 2266 if sameNegotiation { 2267 do disable; 2268 go End; 2269 } 2270 } 2272 // Accept means init Phase1Commit 2273 on Accept { 2274 do trustThisKey; 2275 send CommitAcceptRequester; 2276 go HandshakingPhase1Requester; 2277 } 2278 } 2280 state HandshakingPhase1Offerer { 2281 on Rollback { 2282 if sameNegotiation { 2283 do untrustThisKey; 2284 go Sole; 2285 } 2286 } 2288 on CommitReject { 2289 if sameNegotiation { 2290 do untrustThisKey; 2291 do disable; 2292 go End; 2293 } 2294 } 2296 on CommitAcceptRequester { 2297 if sameNegotiation { 2298 send CommitAcceptOfferer; 2299 go FormingGroupOfferer; 2300 } 2301 } 2302 } 2304 state HandshakingPhase1Requester { 2305 on Rollback { 2306 if sameNegotiation { 2307 do untrustThisKey; 2308 go Sole; 2310 } 2311 } 2313 on CommitReject { 2314 if sameNegotiation { 2315 do untrustThisKey; 2316 do disable; 2317 go End; 2318 } 2319 } 2321 on CommitAcceptOfferer { 2322 if sameNegotiation { 2323 do prepareOwnKeys; 2324 send OwnKeysRequester; 2325 go FormingGroupRequester; 2326 } 2327 } 2328 } 2330 state HandshakingPhase2Offerer { 2331 on Cancel { 2332 send Rollback; 2333 go Sole; 2334 } 2336 on Reject { 2337 send CommitReject; 2338 do disable; 2339 go End; 2340 } 2342 on Accept { 2343 do trustThisKey; 2344 send CommitAcceptOfferer; 2345 go FormingGroupOfferer; 2346 } 2347 } 2349 state FormingGroupOfferer { 2350 on Init { 2351 // we need to keep in memory which keys we have before 2352 // forming a new group 2353 do prepareOwnKeys; 2354 do backupOwnKeys; 2355 } 2357 on Cancel { 2358 send Rollback; 2359 go Sole; 2360 } 2362 on Rollback 2363 go Sole; 2365 on OwnKeysRequester { 2366 if sameNegotiationAndPartner { 2367 do saveGroupKeys; 2368 do receivedKeysAreDefaultKeys; 2369 // send the keys we had before forming a new group 2370 do prepareOwnKeysFromBackup; 2371 send OwnKeysOfferer; 2372 do showGroupCreated; 2373 go Grouped; 2374 } 2375 } 2376 } 2378 state FormingGroupRequester { 2379 on Cancel { 2380 send Rollback; 2381 go Sole; 2382 } 2384 on Rollback 2385 go Sole; 2387 on OwnKeysOfferer { 2388 if sameNegotiation { 2389 do saveGroupKeys; 2390 do prepareOwnKeys; 2391 do ownKeysAreDefaultKeys; 2392 do showGroupCreated; 2393 go Grouped; 2394 } 2395 } 2396 } 2398 state Grouped timeout=off { 2399 on Init { 2400 do newChallengeAndNegotiationBase; 2401 do showBeingInGroup; 2402 } 2404 on CannotDecrypt { 2405 send SynchronizeGroupKeys; 2407 } 2409 on SynchronizeGroupKeys { 2410 do prepareOwnKeys; 2411 send GroupKeysUpdate; 2412 } 2414 on GroupKeysUpdate { 2415 if fromGroupMember // double check 2416 do saveGroupKeys; 2417 } 2419 on KeyGen { 2420 do prepareOwnKeys; 2421 send GroupKeysUpdate; 2422 } 2424 on Beacon { 2425 do openNegotiation; 2426 do tellWeAreGrouped; 2427 do useOwnResponse; 2428 send NegotiationRequestGrouped; 2429 do useOwnChallenge; 2430 } 2432 on NegotiationOpen { 2433 if sameResponse { 2434 do storeNegotiation; 2435 do useThisKey; 2436 send GroupHandshake; 2437 go HandshakingGrouped; 2438 } 2439 } 2441 on GroupHandshake { 2442 do storeNegotiation; 2443 do storeThisKey; 2444 go HandshakingGrouped; 2445 } 2447 on GroupTrustThisKey { 2448 if fromGroupMember // double check 2449 do trustThisKey; 2450 } 2452 on LeaveDeviceGroup { 2453 send InitUnledGroupKeyReset; 2454 do disable; 2455 do resetOwnKeysUngrouped; 2456 } 2458 on InitUnledGroupKeyReset { 2459 do useOwnResponse; 2460 send ElectGroupKeyResetLeader; 2461 go GroupKeyResetElection; 2462 } 2463 } 2465 state GroupKeyResetElection { 2466 on ElectGroupKeyResetLeader { 2467 if sameResponse { 2468 // the first one is from us, we're leading this 2469 do resetOwnGroupedKeys; 2470 go Grouped; 2471 } 2472 else { 2473 // the first one is not from us 2474 go Grouped; 2475 } 2476 } 2477 } 2479 // sole device handshaking with group 2480 state HandshakingToJoin { 2481 on Init 2482 do showJoinGroupHandshake; 2484 // Cancel is Rollback 2485 on Cancel { 2486 send Rollback; 2487 go Sole; 2488 } 2490 on Rollback { 2491 if sameNegotiation 2492 go Sole; 2493 } 2495 // Reject is CommitReject 2496 on Reject { 2497 send CommitReject; 2498 do disable; 2499 go End; 2500 } 2502 on CommitAcceptForGroup { 2503 if sameNegotiation 2504 go HandshakingToJoinPhase2; 2505 } 2507 on CommitReject { 2508 if sameNegotiation { 2509 do disable; 2510 go End; 2511 } 2512 } 2514 // Accept is Phase1Commit 2515 on Accept { 2516 do trustThisKey; 2517 go HandshakingToJoinPhase1; 2518 } 2519 } 2521 state HandshakingToJoinPhase1 { 2522 on Rollback { 2523 if sameNegotiation { 2524 do untrustThisKey; 2525 go Sole; 2526 } 2527 } 2529 on CommitReject { 2530 if sameNegotiation { 2531 do untrustThisKey; 2532 do disable; 2533 go End; 2534 } 2535 } 2537 on CommitAcceptForGroup { 2538 if sameNegotiation { 2539 send CommitAccept; 2540 go JoiningGroup; 2541 } 2542 } 2543 } 2545 state HandshakingToJoinPhase2 { 2546 on Cancel { 2547 send Rollback; 2548 go Sole; 2549 } 2550 on Reject { 2551 send CommitReject; 2552 do disable; 2553 go End; 2554 } 2556 on Accept { 2557 do trustThisKey; 2558 send CommitAccept; 2559 go JoiningGroup; 2560 } 2561 } 2563 state JoiningGroup { 2564 on Init { 2565 // we need to keep in memory which keys we have before 2566 // joining 2567 do prepareOwnKeys; 2568 do backupOwnKeys; 2569 } 2570 on GroupKeysForNewMember { 2571 if sameNegotiationAndPartner { 2572 do saveGroupKeys; 2573 do receivedKeysAreDefaultKeys; 2574 // send the keys we had before joining 2575 do prepareOwnKeysFromBackup; 2576 send GroupKeysAndClose; 2577 do showDeviceAdded; 2578 go Grouped; 2579 } 2580 } 2581 } 2583 state HandshakingGrouped { 2584 on Init 2585 do showGroupedHandshake; 2587 // Cancel is Rollback 2588 on Cancel { 2589 send Rollback; 2590 go Grouped; 2591 } 2593 on Rollback { 2594 if sameNegotiation 2595 go Grouped; 2596 } 2597 // Reject is CommitReject 2598 on Reject { 2599 send CommitReject; 2600 go Grouped; 2601 } 2603 on CommitReject { 2604 if sameNegotiation 2605 go Grouped; 2606 } 2608 // Accept is Phase1Commit 2609 on Accept { 2610 do trustThisKey; 2611 go HandshakingGroupedPhase1; 2612 } 2614 on GroupTrustThisKey { 2615 if fromGroupMember { // double check 2616 do trustThisKey; 2617 if sameNegotiation 2618 go Grouped; 2619 } 2620 } 2622 on GroupKeysUpdate { 2623 if fromGroupMember // double check 2624 do saveGroupKeys; 2625 } 2626 } 2628 state HandshakingGroupedPhase1 { 2629 on Init { 2630 send GroupTrustThisKey; 2631 send CommitAcceptForGroup; 2632 } 2634 on Rollback { 2635 if sameNegotiation { 2636 do untrustThisKey; 2637 go Grouped; 2638 } 2639 } 2641 on CommitReject { 2642 if sameNegotiation { 2643 do untrustThisKey; 2644 go Grouped; 2646 } 2647 } 2649 on CommitAccept { 2650 if sameNegotiation { 2651 do prepareOwnKeys; 2652 send GroupKeysForNewMember; 2653 do showDeviceAccepted; 2654 go Grouped; 2655 } 2656 } 2658 on GroupTrustThisKey { 2659 if fromGroupMember // double check 2660 do trustThisKey; 2661 } 2663 on GroupKeysUpdate { 2664 if fromGroupMember // double check 2665 do saveGroupKeys; 2666 } 2668 on GroupKeysAndClose { 2669 if fromGroupMember { // double check 2670 // do not save GroupKeys as default keys; 2671 // key data is already imported 2672 go Grouped; 2673 } 2674 } 2675 } 2677 external Accept 129; 2678 external Reject 130; 2679 external Cancel 131; 2681 // beacons are always broadcasted 2683 message Beacon 2, type=broadcast, ratelimit=10, 2684 security=unencrypted { 2685 field TID challenge; 2686 auto Version version; 2687 } 2689 message NegotiationRequest 3, security=untrusted { 2690 field TID challenge; 2691 field TID response; 2692 auto Version version; 2693 field TID negotiation; 2694 field bool is_group; 2695 } 2697 message NegotiationOpen 4, security=untrusted { 2698 field TID response; 2699 auto Version version; 2700 field TID negotiation; 2701 } 2703 message Rollback 5, security=untrusted { 2704 field TID negotiation; 2705 } 2707 message CommitReject 6, security=untrusted { 2708 field TID negotiation; 2709 } 2711 message CommitAcceptOfferer 7, security=untrusted { 2712 field TID negotiation; 2713 } 2715 message CommitAcceptRequester 8, security=untrusted { 2716 field TID negotiation; 2717 } 2719 message CommitAccept 9, security=untrusted { 2720 field TID negotiation; 2721 } 2723 message CommitAcceptForGroup 10, security=untrusted { 2724 field TID negotiation; 2725 } 2727 // default: security=trusted 2728 // messages are only accepted when coming from the device group 2729 message GroupTrustThisKey 11 { 2730 field Hash key; 2731 field TID negotiation; 2732 } 2734 // trust in future 2735 message GroupKeysForNewMember 12, 2736 security=attach_own_keys_for_new_member { 2737 field IdentityList ownIdentities; 2738 } 2740 message GroupKeysAndClose 13, 2741 security=attach_own_keys_for_group { 2742 field IdentityList ownIdentities; 2743 } 2745 message OwnKeysOfferer 14, security=attach_own_keys_for_group { 2746 field IdentityList ownIdentities; 2747 } 2749 message OwnKeysRequester 15, 2750 security=attach_own_keys_for_new_member { 2751 field IdentityList ownIdentities; 2752 } 2754 // grouped handshake 2755 message NegotiationRequestGrouped 16, security=untrusted { 2756 field TID challenge; 2757 field TID response; 2758 auto Version version; 2759 field TID negotiation; 2760 field bool is_group; 2761 } 2763 message GroupHandshake 17 { 2764 field TID negotiation; 2765 field Hash key; 2766 } 2768 // update group 2769 message GroupKeysUpdate 18, security=attach_own_keys_for_group { 2770 field IdentityList ownIdentities; 2771 } 2773 // initiate unled group key reset 2774 message InitUnledGroupKeyReset 19 { 2775 } 2777 message ElectGroupKeyResetLeader 20 { 2778 field TID response; 2779 } 2781 message SynchronizeGroupKeys 21, ratelimit=60 { 2782 } 2783 } 2784 } 2785 B.2. ASN.1 Type Definitions 2787 Below you can find the ASN.1 Type definitions for the messages used 2788 in pEp KeySync FSM. 2790 -- This file is under BSD License 2.0 2792 -- Sync protocol for pEp 2793 -- Copyright (c) 2016, 2017 pEp foundation 2795 -- Written by Volker Birk 2797 pEp 2798 { iso(1) org(3) dod(6) internet(1) private(4) enterprise(1) 2799 pEp(47878) basic(0) } 2801 DEFINITIONS AUTOMATIC TAGS EXTENSIBILITY IMPLIED ::= 2803 BEGIN 2805 EXPORTS Identity, IdentityList, TID, Hash, Version; 2807 ISO639-1 ::= PrintableString(FROM ("a".."z")) (SIZE(2)) 2808 Hex ::= PrintableString(FROM ("A".."F") | FROM ("0".."9")) 2809 Hash ::= Hex(SIZE(16..128)) -- 32bit Key ID to SHA512 in hex 2810 PString ::= UTF8String (SIZE(1..1024)) 2811 TID ::= OCTET STRING (SIZE(16)) -- UUID version 4 variant 1 2813 Identity ::= SEQUENCE { 2814 address PString, 2815 fpr Hash, 2816 user-id PString, 2817 username PString, 2818 comm-type INTEGER (0..255), 2819 lang ISO639-1 2820 } 2822 IdentityList ::= SEQUENCE OF Identity 2824 Version ::= SEQUENCE { 2825 major INTEGER (0..255) DEFAULT 1, 2826 minor INTEGER (0..255) DEFAULT 2 2827 } 2829 END 2831 Appendix C. Document Changelog 2833 [[ RFC Editor: This section is to be removed before publication ]] 2835 o draft-pep-keysync-02: 2837 * Improve clarity and readability 2839 * Updated Section 2.1.1 2841 o draft-pep-keysync-01: 2843 * Updated FSM states, actions, messages, events and interaction 2844 diagrams to reflect recent design changes 2846 * added latest revision of code and ASN.1 Type definitions 2848 o draft-pep-keysync-00: 2850 * Updated docname and author's section 2852 o draft-hoeneisen-pep-keysync-01: 2854 * Major rewrite of upper sections 2856 * Adjust to reflect code changes 2858 * Move Finite State Machine reference and code to Appendices A & 2859 B 2861 o draft-hoeneisen-pep-keysync-00: 2863 * Initial version 2865 Appendix D. Open Issues 2867 [[ RFC Editor: This section should be empty and is to be removed 2868 before publication ]] 2870 o Resolve several TODOs / add missing text 2872 Authors' Addresses 2873 Volker Birk 2874 pEp Foundation 2875 Oberer Graben 4 2876 CH-8400 Winterthur 2877 Switzerland 2879 Email: volker.birk@pep.foundation 2880 URI: https://pep.foundation/ 2882 Bernie Hoeneisen 2883 pEp Foundation 2884 Oberer Graben 4 2885 CH-8400 Winterthur 2886 Switzerland 2888 Email: bernie.hoeneisen@pep.foundation 2889 URI: https://pep.foundation/ 2891 Kelly Bristol 2892 pEp Foundation 2893 Oberer Graben 4 2894 CH-8400 Winterthur 2895 Switzerland 2897 Email: kelly.bristol@pep.foundation 2898 URI: https://pep.foundation/