idnits 2.17.1 draft-pep-keysync-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 10, 2020) is 1384 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: 3 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 11, 2021 pEp Foundation 6 July 10, 2020 8 pretty Easy privacy (pEp): Key Synchronization Protocol (KeySync) 9 draft-pep-keysync-01 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 11, 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 . . . . . . . . . . . . . . . . 25 77 2.2.4. Leave Device Group . . . . . . . . . . . . . . . . . 25 78 2.2.5. Remove other Device from Device Group . . . . . . . . 25 79 3. Security Considerations . . . . . . . . . . . . . . . . . . . 25 80 4. Privacy Considerations . . . . . . . . . . . . . . . . . . . 25 81 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 82 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 26 83 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 84 7.1. Normative References . . . . . . . . . . . . . . . . . . 26 85 7.2. Informative References . . . . . . . . . . . . . . . . . 26 86 Appendix A. Reference Implementation . . . . . . . . . . . . . . 27 87 A.1. Description of Finite-State Machine . . . . . . . . . . . 27 88 A.1.1. States . . . . . . . . . . . . . . . . . . . . . . . 28 89 A.1.2. Conditions . . . . . . . . . . . . . . . . . . . . . 37 90 A.1.3. Actions . . . . . . . . . . . . . . . . . . . . . . . 39 91 A.1.4. Transitions . . . . . . . . . . . . . . . . . . . . . 45 92 A.1.5. Events . . . . . . . . . . . . . . . . . . . . . . . 45 93 A.1.6. Messages . . . . . . . . . . . . . . . . . . . . . . 46 94 Appendix B. Code excerpts . . . . . . . . . . . . . . . . . . . 49 95 B.1. Finite-State Machine . . . . . . . . . . . . . . . . . . 49 96 B.2. ASN.1 Type Definitions . . . . . . . . . . . . . . . . . 63 97 Appendix C. Document Changelog . . . . . . . . . . . . . . . . . 64 98 Appendix D. Open Issues . . . . . . . . . . . . . . . . . . . . 65 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 65 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, an identity might be a specific 171 email address, and the common channel would be a mailbox for that 172 email address. 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 having a user form a Device Group 226 among their devices. During this process, a Handshake process 227 occurs, and the user will be presented with a Trustwords dialog 228 between any two devices at a time for pairing purposes. (cf. 229 [I-D.birk-pep-trustwords]) Simply put, a user MUST manually complete 230 the 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, the pEp KeySync protocol 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 is a 275 communication channel with an email address. Let us call these 276 devices Alice_Mobile and Alice_Tablet. Each device already has its 277 own key pair, which was automatically generated by the pEp protocol. 278 Neither device knows anything about the other. 280 Alice wants full communication capability from both of her devices, 281 but currently cannot do so, as the devices do not know about each 282 other. Alice will use pEp KeySync to form a Device Group and add her 283 devices to it. This allows for the exchange of private key data 284 among its devices, allowing Alice to have full communication 285 capability on both of her devices. 287 2.1.2. Add New Device to Existing Device Group 289 Sometime after devices Alice_Mobile and Alice_Tablet have formed a 290 Device Group (cf. Section 2.1.1), Alice buys another device, 291 Alice_Laptop, which is also configured with pEp-implementing 292 messaging clients and shares the same identity for her preferred 293 communication channel (the aforementioned email address). 294 Alice_Laptop also has a key pair, which was automatically generated 295 by the pEp protocol, just as the Grouped Devices Alice_Mobile and 296 Alice_Tablet have. But while the Grouped Devices know each other and 297 have exchanged private keys, Alice_Laptop and the Grouped Devices 298 don't know each other. Thus, Alice does not have full communication 299 capability across the three devices. 301 As before with devices Alice_Mobile and Alice_Tablet, Alice will use 302 pEp KeySync to add device Alice_Laptop to the existing Device Group, 303 allowing all three devices to exchange private key information, and 304 Alice to have access to her messages from any of them. 306 2.1.3. Exchange Private Keys 308 All devices from Alice are part of a Device Group (cf. Section 2.1.1 309 and Section 2.1.2). However, as keys may expire or get reset, it is 310 inevitable that new key pairs will be generated. For Alice to 311 maintain her ability to read all encrypted messages on all devices, 312 any new private key needs to be shared with the other devices in the 313 device group. All devices in Alice's Device Group will share the 314 latest private keys as they are generated, keeping all of her devices 315 up to date and functioning as desired. 317 2.1.4. Leave Device Group 319 Alice decides that her mobile phone, Alice_Mobile, should no longer 320 have access to all private keys of the Device Group. Alice can 321 manually tell her mobile phone to leave the Device Group by turning 322 off the pEp Sync feature on her device, which deactivates KeySync. 323 The Device Group is dissolved, and Sync is disabled on her mobile 324 phone. This action also initiates the pEp KeyReset protocol, which 325 resets keys for all own identities. 327 In the future, if Alice desires, she can re-add her mobile phone to a 328 Device Group, but she will first have to re-enable Sync, and then 329 initiate the joining procedure again (cf. Section 2.1.1 and 330 Section 2.1.2). 332 2.1.5. Remove other Device from Device Group 334 One of Alice's devices may be stolen or become otherwise compromised. 335 She needs to ensure that the affected device no longer receives 336 updates to private keys from the other devices in her Device Group. 337 Using one of her remaining Grouped Devices, Alice can disable pEp 338 Sync (and thus KeySync) on her remaining devices. This action 339 dissolves the Device Group and initiates the pEp KeyReset protocol. 341 2.2. Interaction Diagrams 343 The following interaction diagrams depict what happens during Alice's 344 KeySync scenarios in a simplified manner. For each scenario, we 345 first present a successful case, then an unsuccessful case and, 346 finally, a case that has been interrupted, or discontinued. Some 347 details are skipped here for the sake of readability. Descriptions 348 of the interactions are included after each diagram. 350 Each pEp-enabled device runs its own Finite-State Machine (FSM), 351 which interact with each other throughout the KeySync process, and 352 drive the UI options presented to the user. All messages are 353 'broadcast' between devices. The TIDs added to each message allow 354 the identification of received messages which pertain to the ongoing 355 transaction and its sender. 357 For events requiring user interaction in order to proceed, it does 358 not matter which device has the specified option chosen first unless 359 otherwise indicated. For example, if an event states that the 360 'Offerer' chooses 'Accept' to continue, the process will be 361 unaffected if the 'Requester' device does so first. The only 362 difference is that the order of the roles for the remainder of the 363 given scenario will be swapped. 365 2.2.1. Form Device Group 367 2.2.1.1. Successful Case 369 ,-. 370 `-' 371 /|\ 372 | 373 ,----------------. / \ ,------------------. 374 |'Offerer' device| User |'Requester' device| 375 `-------+--------' | `--------+---------' 376 | | | 377 | | | 378 | 1(r). Beacon (challenge TID) | 379 |<--------------------------------------------| 380 | | | 381 | 1(o). Beacon (challenge TID) | 382 |-------------------------------------------->| 383 | | | 384 | 2. NegotiationRequest | 385 |<--------------------------------------------| 386 | | | 387 | | 3. Display Trustwords| 388 | |<- - - - - - - - - - -| 389 | | | 390 | 4. NegotiationOpen | 391 |-------------------------------------------->| 392 | | | 393 | 5. Display Trustwords| | 394 | - - - - - - - - - - >| | 395 | | | 396 | ,-----------------------------. | 397 | |Handshake (user comparison | | 398 | |of Trustwords) successful | | 399 | `-----------------------------' | 400 | | | 401 ,-----------------------------------. | 402 |User presses 'Accept' button | | 403 |on 'Requester' device | | 404 `-----------------------------------' | 405 | | 6. Accept | 406 | | - - - - - - - - - - >| 407 | | | 408 | 7. CommitAcceptRequester | 409 |<--------------------------------------------| 410 | | | 411 | | | 412 ,-----------------------------------. | 413 |User presses 'Accept' button | | 414 |on 'Offerer' device | | 415 `-----------------------------------' | 416 | 8. Accept | | 417 |<- - - - - - - - - - -| | 418 | | | 419 | 9. CommitAcceptOfferer | 420 |-------------------------------------------->| 421 | | | 422 | 10. OwnKeysRequester + keys | 423 |<--------------------------------------------| 424 | | | 425 ,--------------------. | | 426 |Offerer is Grouped | | | 427 `--------------------' | | 428 | | | 429 | 11. OwnKeysOfferer + keys | 430 |-------------------------------------------->| 431 | | | 432 | | ,----------------------. 433 | | |Requester is Grouped | 434 | | `----------------------' 435 | | | 436 | | | 437 ,-------+--------. | ,--------+---------. 438 |'Offerer' device| User |'Requester' device| 439 `----------------' ,-. `------------------' 440 `-' 441 /|\ 442 | 443 / \ 445 As depicted above, a user intends to form a Device Group in order to 446 securely share key material among its members. The group is formed 447 by an 'Offerer' device and a 'Requester' device. The names 'Offerer' 448 and 'Requester' are derived from the FSM (cf. Appendix A.1), in 449 which the device roles are defined during the start sequence, which 450 is necessary for the FSM to work as intended. 452 During initialization of pEp KeySync, each device generates a 453 Transaction-ID (TID). These TIDs are sent as a Challenge in a Beacon 454 over the mutual channel, and the device roles of 'Offerer' and 455 'Requester' are determined by the numeric value of each device's 456 unique TID. 458 1. Every device sends a Beacon message containing a Challenge TID. 459 Upon receipt of a Beacon message from another device, the 460 received Challenge TID is compared with the device's own 461 Challenge TID. The device which has a TID with a lower 462 numerical value is assigned as the 'Requester', and the other 463 device is automatically assigned as the 'Offerer'. 465 Note: The 'Offerer' device MUST NOT start a negotiation. In the 466 event the earlier Beacon message is lost, the 'Offerer' device 467 re-sends its own Beacon and waits for a response. Message 1(r) 468 depicts the Beacon message sent by the 'Requester' device and is 469 not required for the process to continue. 471 2. After determination of the role, the 'Requester' device sends a 472 NegotiationRequest message. 474 3. The 'Requester' device displays the Trustwords to the user. 476 4. Upon receipt of the NegotiationRequest message, the 'Offerer' 477 device sends a NegotiationOpen message. 479 5. The 'Offerer' device displays the Trustwords to the user. 481 6. The user compares the Trustwords of both devices. As the 482 Trustwords are the same on both devices, the user chooses the 483 'Accept' option on the 'Requester' device. 485 Note: The user may choose 'Accept' on the 'Offerer' device 486 first, in which case the sequence of the messages is slightly 487 different (i.e. message 8 is sent before message 6). However, 488 the result will be exactly the same. 490 7. On receipt of the user's 'Accept', the 'Requester' device sends 491 a CommitAcceptRequester message. 493 The 'Offerer' device receives this message and waits for the 494 user to choose 'Accept'. 496 8. The user compares the Trustwords of both devices and chooses the 497 'Accept' option on the 'Offerer' device. 499 9. Once the user chooses 'Accept', the 'Offerer' device sends a 500 CommitAcceptOfferer message. 502 10. Upon receipt of the CommitAcceptOfferer message, the 'Requester' 503 device sends an OwnKeysRequester message along with the user's 504 local key pairs (private and public keys) to be synchronized. 506 11. Upon receipt of the OwnKeysRequester message, the 'Offerer' 507 device saves the 'Requester' keys combined with the 'Offerer' 508 keys. This means that the 'Offerer' device is grouped. The 509 'Offerer' device sends an OwnKeysOfferer message along with the 510 own original local key pairs (private and public keys) to be 511 synchronized. 513 Upon receipt of the OwnKeysOfferer message, the 'Requester' 514 device saves the 'Offerer' keys combined with the 'Requester' 515 keys. This means that the 'Requester' device is also grouped. 516 The formation of the Device Group has been successful. 518 2.2.1.2. Unsuccessful Case 520 ,-. 521 `-' 522 /|\ 523 | 524 ,----------------. / \ ,------------------. 525 |'Offerer' device| User |'Requester' device| 526 `-------+--------' | `--------+---------' 527 | | | 528 | | | 529 ,--------------------------------------------------------------!. 530 |Messages (1-5) are same as in the successful case (see above) |_\ 531 `----------------------------------------------------------------' 532 | | | 533 | | | 534 | ,-----------------------------. | 535 | |Handshake (user comparison | | 536 | |of Trustwords) unsuccessful | | 537 | `-----------------------------' | 538 | ,------------------------------------. 539 | |User presses 'Reject' button | 540 | |on 'Requester' device | 541 | `------------------------------------' 542 | | R6. Reject | 543 | | - - - - - - - - - - >| 544 | | | 545 | R7. CommitReject | 546 |<-------------------------------------------| 547 | | | 548 ,--------------------------------------------------------------!. 549 | Devices (still not grouped) will not try again |_\ 550 `----------------------------------------------------------------' 551 | | | 552 ,-------+--------. | ,--------+---------. 553 |'Offerer' device| User |'Requester' device| 554 `----------------' ,-. `------------------' 555 `-' 556 /|\ 557 | 558 / \ 560 For unsuccessful KeySync attempts, messages 1-5 are the same as in a 561 successful attempt (see above), but once the Trustwords are shown, 562 events are as follows: 564 R6. The user compares the Trustwords of both devices. As the 565 Trustwords do not match, the user chooses the 'Reject' option 566 on the 'Requester' device. 568 Note: The user may choose 'Reject' on the 'Offerer' device, in 569 which case the origin and/or destination of the messages 570 change. However, the result will be exactly the same. 572 R7. On receipt of the user's 'Reject', the 'Requester' device sends 573 a CommitReject message. 575 Once the CommitReject message is sent or received, respectively, the 576 devices cannot form a Device Group, and pEp KeySync is disabled on 577 both devices. As a result, there are no further attempts to form a 578 Device Group involving either of these two devices. KeySync may be 579 re-enabled in the pEp settings on the affected device(s). 581 2.2.1.3. Discontinuation Case 583 ,-. 584 `-' 585 /|\ 586 | 587 ,----------------. / \ ,------------------. 588 |'Offerer' device| User |'Requester' device| 589 `-------+--------' | `--------+---------' 590 | | | 591 | | | 592 ,--------------------------------------------------------------!. 593 |Messages (1-5) are same as in the successful case (see above) |_\ 594 `----------------------------------------------------------------' 595 | | | 596 | | | 597 | ,-----------------------------. | 598 | |Handshake (user comparison | | 599 | |of Trustwords) discontinued | | 600 | `-----------------------------' | 601 | ,------------------------------------. 602 | |User presses 'Cancel' button | 603 | |on 'Requester' device | 604 | `------------------------------------' 605 | | C6. Cancel | 606 | | - - - - - - - - - - >| 607 | | | 608 | C7. Rollback | 609 |<-------------------------------------------| 610 | | | 611 ,--------------------------------------------------------------!. 612 | Devices (still not grouped) will try again |_\ 613 `----------------------------------------------------------------' 614 | | | 615 ,-------+--------. | ,--------+---------. 616 |'Offerer' device| User |'Requester' device| 617 `----------------' ,-. `------------------' 618 `-' 619 /|\ 620 | 621 / \ 623 For discontinued (canceled) KeySync attempts, messages 1-5 are the 624 same as in a successful attempt (see above), but once the Trustwords 625 are shown, events are as follows: 627 C6. The user decides to discontinue the process and chooses the 628 'Cancel' option on the 'Requester' device. 630 Note: The user may choose 'Cancel' on the 'Offerer' device, in 631 which case the origin and/or destination of the messages 632 change. However, the result will be exactly the same. 634 C7. On receipt of the user's 'Cancel', the 'Requester' device sends 635 a rollback message. 637 The devices do not form a Device Group. KeySync remains enabled on 638 both devices, and forming a Device Group can start again. 640 2.2.2. Add New Device to Existing Device Group 642 2.2.2.1. Successful Case 644 ,-------. ,-. 645 |New | `-' ,--------. ,--------. 646 |device | /|\ |Active | |Passive | 647 |to join| | |device | |devices | 648 |group | / \ |in group| |in group| 649 `---+---' User `---+----' `---+----' 650 | | | | 651 | | | | 652 | 1. Beacon | | 653 |--------------------------------->|------------------>| 654 | | | | 655 | 2(w). NegotiationRequestGrouped | | 656 |<---------------------------------| | 657 | | | | 658 | 2(l). NegotiationRequestGrouped (discarded) | 659 |<-----------------------------------------------------| 660 | | | | 661 | 3. NegotiationOpen | | 662 |--------------------------------->| | 663 | 4. Display | | | 664 | Trustwords | | | 665 | - - - - - - - >| | | 666 | | | 5. GroupHandshake | 667 | | 6(w). Display |------------------>| 668 | | Trustwords | | 669 | |<- - - - - - - - | | 670 | | | | 671 | | 6(l) Display Trustwords | 672 | |<- - - - - - - - - - - - - - - - - - | 673 | | | | 674 | ,-----------------------------. | | 675 | |Handshake (user comparison | | | 676 | |of Trustwords) successful | | | 677 | `-----------------------------' | | 678 | | | | 679 | ,------------------------------. | 680 | |User presses 'Accept' button | | 681 | |on a device in group | | 682 | `------------------------------' | 683 | | 7. Accept | | 684 | | - - - - - - - ->| | 685 | | | 8. GroupTrust | 686 | | | ThisKey | 687 | | |------------------>| 688 | | | | 689 | 9. CommitAcceptForGroup | | 690 |<---------------------------------| | 691 | | | | 692 ,------------------------------. | | 693 |User presses 'Accept' button | | | 694 |on new device | | | 695 `------------------------------' | | 696 | 10. Accept | | | 697 |<- - - - - - - -| | | 698 | | | | 699 | 11. CommitAccept | | 700 |--------------------------------->| | 701 | | | | 702 | 12. GroupKeysForNewMember (key data) | 703 |<---------------------------------| | 704 | | | | 705 ,------------. | | | 706 |New device | | | | 707 |is grouped | | | | 708 `------------' | | | 709 | | | | 710 | 13. GroupKeysAndClose (key data) | | 711 |--------------------------------->| | 712 | | | | 713 | | ,------------. | 714 | | |New device | | 715 | | |is accepted | | 716 | | `------------' | 717 | | | | 718 | 13. GroupKeysAndClose (key data) | 719 |----------------------------------------------------->| 720 | | | | 721 | | | ,------------. 722 | | | |New device | 723 | | | |is accepted | 724 | | | `------------' 725 | | | | 726 ,---+---. User ,---+----. ,---+----. 727 |New | ,-. |Active | |Passive | 728 |device | `-' |device | |devices | 729 |to join| /|\ |in group| |in group| 730 |group | | `--------' `--------' 731 `-------' / \ 733 As depicted above, a user intends to add a new device to an existing 734 Device Group. 736 1. During initialization of pEp KeySync, the new device sends a 737 Beacon message. 739 2. Upon receipt of a Beacon message from a device not part of a 740 Device Group, all Grouped Devices send a 741 NegotiationRequestGrouped message. 743 Note: Messages 2(w) and 2(l) are instances of the same 744 (NegotiationRequest) message type sent from different devices. 746 3. Upon receipt of the NegotiationRequestGrouped message 2(w), the 747 New Device answers with a NegotiationOpen message. 749 Note 1: Only the first NegotiationRequestGrouped message is 750 processed. In this example message 2(w) (from "winner") is 751 processed, while message 2(l) (from "loser") will be ignored. 752 The result will be the same, no matter which 753 NegotiationRequestGrouped message is processed. 755 Note 2: With regards to Active or Passive roles, at this stage 756 all grouped devices are indifferent, i.e. the active or passive 757 role will be determined only at some later stage (i.e. step 7). 759 4. The new device displays the Trustwords to the user. 761 5. Up on receipt of the NegotiationOpen message, the "winner" 762 device sends a GroupHandshake message to the "loser" device(s), 763 to indicate that a new device wants to join the Device Group. 765 6. All Grouped Devices display the Trustwords to the user: the 766 "winner" device as a result of receiving the NegotiationOpen 767 message, the "loser" device(s) as result receiving 768 GroupHandshake message. 770 Note: Messages 6(w) and 6(l) are instances of the same action on 771 different devices. 773 7. The user compares the Trustwords of both devices and chooses the 774 'Accept' option on one of the Grouped Devices. 776 Note 1: The Grouped Device that the user chooses the 'Accept' 777 option from assumes the role of the 'Active Device' (for the 778 Device Group), while the other device(s) in the same Device 779 Group assume the role of a 'Passive Device'. 781 Note 2: The user may choose 'Accept' on the new device first, in 782 which case sequence of the messages is slightly different (i.e. 783 message 10 is sent before message 7). However, the result will 784 be exactly the same. 786 8. On receipt of the user's 'Accept', the 'Active Device' sends a 787 GroupTrustThisKey message to the Passive Device(s) in the same 788 Device Group. 790 9. The Active Device also sends a CommitAcceptForGroup message to 791 the new device. Upon receipt, the new device waits for the user 792 to choose 'Accept'. 794 10. The user compares the Trustwords of both devices and chooses the 795 'Accept' option also on the new device. 797 11. Once the user chooses 'Accept', the new device sends a 798 CommitAccept message to the Active Device. 800 12. Upon receipt of the CommitAccept message, the 'Active Device' 801 device sends a GroupKeysForNewMember message along with the 802 user's local key pairs (private and public keys) to be 803 synchronized. 805 13. Upon receipt of the GroupKeysForNewMember message, the new 806 device saves the received keys combined with its own keys. This 807 means that the new device has successfully joined the Device 808 Group. 810 The new device (now grouped) sends an GroupKeysAndClose message 811 along with its own original local key pairs (private and public 812 keys) to be synchronized. 814 Note: In the diagram, all messages marked "13. 815 GroupKeysAndClose (key data)" are a single message, but drawn 816 separately in order to convey that the message is sent to all 817 devices in the Device Group. 819 Upon receipt of the GroupKeysAndClose message, the 'Active 820 Device' as well as the 'Passive Device(s)' save the received 821 keys combined with its own keys. This means that the new device 822 has been accepted by the 'Active Device' and the 'Passive 823 Device(s)'. All keys are now synchronized among the devices. 825 Note: There is no Event Handler to process the GroupKeysAndClose 826 message explicitly, as all decryptable messages containing keys 827 are implicitly processed and the received keys saved. 829 [[ TODO: Decide whether the implicit importing keys should 830 rather be replaced by explicit actions in Event Handlers. ]] 832 2.2.2.2. Unsuccessful Case 834 ,-------. ,-. 835 |New | `-' ,--------. ,--------. 836 |device | /|\ |Active | |Passive | 837 |to join| | |device | |devices | 838 |group | / \ |in group| |in group| 839 `---+---' User `---+----' `---+----' 840 | | | | 841 | | | | 842 ,---------------------------------------------------------------!. 843 |Messages (1-6) are same as in the successful case (see above) |_\ 844 `-----------------------------------------------------------------' 845 | | | | 846 | | | | 847 | ,-----------------------------. | | 848 | |Handshake (user comparison | | | 849 | |of Trustwords) unsuccessful | | | 850 | `-----------------------------' | | 851 | ,------------------------------. | 852 | |User presses 'Reject' button | | 853 | |on a device in group | | 854 | `------------------------------' | 855 | | R7. Reject | | 856 | | - - - - - - - ->| | 857 | | | | 858 | R8. CommitReject | | 859 |<---------------------------------|------------------>| 860 | | | | 861 ,----------!. | | | 862 |New device|_\ | | | 863 |(still not | | | | 864 |grouped) | | | | 865 |will not | | | | 866 |try again | | | | 867 `------------' | | | 868 | | | | 869 ,---+---. User ,---+----. ,---+----. 870 |New | ,-. |Active | |Passive | 871 |device | `-' |device | |devices | 872 |to join| /|\ |in group| |in group| 873 |group | | `--------' `--------' 874 `-------' / \ 876 For unsuccessful KeySync attempts, messages 1-6 are the same as in a 877 successful attempt (see above), but once the Trustwords are shown, 878 events are as follows: 880 R7. The user compares the Trustwords displayed on both devices. If 881 the Trustwords do not match, the user chooses the 'Reject' option 882 on one of the Grouped Devices (which becomes the 'Active 883 Device'). 885 Note: The user may choose 'Reject' on the new device, in which 886 case the origin and/or destination of the messages 887 change. However, the result will be exactly the same. 889 R8. Upon receipt of the 'Reject' event, the 'Active Device' sends 890 a CommitReject message to both the new device which attempted to 891 join, and the 'Passive Device(s)' in the Device Group. 893 Note: In the diagram, "R8. CommitReject" represents the message 894 that is sent to all devices participating in the handshake. 896 Once the CommitReject message is sent or received, respectively, the 897 new device cannot join the Device Group, and pEp KeySync is disabled 898 on the new device. As a result, there are no further attempts to 899 join a Device Group by the new device. pEp KeySync may be re-enabled 900 in the pEp settings on the affected device. 902 2.2.2.3. Discontinuation Case 904 ,-------. ,-. 905 |New | `-' ,--------. ,--------. 906 |device | /|\ |Active | |Passive | 907 |to join| | |device | |devices | 908 |group | / \ |in group| |in group| 909 `---+---' User `---+----' `---+----' 910 | | | | 911 | | | | 912 ,---------------------------------------------------------------!. 913 |Messages (1-6) are same as in the successful case (see above) |_\ 914 `-----------------------------------------------------------------' 915 | | | | 916 | | | | 917 | ,-----------------------------. | | 918 | |Handshake (user comparison | | | 919 | |of Trustwords) discontinued | | | 920 | `-----------------------------' | | 921 | ,------------------------------. | 922 | |User presses 'Cancel' button | | 923 | |on a device in group | | 924 | `------------------------------' | 925 | | C7. Cancel | | 926 | | - - - - - - - ->| | 927 | | | | 928 | C8. Rollback | | 929 |<---------------------------------|------------------>| 930 | | | | 931 ,----------!. | | | 932 |New device|_\ | | | 933 |(still not | | | | 934 |grouped) | | | | 935 |will try | | | | 936 |again | | | | 937 `------------' | | | 938 | | | | 939 ,---+---. User ,---+----. ,---+----. 940 |New | ,-. |Active | |Passive | 941 |device | `-' |device | |devices | 942 |to join| /|\ |in group| |in group| 943 |group | | `--------' `--------' 944 `-------' / \ 946 For discontinued (canceled) KeySync attempts, messages 1-6 are the 947 same as in a successful attempt (see above), but once the Trustwords 948 are shown, events are as follows: 950 C7. The user decides to discontinue the process and chooses the 951 'Cancel' option on one of the Grouped Devices (which becomes the 952 'Active Device'). 954 Note: The user may choose 'Cancel' on the new device, in which 955 case the origin and/or destination of the messages 956 change. However, the result will be exactly the same. 958 C8. Upon receipt of the 'Reject' event, the 'Active Device' sends a 959 Rollback message to the new device and the 'Passive Device(s)' 961 Note: In the diagram, all messages marked "C8. Rollback" represents 962 the message that is sent to all devices participating in the handshake. 964 The new device does not join the Device Group. KeySync remains 965 enabled and joining a Device Group can start again at any time. 967 2.2.3. Exchange Private Keys 969 [[ TODO ]] 971 2.2.4. Leave Device Group 973 [[ TODO ]] 975 2.2.5. Remove other Device from Device Group 977 [[ TODO ]] 979 3. Security Considerations 981 [[ TODO ]] 983 4. Privacy Considerations 985 [[ TODO ]] 987 5. IANA Considerations 989 This document has no actions for IANA. 991 6. Acknowledgments 993 The authors would like to thank the following people who provided 994 substantial contributions, helpful comments or suggestions for this 995 document: Berna Alp, Claudio Luck, Damian Rutz, Damiano Boppart, 996 Hernani Marques, Itzel Vazquez Sandoval, Krista Bennett, Nana 997 Karlstetter, and Sofia Balicka. 999 This work was initially created by pEp Foundation, and then reviewed 1000 and extended with funding by the Internet Society's Beyond the Net 1001 Programme on standardizing pEp. [ISOC.bnet] 1003 7. References 1005 7.1. Normative References 1007 [I-D.birk-pep] 1008 Birk, V., Marques, H., and B. Hoeneisen, "pretty Easy 1009 privacy (pEp): Privacy by Default", draft-birk-pep-05 1010 (work in progress), November 2019. 1012 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1013 Requirement Levels", BCP 14, RFC 2119, 1014 DOI 10.17487/RFC2119, March 1997, 1015 . 1017 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1018 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1019 . 1021 [RFC7435] Dukhovni, V., "Opportunistic Security: Some Protection 1022 Most of the Time", RFC 7435, DOI 10.17487/RFC7435, 1023 December 2014, . 1025 7.2. Informative References 1027 [I-D.birk-pep-trustwords] 1028 Hoeneisen, B. and H. Marques, "IANA Registration of 1029 Trustword Lists: Guide, Template and IANA Considerations", 1030 draft-birk-pep-trustwords-05 (work in progress), January 1031 2020. 1033 [I-D.marques-pep-handshake] 1034 Marques, H. and B. Hoeneisen, "pretty Easy privacy (pEp): 1035 Contact and Channel Authentication through Handshake", 1036 draft-marques-pep-handshake-05 (work in progress), July 1037 2020. 1039 [ISOC.bnet] 1040 Simao, I., "Beyond the Net. 12 Innovative Projects 1041 Selected for Beyond the Net Funding. Implementing Privacy 1042 via Mass Encryption: Standardizing pretty Easy privacy's 1043 protocols", June 2017, . 1047 Appendix A. Reference Implementation 1049 [[ Note: The full Finite-State Machine code can be found in 1050 Appendix B.1. This section is not a complete reference at this time. 1051 The authors intend to refine this section in future revisions of this 1052 document. ]] 1054 The pEp KeySync Finite-State Machine is based on a two-phase commit 1055 protocol (2PC) structure. This section describes the states, 1056 actions, events, and messages which comprise the pEp KeySync FSM, and 1057 are intended to allow readers to understand the general functionality 1058 and message flow of the FSM. 1060 States are used to direct actions, events, and messages. Actions 1061 describe internal FSM functions, and fall into two general types. 1062 The first action type directs the state transitions within the FSM, 1063 and the second type drives UI functionality. Events are exchanged 1064 both between negotiation partners as well as the pEp engine itself to 1065 trigger actions and send messages. Messages contain information to 1066 ensure the integrity of the KeySync session as well as additional 1067 data, depending on the type of message (cf. Appendix A.1.6). 1069 A.1. Description of Finite-State Machine 1071 A full diagram of the implemented pEp KeySync FSM can be found at the 1072 following URL: 1074 https://gitea.pep.foundation/pEp.foundation/internet- 1075 drafts/raw/branch/master/misc/doc/figures/sync/sync_fsm_full.svg 1077 For convenience (better readability), there is also a simplified 1078 diagram of the implemented pEp KeySync FSM, which does not contain 1079 the transitions that occur when choosing the 'Cancel' or 'Reject' 1080 options. The simplified diagram can be found at the following URL: 1082 https://gitea.pep.foundation/pEp.foundation/internet- 1083 drafts/raw/branch/master/misc/doc/figures/sync/ 1084 sync_fsm_simplified.svg 1086 A.1.1. States 1088 A.1.1.1. InitState 1090 On initialization, the FSM enters InitState, which evaluates and 1091 determines a device's group status. If the device is detected to 1092 belong to a Device Group, it issues a SynchronizeGroupKeys message to 1093 the Grouped Devices (to request an update on the Group Keys), and the 1094 FSM transitions to state Grouped. Otherwise, the FSM transitions to 1095 state Sole (cf. Appendix A.1.2.1). 1097 A.1.1.2. Sole 1099 This is the default FSM state for an ungrouped device. 1101 On initialization, a Challenge TID is created and sent out inside of 1102 a Beacon message along with the device's current state. 1104 The FSM also listens for Beacons from other devices. Upon receipt of 1105 a Beacon message from another device, the received Challenge TID is 1106 compared with the own Challenge. The device with the lower Challenge 1107 TID is assigned the 'Requester' role, and the other device is 1108 automatically assigned the 'Offerer' role. If a device is determined 1109 to be the 'Offerer', it resends the Beacon. If a device is 1110 determined to be the 'Requester', it issues a NegotiationRequest 1111 event to the 'Offerer'. 1113 When the 'Offerer' device receives this NegotiationRequest message, 1114 it responds with a NegotiationOpen message, and the 'Offerer' FSM 1115 transitions to state HandshakingOfferer where it awaits the 1116 'Requester' device response. 1118 On receipt of a Grouped device's NegotiationRequestGrouped message, 1119 it responds with a NegotiationOpen message, and the 'Requester' FSM 1120 transitions to state HandshakingToJoin. 1122 On receipt of the 'Offerer' device's NegotiationOpen message, the 1123 'Requester' FSM transitions to state HandshakingRequester. 1125 In this state, other events may also be processed, but these events 1126 do not result in a transition to another state. 1128 A.1.1.3. HandshakingOfferer 1130 This state can only be entered by the 'Offerer' device from Sole 1131 state. 1133 On initialization, it drives user interface options, including the 1134 Trustwords dialog. The user is prompted to compare Trustwords and 1135 choose from the following options: 1137 o Accept: The 'Requester' public key used in the Handshake is 1138 trusted, and the FSM transitions to state 1139 HandshakingPhase1Offerer. 1141 o Reject: A CommitReject message is sent to the 'Requester' device, 1142 pEp KeySync is disabled, and the FSM transitions to state End. 1144 o Cancel: A Rollback message is sent to the 'Requester' device, and 1145 the FSM transitions to state Sole. 1147 If the user selects one of the above options on the 'Requester' 1148 device, the 'Requester' FSM sends a response to the 'Offerer' device. 1149 When this response is received, the 'Offerer' FSM performs a 1150 sameNegotiation conditional check on the current negotiation session 1151 to verify that the current session has not been disrupted or 1152 compromised. If this conditional returns 'true', the FSM proceeds as 1153 follows, depending on the message received: 1155 o CommitAcceptRequester: The 'Requester' FSM transitions to state 1156 HandshakingPhase2Offerer. 1158 o CommitReject: pEp KeySync is disabled, and the FSM transitions to 1159 state End. 1161 o Rollback: The FSM transitions to state Sole. 1163 A.1.1.4. HandshakingRequester 1165 This state can only be entered by the 'Requester' device from Sole 1166 state. 1168 On initialization, it drives user interface options, including the 1169 Trustwords dialog. The user is prompted to compare Trustwords, and 1170 choose from the following options: 1172 o Accept: The 'Offerer' public key is trusted, a 1173 CommitAcceptRequester message is sent to the 'Offerer' device, and 1174 the FSM transitions to state HandshakingPhase1Requester. 1176 o Reject: A CommitReject message is sent to the 'Offerer' device, 1177 pEp KeySync is disabled, and the FSM transitions to state End. 1179 o Cancel: A Rollback message is sent to the 'Offerer' device, and 1180 the FSM transitions to state Sole. 1182 If the user selects the 'Cancel' or the 'Reject' options on the 1183 'Offerer' device, the 'Offerer' FSM sends a response to the 1184 'Requester' device. When this response is received, the 'Requester' 1185 FSM performs a sameNegotiation conditional check on the current 1186 negotiation session to verify that the current session has not been 1187 disrupted or compromised. If this conditional returns 'true', the 1188 FSM proceeds as follows, depending on the message received: 1190 o CommitReject: pEp KeySync is disabled, and the FSM transitions to 1191 state End. 1193 o Rollback: The FSM transitions to state Sole. 1195 A.1.1.5. HandshakingPhase1Offerer 1197 This state can only be entered by the 'Offerer' device from 1198 HandshakingOfferer state. 1200 In this state the FSM awaits and processes the response from a 1201 'Requester' device in state HandshakingRequester. When this response 1202 is received, the 'Offerer' FSM performs a sameNegotiation conditional 1203 check on the current negotiation session to verify that the current 1204 session has not been disrupted or compromised. If this conditional 1205 returns 'true', the FSM proceeds as follows, depending on the message 1206 received: 1208 o CommitAcceptRequester: A CommitAcceptOfferer message is sent to 1209 the 'Requester' device, and the FSM transitions to state 1210 FormingGroupOfferer. 1212 o CommitReject: The 'Requester' public key is mistrusted, pEp 1213 KeySync is disabled, and the FSM transitions to state End. 1215 o Rollback: The 'Requester' public key is mistrusted, and the FSM 1216 transitions to state Sole. 1218 A.1.1.6. HandshakingPhase1Requester 1220 This state can only be entered by the 'Requester' device from 1221 HandshakingRequester state. 1223 In this state the FSM awaits and processes the response from an 1224 'Offerer' device in state HandshakingOfferer or 1225 HandshakingPhase2Offerer. When this response is received, the 1226 'Requester' FSM performs a sameNegotiation conditional check on the 1227 current negotiation session to verify that the current session has 1228 not been disrupted or compromised. If this conditional returns 1229 'true', the FSM proceeds as follows, depending on the message 1230 received: 1232 o CommitAcceptOfferer: The FSM prepares the Own Keys on the 1233 'Requester' device for synchronization. The FSM then issues an 1234 OwnKeysRequester message to the 'Offerer', which contains these 1235 keys, and transitions to state FormingGroupRequester. 1237 o CommitReject: The 'Offerer' public key is mistrusted, pEp KeySync 1238 is disabled, and the FSM transitions to state End. 1240 o Rollback: The 'Offerer' public key is mistrusted, and the FSM 1241 transitions to state Sole. 1243 A.1.1.7. HandshakingPhase2Offerer 1245 This state can only be entered by the 'Offerer' device from a 1246 HandshakingOfferer state. 1248 In this state the FSM waits for the user's response on the 'Offerer' 1249 device. The user is still prompted to compare Trustwords and choose 1250 from the following options: 1252 o Accept: The 'Requester' public key used in the Handshake is 1253 trusted, a CommitAcceptOfferer message is issued to the 1254 'Requester', and the FSM transitions to state FormingGroupOfferer. 1256 o Reject: A CommitReject message is issued to the 'Requester' 1257 device, pEp KeySync is disabled, and the FSM transitions to state 1258 End. 1260 o Cancel: A Rollback message is issued to the 'Requester' device, 1261 and the FSM transitions to state Sole. 1263 A.1.1.8. FormingGroupOfferer 1265 This state can only be entered by the 'Offerer' device from 1266 HandshakingPhase1Offerer or HandshakingPhase2Offerer state. 1268 On initialization, the FSM prepares the Own Keys on the 'Offerer' 1269 device for synchronization and makes a backup of these Own Keys. 1270 Then it waits for the OwnKeysRequester message from the 'Requester', 1271 which contains the Own Keys and the information about all Own 1272 Identities of the 'Requester'. 1274 When this message is received, the 'Offerer' FSM performs a 1275 sameNegotiation conditional check on the current negotiation session 1276 to verify that the current session has not been disrupted or 1277 compromised. 1278 If this conditional returns 'true', the FSM saves the 'Requester' 1279 keys combined with the 'Offerer' keys in a shared GroupKeys array 1280 (saveGroupKeys) and the 'Requester' device keys are marked as default 1281 for those respective identities (receivedKeysAreDefaultKeys). Then, 1282 the FSM prepares the Own Keys on the 'Offerer' device for 1283 synchronization. Because the Keys are already set to those of the 1284 'Requester' device, it is taking its former Own Keys and Own 1285 Identities from the backup (cf. above). The Offerer sends the 1286 OwnKeysOfferer message (with Key material of its Own Keys and Own 1287 Identities) to the 'Requester', a UI event (showGroupCreated) 1288 indicates that the Device Group process is complete, and the FSM 1289 transitions to state Grouped. 1291 Note: In case the 'Requester' device has transitioned to Sole state 1292 due to a Cancel, this OwnKeysOfferer message will not processed by 1293 the 'Requester' device. 1295 In case a (delayed) Cancel arrives (which normally cannot happen), a 1296 Rollback message is issued to the 'Requester' device, and the FSM 1297 transitions to state Sole. 1299 In case a (delayed) Rollback message is received (which normally 1300 cannot happen), the FSM transitions to state Sole. 1302 A.1.1.9. FormingGroupRequester 1304 This state can only be entered by the 'Requester' device from a 1305 HandshakingPhase1Requester state. 1307 In this state the FSM awaits and processes the message OwnKeysOfferer 1308 from an 'Offerer' device in state HandshakingPhase1Offerer or 1309 HandshakingPhase2Offerer. 1311 When this message is received, the 'Requester' FSM performs a 1312 sameNegotiation conditional check on the current negotiation session 1313 to verify that the current session has not been disrupted or 1314 compromised. 1315 If this conditional returns 'true', the FSM saves the 'Offerer' keys 1316 in a shared GroupKeys array (saveGroupKeys), and prepares the 1317 device's Own Keys for synchronization. The 'Requester' device keys 1318 are marked as default for those respective identities 1319 (ownKeysAreDefaultKeys). A UI event (showGroupCreated) indicates 1320 that the Device Group process is complete, and the FSM transitions to 1321 state Grouped. 1323 In case a (delayed) Cancel arrives (which normally cannot happen), a 1324 Rollback message is issued to the 'Offerer' device, and the FSM 1325 transitions to state Sole. 1327 Note: In case the 'Offerer' device has already transitioned to 1328 Grouped state, this Rollback message will not be processed by the 1329 'Offerer' device. 1331 In case a (delayed) Rollback message is received (which normally 1332 cannot happen), the FSM transitions to state Sole. 1334 A.1.1.10. Grouped 1336 This is the default state for any Grouped Device. 1338 On initialization, this state generates a new Challenge TID and shows 1339 the device as being in the Grouped state. A UI event 1340 (showBeingInGroup) indicates that the Device is part of a Device 1341 Group. 1343 In this state the FSM also listens for Beacons from other devices 1344 that are not yet part of the Device Group. 1346 Upon receipt of a Beacon message from Sole Device, the device sends a 1347 NegotiationRequestGrouped message and waits for the Sole Device to 1348 respond with a NegotiationOpen message. 1350 On receipt of the NegotiationOpen message from the Sole Device, the 1351 FSM of the Grouped Device stores the negotiation information and 1352 transitions to state HandshakingGrouped. 1354 In this state, other events may also be processed, but these events 1355 do not result in a transition to another state. 1357 A.1.1.11. HandshakingToJoin 1359 This state can only be entered by a device in the Sole state that is 1360 attempting to join an existing Device Group. 1362 On initialization, this state drives user interface options, 1363 including the Trustwords dialog for joining a Device Group. The user 1364 on the new device is prompted to compare Trustwords and choose from 1365 the following options: 1367 o Accept: The existing Device Group's public key used in the 1368 Handshake is trusted, and the FSM transitions to state 1369 HandshakingToJoinPhase1. 1371 o Reject: A CommitReject message is sent to the existing Device 1372 Group, pEp KeySync is disabled (on new device), and the FSM 1373 transitions to state End. 1375 o Cancel: A Rollback message is sent to the existing Device Group, 1376 and the FSM transitions to state Sole. 1378 If the user selects one of the above options on a device that is part 1379 of the existing Device Group, its FSM sends a response to the new 1380 device. When this response is received, the FSM of the new device 1381 performs a sameNegotiation conditional check on the current 1382 negotiation session to verify that the current session has not been 1383 disrupted or compromised. If this conditional returns 'true', the 1384 FSM proceeds as follows, depending on the message received: 1386 o CommitAcceptForGroup: The FSM of the new device transitions to 1387 state HandshakingToJoinPhase2. 1389 o CommitReject: pEp KeySync is disabled (on the new device), and the 1390 FSM transitions to state End. 1392 o Rollback: The FSM transitions to state Sole. 1394 A.1.1.12. HandshakingToJoinPhase1 1396 This state is entered by a new device only, i.e. a device that is not 1397 yet part of a Device Group. 1399 In this state the FSM awaits and processes the response from a device 1400 that is part of the existing Device Group. When this response is 1401 received, the FSM of the new device performs a sameNegotiation 1402 conditional check on the current negotiation session to verify that 1403 the current session has not been disrupted or compromised. If this 1404 conditional returns 'true', the FSM proceeds as follows, depending on 1405 the message received: 1407 o CommitAcceptForGroup: A CommitAccept message is sent to the 1408 existing Device Group, and the The FSM transitions to state 1409 JoiningGroup. 1411 o CommitReject: The existing Device Group's public key is 1412 mistrusted, pEp KeySync is disabled (on the new device), and the 1413 FSM transitions to state End. 1415 o Rollback: The existing Device Group's public key is mistrusted, 1416 and the FSM transitions to state Sole. 1418 A.1.1.13. HandshakingToJoinPhase2 1420 This state is entered by a new device only, i.e. a device that is not 1421 yet part of a Device Group. 1423 In this state the FSM waits for the user's response on the new 1424 device. The user is still prompted to compare Trustwords and choose 1425 from the following options: 1427 o Accept: The existing Device Groups's public key used in the 1428 Handshake is trusted, a CommitAccept message is issued to the 1429 'Requester', and the FSM transitions to state JoiningGroup. 1431 o Reject: A CommitReject message is issued to the exiting Device 1432 Group, pEp KeySync is disabled (on the new device), and the FSM 1433 transitions to state End. 1435 o Cancel: A Rollback message is issued to the existing Device Group, 1436 and the FSM transitions to state Sole. 1438 A.1.1.14. JoiningGroup 1440 This state is entered by a new device only, i.e. a device that is not 1441 yet part of a Device Group. 1443 On initialization, the FSM prepares the Own Keys on the new device 1444 for synchronization and makes a backup of these Own Keys. Then it 1445 waits for the OwnKeysForNewMember message from the exiting Device 1446 Group, which contains the Own Keys and the information about all Own 1447 Identities of the existing Device Group. 1449 When this message is received, the FSM of the new device performs a 1450 sameNegotiationAndPartner conditional check on the current 1451 negotiation session to verify that both the current session and 1452 negotiation partner have not been disrupted or compromised. If this 1453 conditional returns 'true', the FSM saves the 'Requester' keys 1454 combined with the keys of the existing group in a shared GroupKeys 1455 array (saveGroupKeys) and the Device Group's keys are marked as 1456 default for those respective identities (receivedKeysAreDefaultKeys). 1457 Then, the FSM prepares the Own Keys on the new device for 1458 synchronization. Because the Keys are already set to the ones of the 1459 existing Device Group, it is taking its former Own Keys and Own 1460 Identities from the backup (cf. above). The new device sends the 1461 GroupKeysAndClose message (with Key material of its Own Keys and Own 1462 Identities) to the Device Group, a UI event (showDeviceAdded) 1463 indicates that the join Device Group process is complete, and the FSM 1464 transitions to state Grouped. 1466 A.1.1.15. HandshakingGrouped 1468 This state is entered by Grouped Devices only, i.e., devices that are 1469 part of a Device Group. 1471 On initialization, this state drives user interface options, 1472 including the Trustwords dialog. The user is prompted to compare 1473 Trustwords, and choose from the following options on any device 1474 belonging to the existing Device Group: 1476 o Accept: The new device's public key is trusted, and the FSM 1477 transitions to state HandshakingGroupedPhase1. 1479 o Reject: A CommitReject message is sent to the new device and the 1480 FSM transitions to state Grouped. 1482 o Cancel: A Rollback message is sent to the new device, and the FSM 1483 transitions to state Grouped. 1485 If the user selects the 'Cancel' or the 'Reject' options on the new 1486 device, the new device's FSM sends a response to the existing Device 1487 Group. When this response is received, the grouped devices FSM 1488 performs a sameNegotiation conditional check on the current 1489 negotiation session to verify that the current session has not been 1490 disrupted or compromised. If this conditional returns 'true', the 1491 FSM proceeds as follows, depending on the message received: 1493 o CommitReject: The FSM transitions to state Grouped. 1495 o Rollback: The FSM transitions to state Grouped. 1497 When a GroupTrustThisKey message is received from another device 1498 group member, the key received along with this message is trusted. 1499 If the sameNegotiation conditional check returns true, the FSM 1500 transitions to state Grouped. This latter causes any device in a 1501 Device Group, which is not actively taking part in the joining 1502 process, to abort the user prompt to Compare the Trustwords. 1504 Note: In this state, other events are processed, but these events do 1505 not result in a transition to another state and are not discussed 1506 here. 1508 A.1.1.16. HandshakingGroupedPhase1 1510 This state is entered by Grouped Devices only, i.e., devices that are 1511 already part of a Device Group. 1513 On initialization a message GroupTrustThisKey is sent to the other 1514 members of the Device Group and a message CommitAcceptForGroup is 1515 sent to the new device. 1517 In this state the FSM awaits and processes the response from an new 1518 device in state HandshakingToJoin or HandshakingToJoinPhase2. When 1519 this response is received, the grouped device's FSM performs a 1520 sameNegotiation conditional check on the current negotiation session 1521 to verify that the current session has not been disrupted or 1522 compromised. If this conditional returns 'true', the FSM proceeds as 1523 follows, depending on the message received: 1525 o CommitAccept: The FSM prepares the Own Keys on the grouped device 1526 for synchronization. The FSM then issues an 1527 SendGroupKeysForNewMember message to the new device, which 1528 contains these keys. Then a UI event (showDeviceAccepted) 1529 indicates that the new device has been successfully added to the 1530 Device Group, and the FSM transitions to state Grouped. [[ TODO: 1531 Check whether 'go Grouped' should be removed in this event handler 1532 ]] 1534 o CommitReject: The 'Offerer' public key is mistrusted and the FSM 1535 transitions to state Grouped. 1537 o Rollback: The 'Offerer' public key is mistrusted, and the FSM 1538 transitions to state Grouped. 1540 In case a GroupKeysAndClose message arrives from another group 1541 member, the FSM transitions to state Grouped. 1543 In this state also various other events are processed, which do not 1544 result in a transition to another state. 1546 A.1.1.17. GroupKeyResetElection 1548 This state is entered by Grouped Devices only, i.e., devices that are 1549 already part of a Device Group. 1551 It is used to reset keys that have become invalid. 1553 [[ TODO: More detailed description ]] 1555 A.1.2. Conditions 1557 All Conditions can either be true or false on success, or they fail 1558 and are bringing the State Machine into an error state, and the State 1559 Machine will be initialized. 1561 A.1.2.1. deviceGrouped 1563 The 'deviceGrouped' conditional evaluates true if a device is already 1564 in a Device Group. This is determined by checking if there are Group 1565 Keys already. This boolean value is available and eventually altered 1566 locally on every KeySync-enabled device. For example, in the 1567 reference implementation, this boolean value is stored in a local SQL 1568 database. 1570 The 'deviceGrouped' value is what the KeySync FSM uses upon 1571 initialization to determine whether a device should transition to 1572 state Sole or state Grouped. 1574 A.1.2.2. fromGroupMember 1576 The 'fromGroupMember' conditional evaluates true if the incoming Sync 1577 Message is coming from a Device Group member. 1579 A.1.2.3. keyElectionWon 1581 The 'keyElectionWon' conditional evaluates true if our Own Keys are 1582 going to be used as Group Keys. False if the Own Keys of the partner 1583 will be the Group Keys. Calculated by comparing if the FPR of the 1584 Sender Key of the partner is greater than our Default Key for the 1585 Account, which is being used as Active Transport. 1587 A.1.2.4. sameChallenge 1589 The 'sameChallenge' conditional evaluates true if the Challenge of 1590 the incoming Sync Message is identical to the Challenge of the 1591 Device, i.e., this is a Sync Message sent by the originating Device 1592 itself. 1594 A.1.2.5. sameNegotiation 1596 The 'sameNegotiation' conditional is dependent upon the 1597 'storeNegotiation' function, which stores the active negotiation 1598 session while the KeySync process is performed. This conditional 1599 evaluates true if the 'storeNegotiation' value of the incoming Sync 1600 Message is identical to that of the 'storeNegotiation' value that the 1601 Device is in. 1603 This serves as a session fidelity check. If this boolean evaluates 1604 'true', it confirms that the pEp KeySync session in progress is the 1605 same throughout. 1607 A.1.2.6. sameNegotiationAndPartner 1609 Similar to the 'sameNegotiation' conditional, the 1610 'sameNegotiationAndPartner' conditional is dependent upon the 1611 'storeNegotiation' function, which stores the active negotiation 1612 session while the KeySync process is performed. The 1613 'sameNegotiation' conditional evaluates true if both 1614 'storeNegotiation' value of the incoming Sync Message is identical to 1615 that of the 'storeNegotiation' value that the Device is in, AND the 1616 negotiation partner did not change. 1618 This conditional also serves as a session fidelity check. If this 1619 boolean evaluates 'true', it confirms that the pEp KeySync session in 1620 progress is the same throughout, and that the negotiation partner has 1621 not changed. 1623 A.1.2.7. sameResponse 1625 The 'sameResponse' conditional evaluates true if the Response of the 1626 incoming Sync Message is identical to the Response of the Device. In 1627 this case the Response is correctly echoed. 1629 A.1.2.8. weAreOfferer 1631 The 'weAreOfferer' conditional evaluates true if the Challenge of the 1632 incoming Sync Message is greater than the Challenge of the Device. 1633 Otherwise we're the Requester. 1635 A.1.3. Actions 1637 Actions are unconditionally executed. Any or all Actions may fail. 1638 In the event of failure, actions bring the State Machine into an 1639 error state, and the State Machine will be reinitialized. 1641 A.1.3.1. backupOwnKeys 1643 The 'backupOwnKeys' action is to make a backup of all Own Keys, and 1644 allows for restoration of the Own Keys. 1646 A.1.3.2. disable 1648 The 'disable' action does as it implies. This action shuts down the 1649 State Machine and disables KeySync functionality on the impacted 1650 device. It is most commonly called in 'Cancel' or 'Reject' 1651 scenarios. For example, if a user rejects a pEp Handshake on a 1652 device involved in a pEp Handshake, the 'disable' action is called. 1653 Invoking the 'disable' function results in the State Machine 1654 transitioning to state End, which automatically disables the KeySync 1655 feature. pEp KeySync can be manually re-enabled in the pEp settings 1656 on the disabled device. 1658 A.1.3.3. newChallengeAndNegotiationBase 1660 The 'newChallengeAndNegotiationBase' action is to randomly compute a 1661 new Challenge and a new Response (Negotiatial Base). 1663 The 'newChallengeAndNegotiationBase' action is invoked by a device 1664 during an Init event in either the Sole or Grouped state, and serves 1665 to clear and generate a new Challenge TID and negotiation state. 1667 A.1.3.4. openNegotiation 1669 The 'openNegotiation' action is to clear Key and Identity of the 1670 partner and to calculate the Negotiation ID from the Negotiation Base 1671 and the Challenge of the partner (by XOR). 1673 An 'openNegotiation' action is carried out either by a Sole Device in 1674 the 'Requester' role, or a Grouped device upon receipt of a Beacon 1675 message from another Sole Device. Most importantly, this action 1676 ensures that the own TID and the Challenge TID of the Sole Device get 1677 combined by the mathematical XOR function. In this way, a common TID 1678 exists which can be used by both devices a user wishes to pair. This 1679 TID is crucial in allowing the devices to recognize themselves in a 1680 particular pairing process, as multiple pairing process can occur 1681 simultaneously. 1683 A.1.3.5. ownKeysAreDefaultKeys 1685 The 'ownKeysAreDefaultKeys' action is to flag Default Keys of Own 1686 Identities as Group Keys. 1688 The ownKeysAreDefaultKeys action is invoked by the 'Requester' device 1689 during the final step of Device Group formation between two Sole 1690 devices, and ensures that the Own Keys for the identities on the 1691 'Requester' device are set as the default for those respective 1692 identities. 1694 A.1.3.6. prepareOwnKeys 1696 The 'prepareOwnKeys' action is to write a list of Own Identities into 1697 the I/O Buffer and load the list of Own Keys into the Device state. 1699 The prepareOwnKeys action is invoked during the latter phases of the 1700 KeySync protocol for both new and existing Device Group joining 1701 processes. This action indicates to a device that all key 1702 information that has been selected for synchronization should be 1703 prepared for sending to the other negotiation partner. 1705 A.1.3.7. prepareOwnKeysFromBackup 1707 The 'prepareOwnKeysFromBackup' action is to restore the formerly 1708 backed up Own Keys (cf. Appendix A.1.3.1) into the I/O Buffer. This 1709 action is similar to prepareOwnKeys (cf. Appendix A.1.3.6). 1711 A.1.3.8. receivedKeysAreDefaultKeys 1713 The 'receivedKeysAreDefaultKeys' action is to set the received Own 1714 Keys as Default Keys for the Own Identities. 1716 A.1.3.9. resetOwnGroupedKeys 1718 The 'resetOwnGroupedKeys' action is to carry out a KeyReset on Own 1719 Group Keys. 1721 A.1.3.10. resetOwnKeysUngrouped 1723 The 'resetOwnKeysUngrouped' action is to carry out a KeyReset on all 1724 Own Keys. 1726 A.1.3.11. saveGroupKeys 1728 The 'saveGroupKeys' action is to load Own Identities from the I/O 1729 Buffer and store them as Own Identities. 1731 The 'saveGroupKeys' action directs the addition of any keys received 1732 during a KeySync process to a GroupKeys array, along with any 1733 existing Own or Grouped Device Keys. 1735 A.1.3.12. showBeingInGroup 1737 The 'showBeingInGroup' action is to signal to the application that 1738 the device is member of a Device Group. 1740 The showBeingInGroup action in state Grouped drives a UI event that 1741 can be used to notify a pEp user that their device belongs to a 1742 Device Group 1744 A.1.3.13. showBeingSole 1746 The 'showBeingSole' action is to signal to the application that the 1747 device is not member of a Device Group. 1749 The 'showBeingSole' action in state Sole drives a UI event that can 1750 be used to notify a pEp user that their device is Sole (ungrouped). 1752 A.1.3.14. showDeviceAccepted 1754 The 'showDeviceAccepted' action is to signal to the application that 1755 the device has been accepted as member of the Device Group. 1757 The 'showDeviceAccepted' action drives a UI event that is used to 1758 notify a pEp user that a Sole Device was accepted as member of an 1759 existing Device Group. 1761 A.1.3.15. showDeviceAdded 1763 The 'showDeviceAdded' action is to signal to the application that the 1764 device has been added as member of the Device Group. 1766 The 'showDeviceAdded' action drives a UI event that is used to notify 1767 a pEp user that a Sole Device was added to an already existing Device 1768 Group. 1770 A.1.3.16. showGroupCreated 1772 The 'showGroupCreated' action is to signal to the application that 1773 the Device Group has been created. 1775 In either role that a Sole Device can assume ('Requester' or 1776 'Offerer'), the action 'showGroupCreated' drives a UI event which 1777 notifies a user that a new Device Group was formed from two Sole 1778 Devices. 1780 A.1.3.17. showGroupedHandshake 1782 The 'showGroupedHandshake' action is to signal to the application of 1783 a Grouped Device that a new device is about to join that Device 1784 Group. 1786 The 'showGroupedHandshake' action drives a UI event on a Grouped 1787 device, which a pEp implementer should use to display a pEp Handshake 1788 dialog. This dialog should indicate that there is a new Sole Device 1789 that is requesting to join the Device Group that this Grouped device 1790 belongs to. 1792 A.1.3.18. showJoinGroupHandshake 1794 The 'showJoinGroupHandshake' action is to signal to the application 1795 of a Ungrouped Device that it is about to join an existing Device 1796 Group. 1798 The 'showJoinGroupHandshake' action drives a UI event on a Sole 1799 Device attempting to join an existing Device Group, and should be 1800 used by pEp implementers to show a Handshake dialog on the Sole 1801 Device. 1803 A.1.3.19. showSoleHandshake 1805 The 'showSoleHandshake' action is to signal to the application of a 1806 Ungrouped Device that it is about to from a new Device Group. 1808 For cases where two Sole Devices are attempting to form a new Device 1809 Group, the showSoleHandshake action drives a UI event, which a pEp 1810 implementer should use to display a pEp Handshake dialog to each of 1811 the devices in negotiation. 1813 A.1.3.20. storeNegotiation 1815 The 'storeNegotiation' action is to store the Negotiation for the 1816 device in the I/O Buffer The Sender FPR and partner's Identity are 1817 both stored for later comparison. 1819 The storeNegotiation action saves the received non-own negotiation 1820 information, which is used e.g. by the sameNegotiation conditional to 1821 perform a session fidelity check (cf. Appendix A.1.2.5). 1823 A.1.3.21. storeThisKey 1825 The 'storeThisKey' action is to load the Sender Key of the partner 1826 from the I/O Buffer and store it for later use. 1828 A.1.3.22. tellWeAreGrouped 1830 The 'tellWeAreGrouped' action is to set the is_grouped Field in the 1831 I/O Buffer to true. 1833 The tellWeAreGrouped action is used by devices already in the Grouped 1834 state. It is sent in a Beacon and indicates to Sole Devices that 1835 they are entering a negotiation with a Grouped device. For the Sole 1836 Device, receiving this action determines which state the FSM will 1837 transition to next. 1839 A.1.3.23. tellWeAreNotGrouped 1841 The 'tellWeAreNotGrouped' action is to set the is_grouped Field in 1842 the I/O Buffer to false. 1844 The 'tellWeAreNotGrouped' action is used by Sole Devices which are 1845 assigned the role of 'Requester' upon Challenge TID comparison, and 1846 is sent along with a NegotiationRequest event to indicate to the 1847 'Offerer' device that they are entering into a negotiation request 1848 with a Sole Device. 1850 A.1.3.24. trustThisKey 1852 The 'trustThisKey' action is to trust the formerly stored Key of the 1853 partner and load this Key into the I/O Buffer. 1855 The trustThisKey action is executed in all states when a user chooses 1856 'Accept' on the Handshake dialog. Trust for the public key from the 1857 negotiation partner is granted so the rest of the KeySync process can 1858 be conducted securely. The trust also extends to the private key 1859 portion of the key pair at later stage in the KeySync process, so 1860 long as the user continues to choose 'Accept' on both devices. If 1861 the process is canceled or rejected at any point after the public key 1862 trust has been granted, that trust will be removed (cf. 1863 Appendix A.1.3.25). 1865 A.1.3.25. untrustThisKey 1867 The 'untrustThisKey' action is to revoke trust from the formerly 1868 stored Key of the partner and clear the Key in the I/O Buffer. 1870 If the 'Cancel' or 'Reject' options are chosen at any point during 1871 the KeySync process after a negotiation partner's public key has been 1872 trusted, trust on that public key is removed (cf. 1873 Appendix A.1.3.24). The untrustThisKey action ensures that the 1874 negotiation partner's public key can never be attached to messages 1875 sent to outside peers from the recipient device. 1877 A.1.3.26. useOwnChallenge 1879 The 'useOwnChallenge' action is to copy the Challenge of the Device 1880 into the I/O Buffer. 1882 Once a Beacon is received by a device in either the Sole or Grouped 1883 state, the useOwnChallenge action attaches the device's generated 1884 Challenge TID to an outgoing Beacon or NegotiationRequest event for 1885 comparison and session verification purposes. 1887 A.1.3.27. useOwnResponse 1889 The 'useOwnResponse' action is to copy the Response of the Device 1890 into the I/O Buffer. 1892 A.1.3.28. useThisKey 1894 The 'useThisKey' action is to copy the stored Sender Key of the 1895 partner into the I/O Buffer. 1897 A.1.4. Transitions 1899 Transitions are changes between states within the FSM, and are 1900 indicated by the 'go' command throughout the code. Please see the 1901 desired State (Appendix A.1.1 and Appendix B.1) for additional 1902 information on why and when these changes are triggered. 1904 A.1.5. Events 1906 While in a State, Events receive incoming messages and prompt the 1907 execution of any event handlers (conditions, actions, messages, or 1908 transitions) contained within. Please refer to the desired State 1909 (Appendix B.1) for additional information on specific event handlers. 1911 A.1.5.1. Init Event 1913 When the FSM transitions to a new state for the first time, the Init 1914 event (if present) is called. Init events typically drive UI actions 1915 and event handlers associated with core functionality of the 1916 protocol. 1918 Example of an Init Event Handler: 1920 on Init { 1921 if deviceGrouped { 1922 send SynchronizeGroupKeys; 1923 go Grouped; 1924 } 1925 go Sole; 1926 } 1928 A.1.5.2. Message Event 1930 If a Sync Message (cf. Appendix A.1.6) arrives through the network 1931 then the Event with the name of the Message occurs. 1933 Example of an Message Event Handler: 1935 In this example an Event Handler is defined, which is executed when a 1936 Beacon Message arrives: 1938 on Beacon { 1939 do openNegotiation; 1940 do tellWeAreGrouped; 1941 do useOwnResponse; 1942 send NegotiationRequestGrouped; 1943 do useOwnChallenge; 1944 } 1946 A.1.5.3. Signaled Events 1948 Events, which don't share their name with a Message, are signaled 1949 from engine code. 1951 Example of an Signaled Event Handler: 1953 The KeyGen Event has no corresponding Message. Therefore, it does 1954 not occur when a Sync Message arrives, but rather when it is signaled 1955 from code: 1957 on KeyGen { 1958 do prepareOwnKeys; 1959 send GroupKeysUpdate; 1960 } 1962 A.1.5.4. External Events 1964 If Events are part of an API then their IDs must be well defined. 1965 Therefore, it is possible to define such IDs in the State Machine. 1966 External Event may be used to signal a User Interaction to the FSM. 1968 Example: 1970 on Accept { 1971 do trustThisKey; 1972 send CommitAcceptRequester; 1973 go HandshakingPhase1Requester; 1974 } 1976 A.1.6. Messages 1978 KeySync is a Network Protocol, which is implemented using Sync 1979 Messages. The Sync Messages for KeySync are defined at the end of 1980 the Finite State Machine code in Appendix B.1. 1982 The wire format of Sync Messages is defined in ASN.1 (cf. 1983 Appendix B.2), using PER. 1985 Sync Messages are transported as Attachments to pEp Messages. Hence 1986 they're carried by the same Transports, which transmit pEp Messages. 1987 Some Sync Messages must be sent in copy on all Transports. Others 1988 are transported on the Active Transport only. The Active Transport 1989 is the transport on which the last Sync Message was received. 1991 A.1.6.1. Message Types 1993 Each Sync Message has a name and an ID. There is different types of 1994 Messages: 1996 o type=broadcast: Messages, which are meant to be copied on all 1997 Transports 1999 o type=anycast: Messages, which are meant to be sent on the Active 2000 Transport only 2002 A.1.6.2. Security Context 2004 Each Sync Message has a Security Context. The available Security 2005 Contexts are: 2007 o security=unencrypted: send and receive as unencrypted but signed 2008 Sync Message 2010 o security=untrusted: only accept when encrypted and signed 2012 o security=trusted (default): only accept when coming over a Trusted 2013 Channel and when originating from the Device Group 2015 o security=attach_own_keys_for_new_member: like security=trusted but 2016 attach all Own Keys for a new Member of the Device Group 2018 o security=attach_own_keys_for_group: like security=trusted but 2019 attach all Own Keys for other Device Group Members. 2021 A.1.6.3. Rate Limit 2023 A Sync Message can have a Rate Limit ratelimit=. That means 2024 it is only possible to send out one message each seconds. 2025 A Rate Limit of 0 means no Rate Limit checking. 2027 Example: 2029 message Beacon 2, type=broadcast, ratelimit=10, security=unencrypted { 2030 field TID challenge; 2031 auto Version version; 2032 } 2034 A.1.6.4. Fields 2036 A Sync Message can have Fields. There is two types of fields: 2037 automatically calculated fields, defined with the auto keyword, and 2038 fields, which are copied in and out from the I/O Buffer, marked with 2039 the fields keyword. 2041 The wire format of the fields is depending on their type. 2043 The types are defined in Appendix B.2. Additionally, the two basic 2044 types bool (ASN.1: BOOLEAN) and int (ASN.1: INTEGER) are supported. 2046 Example for an auto field: 2048 auto Version version; 2050 This field will be filled with the pEp Sync Protocol version. The 2051 Version type is the only automatically calculated type yet. 2053 Example for a field coming from I/O Buffer 2055 field TID challenge; 2057 A.1.6.5. I/O Buffer 2059 There is an I/O Buffer for all Fields which occur in Messages. All 2060 Messages share this I/O Buffer. Fields with the same name share one 2061 space in the I/O Buffer. Hence, the I/O Buffer is built as superset 2062 of all Fields' buffers. 2064 A.1.6.6. Sending 2066 Sending is performed as follows: 2068 1. Calculating all auto Fields and copying the result into the I/O 2069 Buffer 2071 2. Loading all Fields of the Message from I/O Buffer 2073 3. Creating a Sync Message 2074 4. Creating a transporting pEp Message by attaching the Sync Message 2075 using Base Protocol 2077 5. Calling messageToSend() with this pEp Message 2079 Example 2081 send SynchronizeGroupKeys; 2083 A.1.6.7. Receiving 2085 When a Message is being received the field values are being copied 2086 into the I/O Buffer and the corresponding Event is being signaled. 2088 A.1.6.8. Messages used in KeySync 2090 For more information on the messages used in the KeySync Protocol, 2091 see (end of) Appendix B.1. 2093 Appendix B. Code excerpts 2095 B.1. Finite-State Machine 2097 Below is the full code for the pEp KeySync FSM, including messages 2098 and external events. 2100 // This file is under BSD License 2.0 2102 // Sync protocol for pEp 2103 // Copyright (c) 2016-2020, pEp foundation 2105 // Written by Volker Birk 2107 include ./fsm.yml2 2109 protocol Sync 1 { 2110 // all messages have a timestamp, time out and are removed after 2111 // timeout 2113 fsm KeySync 1, threshold=300 { 2114 version 1, 2; 2116 state InitState { 2117 on Init { 2118 if deviceGrouped { 2119 send SynchronizeGroupKeys; 2120 go Grouped; 2122 } 2123 go Sole; 2124 } 2125 } 2127 state Sole timeout=off { 2128 on Init { 2129 do newChallengeAndNegotiationBase; 2130 send Beacon; 2131 do showBeingSole; 2132 } 2134 on KeyGen { 2135 send Beacon; 2136 } 2138 on CannotDecrypt { 2139 send Beacon; 2140 } 2142 on Beacon { 2143 if sameChallenge { 2144 } 2145 else { 2146 if weAreOfferer { 2147 do useOwnChallenge; 2148 send Beacon; 2149 } 2150 else /* we are requester */ { 2151 do openNegotiation; 2152 do tellWeAreNotGrouped; 2153 // requester is sending NegotiationRequest 2154 do useOwnResponse; 2155 send NegotiationRequest; 2156 do useOwnChallenge; 2157 } 2158 } 2159 } 2161 // we get this from another sole device 2162 on NegotiationRequest { 2163 if sameChallenge { // challenge accepted 2164 do storeNegotiation; 2165 // offerer is accepting by confirming 2166 // NegotiationOpen 2167 // repeating response is implicit 2168 send NegotiationOpen; 2169 go HandshakingOfferer; 2171 } 2172 } 2174 // we get this from an existing device group 2175 on NegotiationRequestGrouped { 2176 if sameChallenge { // challenge accepted 2177 do storeNegotiation; 2178 // offerer is accepting by confirming 2179 // NegotiationOpen 2180 // repeating response is implicit 2181 send NegotiationOpen; 2182 go HandshakingToJoin; 2183 } 2184 } 2186 on NegotiationOpen { 2187 if sameResponse { 2188 do storeNegotiation; 2189 go HandshakingRequester; 2190 } 2191 } 2192 } 2194 // handshaking without existing Device group 2195 state HandshakingOfferer timeout=600 { 2196 on Init 2197 do showSoleHandshake; 2199 // Cancel is Rollback 2200 on Cancel { 2201 send Rollback; 2202 go Sole; 2203 } 2205 on Rollback { 2206 if sameNegotiation 2207 go Sole; 2208 } 2210 // Reject is CommitReject 2211 on Reject { 2212 send CommitReject; 2213 do disable; 2214 go End; 2215 } 2217 on CommitReject { 2218 if sameNegotiation { 2219 do disable; 2220 go End; 2221 } 2222 } 2224 // Accept means init Phase1Commit 2225 on Accept { 2226 do trustThisKey; 2227 go HandshakingPhase1Offerer; 2228 } 2230 // got a CommitAccept from requester 2231 on CommitAcceptRequester { 2232 if sameNegotiation 2233 go HandshakingPhase2Offerer; 2234 } 2235 } 2237 // handshaking without existing Device group 2238 state HandshakingRequester timeout=600 { 2239 on Init 2240 do showSoleHandshake; 2242 // Cancel is Rollback 2243 on Cancel { 2244 send Rollback; 2245 go Sole; 2246 } 2248 on Rollback { 2249 if sameNegotiation 2250 go Sole; 2251 } 2253 // Reject is CommitReject 2254 on Reject { 2255 send CommitReject; 2256 do disable; 2257 go End; 2258 } 2260 on CommitReject { 2261 if sameNegotiation { 2262 do disable; 2263 go End; 2264 } 2265 } 2266 // Accept means init Phase1Commit 2267 on Accept { 2268 do trustThisKey; 2269 send CommitAcceptRequester; 2270 go HandshakingPhase1Requester; 2271 } 2272 } 2274 state HandshakingPhase1Offerer { 2275 on Rollback { 2276 if sameNegotiation { 2277 do untrustThisKey; 2278 go Sole; 2279 } 2280 } 2282 on CommitReject { 2283 if sameNegotiation { 2284 do untrustThisKey; 2285 do disable; 2286 go End; 2287 } 2288 } 2290 on CommitAcceptRequester { 2291 if sameNegotiation { 2292 send CommitAcceptOfferer; 2293 go FormingGroupOfferer; 2294 } 2295 } 2296 } 2298 state HandshakingPhase1Requester { 2299 on Rollback { 2300 if sameNegotiation { 2301 do untrustThisKey; 2302 go Sole; 2303 } 2304 } 2306 on CommitReject { 2307 if sameNegotiation { 2308 do untrustThisKey; 2309 do disable; 2310 go End; 2311 } 2312 } 2313 on CommitAcceptOfferer { 2314 if sameNegotiation { 2315 do prepareOwnKeys; 2316 send OwnKeysRequester; 2317 go FormingGroupRequester; 2318 } 2319 } 2320 } 2322 state HandshakingPhase2Offerer { 2323 on Cancel { 2324 send Rollback; 2325 go Sole; 2326 } 2328 on Reject { 2329 send CommitReject; 2330 do disable; 2331 go End; 2332 } 2334 on Accept { 2335 do trustThisKey; 2336 send CommitAcceptOfferer; 2337 go FormingGroupOfferer; 2338 } 2339 } 2341 state FormingGroupOfferer { 2342 on Init { 2343 // we need to keep in memory which keys we have before 2344 // forming a new group 2345 do prepareOwnKeys; 2346 do backupOwnKeys; 2347 } 2349 on Cancel { 2350 send Rollback; 2351 go Sole; 2352 } 2354 on Rollback 2355 go Sole; 2357 on OwnKeysRequester { 2358 if sameNegotiationAndPartner { 2359 do saveGroupKeys; 2360 do receivedKeysAreDefaultKeys; 2361 // send the keys we had before forming a new group 2362 do prepareOwnKeysFromBackup; 2363 send OwnKeysOfferer; 2364 do showGroupCreated; 2365 go Grouped; 2366 } 2367 } 2368 } 2370 state FormingGroupRequester { 2371 on Cancel { 2372 send Rollback; 2373 go Sole; 2374 } 2376 on Rollback 2377 go Sole; 2379 on OwnKeysOfferer { 2380 if sameNegotiation { 2381 do saveGroupKeys; 2382 do prepareOwnKeys; 2383 do ownKeysAreDefaultKeys; 2384 do showGroupCreated; 2385 go Grouped; 2386 } 2387 } 2388 } 2390 state Grouped timeout=off { 2391 on Init { 2392 do newChallengeAndNegotiationBase; 2393 do showBeingInGroup; 2394 } 2396 on CannotDecrypt { 2397 send SynchronizeGroupKeys; 2398 } 2400 on SynchronizeGroupKeys { 2401 do prepareOwnKeys; 2402 send GroupKeysUpdate; 2403 } 2405 on GroupKeysUpdate { 2406 if fromGroupMember // double check 2407 do saveGroupKeys; 2408 } 2409 on KeyGen { 2410 do prepareOwnKeys; 2411 send GroupKeysUpdate; 2412 } 2414 on Beacon { 2415 do openNegotiation; 2416 do tellWeAreGrouped; 2417 do useOwnResponse; 2418 send NegotiationRequestGrouped; 2419 do useOwnChallenge; 2420 } 2422 on NegotiationOpen { 2423 if sameResponse { 2424 do storeNegotiation; 2425 do useThisKey; 2426 send GroupHandshake; 2427 go HandshakingGrouped; 2428 } 2429 } 2431 on GroupHandshake { 2432 do storeNegotiation; 2433 do storeThisKey; 2434 go HandshakingGrouped; 2435 } 2437 on GroupTrustThisKey { 2438 if fromGroupMember // double check 2439 do trustThisKey; 2440 } 2442 on LeaveDeviceGroup { 2443 send InitUnledGroupKeyReset; 2444 do disable; 2445 do resetOwnKeysUngrouped; 2446 } 2448 on InitUnledGroupKeyReset { 2449 do useOwnResponse; 2450 send ElectGroupKeyResetLeader; 2451 go GroupKeyResetElection; 2452 } 2453 } 2455 state GroupKeyResetElection { 2456 on ElectGroupKeyResetLeader { 2457 if sameResponse { 2458 // the first one is from us, we're leading this 2459 do resetOwnGroupedKeys; 2460 go Grouped; 2461 } 2462 else { 2463 // the first one is not from us 2464 go Grouped; 2465 } 2466 } 2467 } 2469 // sole device handshaking with group 2470 state HandshakingToJoin { 2471 on Init 2472 do showJoinGroupHandshake; 2474 // Cancel is Rollback 2475 on Cancel { 2476 send Rollback; 2477 go Sole; 2478 } 2480 on Rollback { 2481 if sameNegotiation 2482 go Sole; 2483 } 2485 // Reject is CommitReject 2486 on Reject { 2487 send CommitReject; 2488 do disable; 2489 go End; 2490 } 2492 on CommitAcceptForGroup { 2493 if sameNegotiation 2494 go HandshakingToJoinPhase2; 2495 } 2497 on CommitReject { 2498 if sameNegotiation { 2499 do disable; 2500 go End; 2501 } 2502 } 2504 // Accept is Phase1Commit 2505 on Accept { 2506 do trustThisKey; 2507 go HandshakingToJoinPhase1; 2508 } 2509 } 2511 state HandshakingToJoinPhase1 { 2512 on Rollback { 2513 if sameNegotiation { 2514 do untrustThisKey; 2515 go Sole; 2516 } 2517 } 2519 on CommitReject { 2520 if sameNegotiation { 2521 do untrustThisKey; 2522 do disable; 2523 go End; 2524 } 2525 } 2527 on CommitAcceptForGroup { 2528 if sameNegotiation { 2529 send CommitAccept; 2530 go JoiningGroup; 2531 } 2532 } 2533 } 2535 state HandshakingToJoinPhase2 { 2536 on Cancel { 2537 send Rollback; 2538 go Sole; 2539 } 2541 on Reject { 2542 send CommitReject; 2543 do disable; 2544 go End; 2545 } 2547 on Accept { 2548 do trustThisKey; 2549 send CommitAccept; 2550 go JoiningGroup; 2551 } 2552 } 2553 state JoiningGroup { 2554 on Init { 2555 // we need to keep in memory which keys we have before 2556 // joining 2557 do prepareOwnKeys; 2558 do backupOwnKeys; 2559 } 2560 on GroupKeysForNewMember { 2561 if sameNegotiationAndPartner { 2562 do saveGroupKeys; 2563 do receivedKeysAreDefaultKeys; 2564 // send the keys we had before joining 2565 do prepareOwnKeysFromBackup; 2566 send GroupKeysAndClose; 2567 do showDeviceAdded; 2568 go Grouped; 2569 } 2570 } 2571 } 2573 state HandshakingGrouped { 2574 on Init 2575 do showGroupedHandshake; 2577 // Cancel is Rollback 2578 on Cancel { 2579 send Rollback; 2580 go Grouped; 2581 } 2583 on Rollback { 2584 if sameNegotiation 2585 go Grouped; 2586 } 2588 // Reject is CommitReject 2589 on Reject { 2590 send CommitReject; 2591 go Grouped; 2592 } 2594 on CommitReject { 2595 if sameNegotiation 2596 go Grouped; 2597 } 2599 // Accept is Phase1Commit 2600 on Accept { 2601 do trustThisKey; 2602 go HandshakingGroupedPhase1; 2603 } 2605 on GroupTrustThisKey { 2606 if fromGroupMember { // double check 2607 do trustThisKey; 2608 if sameNegotiation 2609 go Grouped; 2610 } 2611 } 2613 on GroupKeysUpdate { 2614 if fromGroupMember // double check 2615 do saveGroupKeys; 2616 } 2617 } 2619 state HandshakingGroupedPhase1 { 2620 on Init { 2621 send GroupTrustThisKey; 2622 send CommitAcceptForGroup; 2623 } 2625 on Rollback { 2626 if sameNegotiation { 2627 do untrustThisKey; 2628 go Grouped; 2629 } 2630 } 2632 on CommitReject { 2633 if sameNegotiation { 2634 do untrustThisKey; 2635 go Grouped; 2636 } 2637 } 2639 on CommitAccept { 2640 if sameNegotiation { 2641 do prepareOwnKeys; 2642 send GroupKeysForNewMember; 2643 do showDeviceAccepted; 2644 go Grouped; 2645 } 2646 } 2648 on GroupTrustThisKey { 2649 if fromGroupMember // double check 2650 do trustThisKey; 2651 } 2653 on GroupKeysUpdate { 2654 if fromGroupMember // double check 2655 do saveGroupKeys; 2656 } 2658 on GroupKeysAndClose { 2659 if fromGroupMember { // double check 2660 // do not save GroupKeys as default keys; 2661 // key data is already imported 2662 go Grouped; 2663 } 2664 } 2665 } 2667 external Accept 129; 2668 external Reject 130; 2669 external Cancel 131; 2671 // beacons are always broadcasted 2673 message Beacon 2, type=broadcast, ratelimit=10, 2674 security=unencrypted { 2675 field TID challenge; 2676 auto Version version; 2677 } 2679 message NegotiationRequest 3, security=untrusted { 2680 field TID challenge; 2681 field TID response; 2682 auto Version version; 2683 field TID negotiation; 2684 field bool is_group; 2685 } 2687 message NegotiationOpen 4, security=untrusted { 2688 field TID response; 2689 auto Version version; 2690 field TID negotiation; 2691 } 2693 message Rollback 5, security=untrusted { 2694 field TID negotiation; 2695 } 2696 message CommitReject 6, security=untrusted { 2697 field TID negotiation; 2698 } 2700 message CommitAcceptOfferer 7, security=untrusted { 2701 field TID negotiation; 2702 } 2704 message CommitAcceptRequester 8, security=untrusted { 2705 field TID negotiation; 2706 } 2708 message CommitAccept 9, security=untrusted { 2709 field TID negotiation; 2710 } 2712 message CommitAcceptForGroup 10, security=untrusted { 2713 field TID negotiation; 2714 } 2716 // default: security=trusted 2717 // messages are only accepted when coming from the device group 2718 message GroupTrustThisKey 11 { 2719 field Hash key; 2720 field TID negotiation; 2721 } 2723 // trust in future 2724 message GroupKeysForNewMember 12, 2725 security=attach_own_keys_for_new_member { 2726 field IdentityList ownIdentities; 2727 } 2729 message GroupKeysAndClose 13, 2730 security=attach_own_keys_for_group { 2731 field IdentityList ownIdentities; 2732 } 2734 message OwnKeysOfferer 14, security=attach_own_keys_for_group { 2735 field IdentityList ownIdentities; 2736 } 2738 message OwnKeysRequester 15, 2739 security=attach_own_keys_for_new_member { 2740 field IdentityList ownIdentities; 2741 } 2743 // grouped handshake 2744 message NegotiationRequestGrouped 16, security=untrusted { 2745 field TID challenge; 2746 field TID response; 2747 auto Version version; 2748 field TID negotiation; 2749 field bool is_group; 2750 } 2752 message GroupHandshake 17 { 2753 field TID negotiation; 2754 field Hash key; 2755 } 2757 // update group 2758 message GroupKeysUpdate 18, security=attach_own_keys_for_group { 2759 field IdentityList ownIdentities; 2760 } 2762 // initiate unled group key reset 2763 message InitUnledGroupKeyReset 19 { 2764 } 2766 message ElectGroupKeyResetLeader 20 { 2767 field TID response; 2768 } 2770 message SynchronizeGroupKeys 21, ratelimit=60 { 2771 } 2772 } 2773 } 2775 B.2. ASN.1 Type Definitions 2777 Below you can find the ASN.1 Type definitions for the messages used 2778 in pEp KeySync FSM. 2780 -- This file is under BSD License 2.0 2782 -- Sync protocol for pEp 2783 -- Copyright (c) 2016, 2017 pEp foundation 2785 -- Written by Volker Birk 2787 pEp 2788 { iso(1) org(3) dod(6) internet(1) private(4) enterprise(1) 2789 pEp(47878) basic(0) } 2791 DEFINITIONS AUTOMATIC TAGS EXTENSIBILITY IMPLIED ::= 2793 BEGIN 2795 EXPORTS Identity, IdentityList, TID, Hash, Version; 2797 ISO639-1 ::= PrintableString(FROM ("a".."z")) (SIZE(2)) 2798 Hex ::= PrintableString(FROM ("A".."F") | FROM ("0".."9")) 2799 Hash ::= Hex(SIZE(16..128)) -- 32bit Key ID to SHA512 in hex 2800 PString ::= UTF8String (SIZE(1..1024)) 2801 TID ::= OCTET STRING (SIZE(16)) -- UUID version 4 variant 1 2803 Identity ::= SEQUENCE { 2804 address PString, 2805 fpr Hash, 2806 user-id PString, 2807 username PString, 2808 comm-type INTEGER (0..255), 2809 lang ISO639-1 2810 } 2812 IdentityList ::= SEQUENCE OF Identity 2814 Version ::= SEQUENCE { 2815 major INTEGER (0..255) DEFAULT 1, 2816 minor INTEGER (0..255) DEFAULT 2 2817 } 2819 END 2821 Appendix C. Document Changelog 2823 [[ RFC Editor: This section is to be removed before publication ]] 2825 o draft-hoeneisen-pep-keysync-00: 2827 * Initial version 2829 o draft-hoeneisen-pep-keysync-01: 2831 * Major rewrite of upper sections 2833 * Adjust to reflect code changes 2835 * Move Finite-State Machine reference and code to Appendices A & 2836 B 2838 o draft-pep-keysync-00: 2840 * Updated docname and author's section 2842 o draft-pep-keysync-01: 2844 * Updated FSM states, actions, messages, events and interaction 2845 diagrams to reflect recent design changes 2847 * added latest revision of code and ASN.1 Type definitions 2849 Appendix D. Open Issues 2851 [[ RFC Editor: This section should be empty and is to be removed 2852 before publication ]] 2854 o Resolve several TODOs / add missing text 2856 Authors' Addresses 2858 Volker Birk 2859 pEp Foundation 2860 Oberer Graben 4 2861 CH-8400 Winterthur 2862 Switzerland 2864 Email: volker.birk@pep.foundation 2865 URI: https://pep.foundation/ 2866 Bernie Hoeneisen 2867 pEp Foundation 2868 Oberer Graben 4 2869 CH-8400 Winterthur 2870 Switzerland 2872 Email: bernie.hoeneisen@pep.foundation 2873 URI: https://pep.foundation/ 2875 Kelly Bristol 2876 pEp Foundation 2877 Oberer Graben 4 2878 CH-8400 Winterthur 2879 Switzerland 2881 Email: kelly.bristol@pep.foundation 2882 URI: https://pep.foundation/