[Docs] [txt|pdf] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: (draft-birk-pep-keysync) 00

Network Working Group                                       B. Hoeneisen
Internet-Draft                                                   Ucom.ch
Intended status: Standards Track                              H. Marques
Expires: January 8, 2020                                  pEp Foundation
                                                           July 07, 2019


        pretty Easy privacy (pEp): Key Synchronization Protocol
                     draft-hoeneisen-pep-keysync-00

Abstract

   Modern users of messaging systems usually have multiple devices, and
   often desire to send and receive encrypted messages on some or all of
   their devices.  Using encryption on multiple devices often results in
   situations where messages cannot be decrypted on the device used to
   read the message due to a missing private key.

   This document specifies a protocol for secure peer-to-peer
   synchronization of private keys across devices belonging to the same
   user (pEp Key Synchronization Protocol).

   The pretty Easy privacy (pEp) protocols describe a set of conventions
   for the automation of operations traditionally seen as barriers to
   the use and deployment of secure end-to-end interpersonal messaging.
   These include, but are not limited to, key management, key discovery,
   and private key handling.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on January 8, 2020.







Hoeneisen & Marques      Expires January 8, 2020                [Page 1]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


Copyright Notice

   Copyright (c) 2019 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Problem Statement . . . . . . . . . . . . . . . . . . . .   3
     1.2.  Approach  . . . . . . . . . . . . . . . . . . . . . . . .   4
     1.3.  Main Challenge  . . . . . . . . . . . . . . . . . . . . .   4
     1.4.  Requirements Language . . . . . . . . . . . . . . . . . .   4
     1.5.  Terms . . . . . . . . . . . . . . . . . . . . . . . . . .   4
   2.  General Description . . . . . . . . . . . . . . . . . . . . .   5
     2.1.  Use Cases for pEp KeySync . . . . . . . . . . . . . . . .   6
       2.1.1.  Form Device Group . . . . . . . . . . . . . . . . . .   6
       2.1.2.  Add New Device to Existing Device Group . . . . . . .   6
       2.1.3.  Exchange Private Keys . . . . . . . . . . . . . . . .   6
       2.1.4.  Leave Device Group  . . . . . . . . . . . . . . . . .   7
       2.1.5.  Remove other Device from Device Group . . . . . . . .   7
     2.2.  Interaction Diagrams  . . . . . . . . . . . . . . . . . .   7
       2.2.1.  Form Device Group . . . . . . . . . . . . . . . . . .   8
       2.2.2.  Add New Device to Existing Device Group . . . . . . .  16
       2.2.3.  Exchange Private Keys . . . . . . . . . . . . . . . .  23
       2.2.4.  Leave Device Group  . . . . . . . . . . . . . . . . .  23
       2.2.5.  Remove other Device from Device Group . . . . . . . .  23
     2.3.  Simplified Finite-State Machine . . . . . . . . . . . . .  23
   3.  Reference Implementation  . . . . . . . . . . . . . . . . . .  24
     3.1.  Full Finite-State Machine . . . . . . . . . . . . . . . .  24
       3.1.1.  States  . . . . . . . . . . . . . . . . . . . . . . .  24
       3.1.2.  Actions . . . . . . . . . . . . . . . . . . . . . . .  43
     3.2.  Messages  . . . . . . . . . . . . . . . . . . . . . . . .  69
       3.2.1.  Format  . . . . . . . . . . . . . . . . . . . . . . .  69
       3.2.2.  List of Messages Used in Finite-State Machine . . . .  69
       3.2.3.  Example Messages  . . . . . . . . . . . . . . . . . .  72
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .  72
   5.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  72
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  72



Hoeneisen & Marques      Expires January 8, 2020                [Page 2]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   7.  Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .  72
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  73
     8.1.  Normative References  . . . . . . . . . . . . . . . . . .  73
     8.2.  Informative References  . . . . . . . . . . . . . . . . .  73
   Appendix A.  Document Changelog . . . . . . . . . . . . . . . . .  74
   Appendix B.  Open Issues  . . . . . . . . . . . . . . . . . . . .  74
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  74

1.  Introduction

   This document specifies the pEp Key Synchronization (KeySync)
   Protocol, a means for secure peer-to-peer synchronization of private
   keys across devices belonging to the same user.

   This part of the pretty Easy privacy (pEp) protocols [I-D.birk-pep]
   presents a way to synchronize private key material in a decentralized
   manner that is easy to implement.  This network protocol is designed
   as a finite-state machine (FSM) along with the exchange of specific
   KeySync messages.

   For pEp implementations, pEp KeySync for key synchronization is a
   critical part of the broader pEp Sync protocol, which is designed to
   be extensible to allow for the synchronization of additional user
   data, such as configuration settings and peer trust status
   information across a user's devices.

   This document will provide a general description of pEp KeySync,
   including idealized use cases, diagrams, and examples of messages
   that may be generated during the KeySync process.

1.1.  Problem Statement

   Modern users of messaging systems usually have multiple devices, and
   often desire to send and receive encrypted messages on some or all of
   them.

   Using encryption on multiple devices often results in situations
   where messages cannot be decrypted on the device used to read the
   message due to a missing private key.  These messages were likely
   encrypted with a key that was generated on another device belonging
   to the same user.  For example, the sender encrypts with a key that
   was generated on the home laptop of the recipient.  The recipient
   then attempts to decrypt the message on their mobile phone, where the
   corresponding private key is not available.  As a result, the
   recipient either must return to their laptop to decrypt the message,
   or attempt to copy the correct private key to their mobile device,
   which may expose the user's private key to potential leaks or theft.




Hoeneisen & Marques      Expires January 8, 2020                [Page 3]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


1.2.  Approach

   The basic approach to solving the multiple-device decryption problem
   is to synchronize private keys among the devices of a user in a
   secure manner. pEp aims to do this by using Trustword confirmation
   (cf.  [I-D.birk-pep-trustwords]) between any two devices at a time
   for pairing purposes.  Simply put, a user needs to manually compare
   and confirm Trustwords before the automatic and security-sensitive
   transfer of private key information can occur.

1.3.  Main Challenge

   The main challenge, that pEp KeySync is designed to overcome, is to
   perform the synchronization in a secure manner so that private keys
   are not leaked or exposed to theft.

   Note: The case of an adversary getting access to the device itself is
   beyond the scope of this document.

1.4.  Requirements Language

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

1.5.  Terms

   The following terms are defined for the scope of this document:

   o  pEp Handshake: The process of one user contacting another over an
      independent channel in order to verify Trustwords (or by fallback:
      fingerprints).  This can be done in-person or through established
      verbal communication channels, like a phone call.
      [I-D.marques-pep-handshake]

      Note: In pEp KeySync, the handshake is used to authenticate own
      devices (the user normally compares the Trustwords directly by
      looking at the screens of the devices involved).

   o  Trustwords: A scalar-to-word representation of 16-bit numbers (0
      to 65535) to natural language words.  When doing a Handshake,
      peers are shown combined Trustwords of both public keys involved
      to ease the comparison.  [I-D.birk-pep-trustwords]

   o  Trust On First Use (TOFU): cf. [RFC7435], which states: "In a
      protocol, TOFU calls for accepting and storing a public key or
      credential associated with an asserted identity, without
      authenticating that assertion.  Subsequent communication that is



Hoeneisen & Marques      Expires January 8, 2020                [Page 4]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


      authenticated using the cached key or credential is secure against
      an MiTM attack, if such an attack did not succeed during the
      vulnerable initial communication."

   o  Man-in-the-middle (MITM) attack: cf. [RFC4949], which states: "A
      form of active wiretapping attack in which the attacker intercepts
      and selectively modifies communicated data to masquerade as one or
      more of the entities involved in a communication association."

   o  Identity: The combination of a unique user ID plus a specific
      address (email, network ID, URI, etc.).  A single user may have
      multiple identities.

   o  Device Group: All devices that are grouped to share data like
      cryptographic keys, trust information, calendar, configuration and
      other data.  The data is synchronized through a common channel for
      a given identity, e.g., an identity can be an email address and
      the common channel a mailbox in email.

   o  Group Key: A key pair primarily used by a Device Group for a
      certain identity.  A Device Group has a Group Key for each of a
      user's identities.

   o  Sole Device: A device which is not part of a Device Group.

   o  Grouped Device: A device which is already part of a Device Group.

   o  Beacon (message): A technical text message that is broadcast by
      Sole Devices and transmitted through a message sent to the channel
      of an identity.  Other Sole Devices, or a Grouped Device of the
      same unique identity and using that identity's channel, can
      interpret this Beacon in order to initiate negotiation for the
      formation of a Device Group.

2.  General Description

   This section describes an ideal-condition use case for pEp KeySync.
   It focuses on the main procedures and on the scenarios where
   everything works.  Unexpected user behavior, error handling, race
   conditions and the like are mostly omitted from this section in order
   to facilitate a better understanding of the general concepts of pEp
   KeySync.  Additional use cases will be discussed in further detail
   throughout Section 3.








Hoeneisen & Marques      Expires January 8, 2020                [Page 5]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


2.1.  Use Cases for pEp KeySync

2.1.1.  Form Device Group

   Our user, Alice, has two devices that are configured with pEp-
   implementing messaging clients and share the same identity for her
   preferred communication channel (in our example: a communication
   channel with an email address).  Let us call these devices Alice_R
   and Alice_O.  Each device already has its own key pair, which was
   automatically generated by the pEp protocol.  Neither device knows
   anything about the other.

   Alice wants full communication capability from both of her devices,
   but currently cannot do so, as the devices do not know about each
   other.  Alice will use pEp Keysync to form a Device Group and add her
   devices to it.  This allows for the exchange of private key data
   among its devices, allowing Alice to have full communication
   capability on both of her devices.

2.1.2.  Add New Device to Existing Device Group

   Sometime after devices Alice_R and Alice_O have formed a Device Group
   (cf.  Section 2.1.1), Alice buys another device, Alice_J, which is
   also configured with pEp-implementing messaging clients and shares
   the same identity for her preferred communication channel (the
   aforementioned email address).  Alice_J also has a key pair, which
   was automatically generated by the pEp protocol, just as the Grouped
   Devices Alice_R and Alice_O have.  But while the Grouped Devices know
   each other and have exchanged private keys, Alice_J and the Grouped
   Devices don't know anything each other.  Thus, Alice does not have
   full communication capability across the three devices.

   As before with devices Alice_R and Alice_O, Alice will use pEp
   Keysync to add device Alice_J to the existing Device Group, allowing
   all three devices to exchange private key information, and Alice to
   have access to her messages from any of them.

2.1.3.  Exchange Private Keys

   All devices from Alice are part of a Device Group (cf.  Section 2.1.1
   and Section 2.1.2).  However, as keys may expire or get reset,
   occasionally new key pairs are generated.  For Alice to be able to
   read all encrypted messages on all devices, any new private key needs
   to be shared with the other devices in the device group.  All devices
   in Alice's Device Group will share the latest private keys as they
   are generated, keeping all of her devices up to date and functioning
   as desired.




Hoeneisen & Marques      Expires January 8, 2020                [Page 6]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


2.1.4.  Leave Device Group

   Alice may decide that one of her devices (e.g., her mobile phone)
   should no longer have access to all private keys of the Device Group.
   Alice can manually tell that device to leave the Device Group.  The
   Device Group will ensure that further communication among the
   remaining Grouped Devices is private.

2.1.5.  Remove other Device from Device Group

   One of Alice's devices may be stolen or become otherwise compromised.
   She needs to ensure that the affected device no longer receives
   updates to private keys from the other devices in her Device Group.
   Alice can initiate actions to mitigate the damage, including the
   revocation of her private keys, as well as forcibly removing the
   compromised device from her Device Group.

2.2.  Interaction Diagrams

   The following interaction diagrams depict what happens during Alice's
   KeySync scenarios in a simplified manner.  For each scenario, we
   first present a successful case, then an unsuccessful case and,
   finally, a case that has been interrupted, or discontinued.  Some
   details are skipped here for the sake of readability.  Descriptions
   of the interactions are included after each diagram.


























Hoeneisen & Marques      Expires January 8, 2020                [Page 7]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


2.2.1.  Form Device Group

2.2.1.1.  Successful Case

                                    ,-.
                                    `-'
                                    /|\
     ,----------------.              |            ,------------------.
     |'Offerer' device|             / \           |'Requester' device|
     `-------+--------'            User           `--------+---------'
             |                      |                      |
             |                      |                      |
             |         1(r). Beacon (challenge TID)        |
             |<--------------------------------------------|
             |                      |                      |
             |         1(o). Beacon (challenge TID)        |
             |-------------------------------------------->|
             |                      |                      |
             |            2. NegotiationRequest            |
             |<--------------------------------------------|
             |                      |                      |
             |                      | 3. Display Trustwords|
             |                      |<- - - - - - - - - - -|
             |                      |                      |
             |              4. NegotiationOpen             |
             |-------------------------------------------->|
             |                      |                      |
             | 5. Display Trustwords|                      |
             | - - - - - - - - - - >|                      |
             |                      |                      |
             |        ,-----------------------------.      |
             |        |Handshake (user comparison   |      |
             |        |of Trustwords) successful    |      |
             |        `-----------------------------'      |
       ,-----------------------------------.               |
       |User presses 'Accept' button       |               |
       |on 'Requestor' device              |               |
       `-----------------------------------'               |
             |                      |       6. Accept      |
             |                      | - - - - - - - - - - >|
             |                      |                      |
             |           7. CommitAcceptRequester          |
             |<--------------------------------------------|
             |                      |                      |
       ,-----------------------------------.               |
       |User presses 'Accept' button       |               |
       |on 'Offerer' Device                |               |
       `-----------------------------------'               |



Hoeneisen & Marques      Expires January 8, 2020                [Page 8]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


             |       8. Accept      |                      |
             |<- - - - - - - - - - -|                      |
             |                      |                      |
             |            9. CommitAcceptOfferer           |
             |-------------------------------------------->|
             |                      |                      |
             |          10. OwnKeysOfferer + keys          |
             |-------------------------------------------->|
             |                      |                      |
             |                      |           ,----------------------.
             |                      |           |Requester is Grouped  |
             |                      |           `----------------------'
             |         11. OwnKeysRequester + keys         |
             |<--------------------------------------------|
             |                      |                      |
   ,--------------------.           |                      |
   |Offerer is Grouped  |           |                      |
   `--------------------'           |                      |
             |                      |                      |
     ,-------+--------.            User           ,--------+---------.
     |'Offerer' device|             ,-.           |'Requester' device|
     `----------------'             `-'           `------------------'
                                    /|\
                                     |
                                    / \


























Hoeneisen & Marques      Expires January 8, 2020                [Page 9]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   As depicted above, a user intends to form a Device Group in order to
   securely share key material among its members.  The group is formed
   by an 'Offerer' device and a 'Requester' device.  The names 'Offerer'
   and 'Requester' are derived from the FSM (cf.  Section 2.3), in which
   the device roles are defined during the start sequence, which is
   necessary for the FSM to work as intended.

   During initialization of pEp KeySync, each device generates a UUID
   version 4, variant 1 number, which is called a Transaction-ID (TID).
   These TIDs are sent as a challenge in a Beacon over the mutual
   channel, and the device roles of 'Offerer' and 'Requester' are
   determined by the numeric value of each device's unique TID.

   Note: All messages are 'broadcast'.  The TIDs added to each message
   allow the identification of received messages which pertain to the
   ongoing transaction and its sender.

   1.   Every device sends a Beacon message containing a challenge TID.
        Upon receipt of a Beacon message from another device, the the
        received challenge TID is compared with the device's own
        challenge TID.  The device which has a TID with a lower
        numerical value is assigned as the 'Requester', and the other
        device is automatically assigned as the 'Offerer'.

        Note: The 'Offerer' device MUST NOT start a Negotiation.  Thus,
        it re-sends its own Beacon (for robustness in case earlier
        Beacon message got lost) and waits.  Message 1(r) depicts the
        Beacon message sent by the 'Requester' device and is not
        required for the process to continue.



   2.   After determination of the role, the 'Requester' device sends a
        NegotiationRequest message.

   3.   The 'Requester' device displays the Trustwords to the user.

   4.   Upon receipt of the NegotiationRequest message, the 'Offerer'
        device sends a NegotiationOpen message.

   5.   The 'Offerer' device displays the Trustwords to the user.

   6.   The user compares the Trustwords of both devices.  As the
        Trustwords are the same on both devices, the user presses the
        'Accept' button on the 'Requester' device.

        Note 1: The user may also press the 'Accept' button on the
        'Offerer' device first.  The end result is not affected by which



Hoeneisen & Marques      Expires January 8, 2020               [Page 10]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


        'Accept' button is pressed first.  However, the order of the
        messages slightly changes.

        Note 2: The user may also choose to press the 'Cancel' button or
        the 'Reject' button (see below).



   7.   On receipt of the user's 'Accept', the 'Requester' device sends
        a CommitAcceptRequester message.

        The 'Offerer' device receives this message and waits for the
        user to press the local 'Accept' button.

   8.   The user compares the Trustwords of both devices and presses the
        'Accept' button on the 'Offerer' device.

        Note: The user may also choose to press the 'Cancel' button or
        the 'Reject' button (see below).



   9.   On receipt of the user's 'Accept', the 'Offerer' device sends a
        CommitAcceptRequester message.

   10.  The 'Offerer' device then sends an OwnKeysOfferer message along
        with the user's local key pairs (private and public keys) to
        to be synchronized.

   11.  Upon receipt of the OwnKeysOfferer message, the 'Requester'
        device is Grouped and sends an OwnKeysRequester message along
        with the user's local key pairs (private and public keys) to be
        synchronized.

        Upon receipt of the OwnKeysRequester message, also the 'Offerer'
        device is grouped.  The formation of the Device Group has been
        successful.














Hoeneisen & Marques      Expires January 8, 2020               [Page 11]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


2.2.1.2.  Unsuccessful Case

                                  ,-.
                                  `-'
                                  /|\
    ,----------------.             |            ,------------------.
    |'Offerer' device|            / \           |'Requester' device|
    `-------+--------'           User           `--------+---------'
            |                     |                      |
            |                     |                      |
   ,--------------------------------------------------------------!.
   |Messages (1-5) are same as in the successful case (see above) |_\
   `----------------------------------------------------------------'
            |                     |                      |
            |                     |                      |
            |       ,-----------------------------.      |
            |       |Handshake (user comparison   |      |
            |       |of Trustwords) unsuccessful  |      |
            |       `-----------------------------'      |
            |               ,------------------------------------.
            |               |User presses 'Reject' button        |
            |               |on 'Requestor' device               |
            |               `------------------------------------'
            |                     |      R6. Reject      |
            |                     | - - - - - - - - - - >|
            |                     |                      |
            |              R7. CommitReject              |
            |<-------------------------------------------|
            |                     |                      |
   ,--------------------------------------------------------------!.
   |Devices (still not grouped) will not try again                |_\
   `----------------------------------------------------------------'
            |                     |                      |
    ,-------+--------.           User           ,--------+---------.
    |'Offerer' device|            ,-.           |'Requester' device|
    `----------------'            `-'           `------------------'
                                  /|\
                                   |
                                  / \












Hoeneisen & Marques      Expires January 8, 2020               [Page 12]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   For unsuccessful KeySync attempts, messages 1-5 are the same as in a
   successful attempt (see above), but once the Trustwords are shown,
   events are as follows:

   R6.  The user compares the Trustwords of both devices. As the
        Trustwords do not match, the user presses the 'Reject' button on
        the 'Requester' device.

        Note: The user may also press the 'Reject' button on the
        'Offerer' device first. The end result is not affected by which
        'Reject' button is pressed first. However, the order of the
        messages slightly changes.


   R7. On receipt of the user's 'Reject', the 'Requester' device sends
       a CommitReject message.


   Once the CommitReject message is sent or received, respectively, the
   devices cannot form a Device Group, and pEp KeySync is disabled on
   both devices.  As a result, there are no further attempts to form a
   Device Group involving either of these two devices.





























Hoeneisen & Marques      Expires January 8, 2020               [Page 13]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


2.2.1.3.  Discontinuation Case

                                  ,-.
                                  `-'
                                  /|\
    ,----------------.             |            ,------------------.
    |'Offerer' device|            / \           |'Requester' device|
    `-------+--------'           User           `--------+---------'
            |                     |                      |
            |                     |                      |
   ,--------------------------------------------------------------!.
   |Messages (1-5) are same as in the successful case (see above) |_\
   `----------------------------------------------------------------'
            |                     |                      |
            |                     |                      |
            |       ,-----------------------------.      |
            |       |Handshake (user comparison   |      |
            |       |of Trustwords) discontinued  |      |
            |       `-----------------------------'      |
            |               ,------------------------------------.
            |               |User presses 'Cancel' button        |
            |               |on 'Requestor' device               |
            |               `------------------------------------'
            |                     |      C6. Cancel      |
            |                     | - - - - - - - - - - >|
            |                     |                      |
            |                C7. Rollback                |
            |<-------------------------------------------|
            |                     |                      |
   ,--------------------------------------------------------------!.
   |Devices (still not grouped) will try again                    |_\
   `----------------------------------------------------------------'
            |                     |                      |
    ,-------+--------.           User           ,--------+---------.
    |'Offerer' device|            ,-.           |'Requester' device|
    `----------------'            `-'           `------------------'
                                  /|\
                                   |
                                  / \












Hoeneisen & Marques      Expires January 8, 2020               [Page 14]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   For discontinued (canceled) KeySync attempts, messages 1-5 are the
   same as in a successful attempt (see above), but once the Trustwords
   are shown, events are as follows:

   C6.  The user decides to discontinue the process and presses the
        'Cancel' button on the 'Requester' device.

        Note: The user may also press the 'Cancel' button on the
        'Offerer' device first. The end result is not affected by which
        'Cancel' button is pressed first. However, the order of the
        messages slightly changes.


   C7. On receipt of the user's 'Cancel', the 'Requester' device sends
       a rollback message.


   The devices do not form a Device Group.  KeySync remains enabled and
   forming a Device Group can start again.
































Hoeneisen & Marques      Expires January 8, 2020               [Page 15]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


2.2.2.  Add New Device to Existing Device Group

2.2.2.1.  Successful Case

      ,-------.            ,-.
      |New    |            `-'           ,--------.          ,--------.
      |device |            /|\           |Active  |          |Passive |
      |to join|             |            |device  |          |devices |
      |group  |            / \           |in group|          |in group|
      `---+---'           User           `---+----'          `---+----'
          |                |                 |                   |
          |                |                 |                   |
          |            1. Beacon             |                   |
          |--------------------------------->|                   |
          |                |                 |                   |
          |                |     1. Beacon   |                   |
          |----------------------------------------------------->|
          |                |                 |                   |
          |              2(p). NegotiationRequest                |
          |<-----------------------------------------------------|
          |                |                 |                   |
          |                |       3(p) Display Trustwords       |
          |                |<- - - - - - - - - - - - - - - - - - |
          |                |                 |                   |
          |               4(p) NegotiationOpen                   |
          |----------------------------------------------------->|
          |                |                 |                   |
          |     2(a). NegotiationRequest     |                   |
          |<---------------------------------|                   |
          |                |                 |                   |
          |                |  3(a). Display  |                   |
          |                |     Trustwords  |                   |
          |                |<- - - - - - - - |                   |
          |                |                 |                   |
          |      4(a). NegotiationOpen       |                   |
          |--------------------------------->|                   |
          |                |                 |                   |
          | 5. Display     |                 |                   |
          |    Trustwords  |                 |                   |
          | - - - - - - - >|                 |                   |
          |                |                 |                   |
          |  ,-----------------------------. |                   |
          |  |Handshake (user comparison   | |                   |
          |  |of Trustwords) successful    | |                   |
          |  `-----------------------------' |                   |
          |          ,------------------------------.            |
          |          |User presses 'Accept' button  |            |
          |          |on a device in group          |            |



Hoeneisen & Marques      Expires January 8, 2020               [Page 16]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


          |          `------------------------------'            |
          |                |    6. Accept    |                   |
          |                | - - - - - - - ->|                   |
          |                |                 |                   |
          |                |                 |   7. GroupTrust   |
          |                |                 |      ThisKey      |
          |                |                 |------------------>|
          |                |                 |                   |
          |     8. CommitAcceptForGroup      |                   |
          |<---------------------------------|                   |
          |                |                 |                   |
   ,------------------------------.          |                   |
   |User presses 'Accept' button  |          |                   |
   |on new device                 |          |                   |
   `------------------------------'          |                   |
          |   9. Accept    |                 |                   |
          |<- - - - - - - -|                 |                   |
          |                |                 |                   |
          |        10. CommitAccept          |                   |
          |--------------------------------->|                   |
          |                |                 |                   |
          |      11. GroupKeys + keys        |                   |
          |<---------------------------------|                   |
          |                |                 |                   |
    ,------------.         |                 |                   |
    |New device  |         |                 |                   |
    |is grouped  |         |                 |                   |
    `------------'         |                 |                   |
          |      12. GroupKeys + keys        |                   |
          |--------------------------------->|                   |
          |                |                 |                   |
          |                | 12. GroupKeys + keys                |
          |----------------------------------------------------->|
          |                |                 |                   |
          |                |                 |                   |
      ,---+---.           User           ,---+----.          ,---+----.
      |New    |            ,-.           |Active  |          |Passive |
      |device |            `-'           |device  |          |devices |
      |to join|            /|\           |in group|          |in group|
      |group  |             |            `--------'          `--------'
      `-------'            / \










Hoeneisen & Marques      Expires January 8, 2020               [Page 17]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   As depicted above, a user intends to add a new device to an existing
   Device Group.

   Note: All messages are 'broadcast'.  The TIDs added to each message
   allow the identification of received messages which pertain to the
   ongoing transaction and its sender.

   1.   During initialization of pEp KeySync, the new device sends a
        Beacon message.

        Note: In the diagram, all messages marked "1.  Beacon" are a
        single message, but drawn separately in order to convey that the
        message is sent to all devices in the Device Group.

   2.   Upon receipt of a Beacon message from a device not part of a
        Device Group, all Grouped Devices are send a NegotiationRequest
        message.

        Note: Messages 2(a) and 2(p) are different instances of the
        NegotiationRequest message type.

   3.   All Grouped Devices display the Trustwords to the user.

   4.   Upon receipt of every NegotiationRequest message, the New Device
        sends a NegotiationOpen message.

        Note: Messages 4(a) and 4(p) are different instances of the
        NegotiationOpen message type.

   5.   The new device displays the Trustwords to the user.

   6.   The user compares the Trustwords of both devices and presses the
        'Accept' button on one of the Grouped Devices.

        Note 1: The Grouped Device that the user presses the 'Accept'
        button on now assumes the role of the active device in Group,
        while the other Grouped Devices get the role of passive devices
        in the group.



        Note 2: The user may also press the 'Accept' button on the new
        device first.  The end result is not affected by which 'Accept'
        button is pressed first.  However, the order and number of the
        messages change.

        Note 3: The user may also choose to press the 'Cancel' button or
        the 'Reject' button (see below).



Hoeneisen & Marques      Expires January 8, 2020               [Page 18]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   7.   On receipt of the user's 'Accept', the active Grouped Device
        sends a TrustThisKey message, which is consumed by the passive
        Grouped Devices.

   8.   Then, the Active Grouped Device also sends a
        CommitAcceptForGroup message.

        The new device receives this message and waits for the user to
        press the local 'Accept' button.

   9.   The user compares the Trustwords of both devices and presses the
        'Accept' button on the new device.

        Note: The user may also choose to press the 'Cancel' button or
        the 'Reject' button.  However, these cases are explained later.



   10.  On receipt of the user's 'Accept', the new device sends a
        CommitAccept message.

   11.  The new device then sends a GroupKeys message along with its own
        private keys.

   12.  Upon receipt of the GroupKeys message, the Active Grouped Device
        is Grouped and sends a GroupKeys message along with its own
        private keys.  The new device has successfully joined the Device
        Group.

   Note: In the diagram, all messages marked "12.  GroupKeys + keys" are
   a single message, but drawn separately in order to convey that the
   message is sent to all devices in the Device Group.



















Hoeneisen & Marques      Expires January 8, 2020               [Page 19]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


2.2.2.2.  Unsuccessful Case

     ,-------.            ,-.
     |New    |            `-'           ,--------.          ,--------.
     |device |            /|\           |Active  |          |Passive |
     |to join|             |            |device  |          |devices |
     |group  |            / \           |in group|          |in group|
     `---+---'           User           `---+----'          `---+----'
         |                |                 |                   |
         |                |                 |                   |
    ,---------------------------------------------------------------!.
    |Messages (1-5) are same as in the successful case (see above)  |_\
    `-----------------------------------------------------------------'
         |                |                 |                   |
         |                |                 |                   |
         |  ,-----------------------------. |                   |
         |  |Handshake (user comparison   | |                   |
         |  |of Trustwords) unsuccessful  | |                   |
         |  `-----------------------------' |                   |
         |          ,------------------------------.            |
         |          |User presses 'Reject' button  |            |
         |          |on a device in group          |            |
         |          `------------------------------'            |
         |                |    R6. Reject   |                   |
         |                | - - - - - - - ->|                   |
         |                |                 |                   |
         |        R7. CommitReject          |                   |
         |<---------------------------------|                   |
         |                |                 |                   |
         |                |                 |  R7. CommitReject |
         |                |                 |------------------>|
         |                |                 |                   |
   ,----------!.          |                 |                   |
   |New device|_\         |                 |                   |
   |(still not  |         |                 |                   |
   |grouped)    |         |                 |                   |
   |will not    |         |                 |                   |
   |try again   |         |                 |                   |
   `------------'         |                 |                   |
         |                |                 |                   |
     ,---+---.           User           ,---+----.          ,---+----.
     |New    |            ,-.           |Active  |          |Passive |
     |device |            `-'           |device  |          |devices |
     |to join|            /|\           |in group|          |in group|
     |group  |             |            `--------'          `--------'
     `-------'            / \





Hoeneisen & Marques      Expires January 8, 2020               [Page 20]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   For unsuccessful KeySync attempts, messages 1-5 are the same as in a
   successful attempt (see above), but once the Trustwords are shown,
   events are as follows:

   R6.  The user compares the Trustwords of both devices. As the
        Trustwords do not match, the user presses the 'Reject' button on
        one of the Grouped Devices.

        Note: The user may also press the 'Reject' button on the New
        Device first. The end result is not affected by which 'Reject'-
        Button is pressed first. However, the order and number of the
        messages slightly changes.


   R7. On receipt of the user's 'Reject', the 'Requester' device sends
       a 'CommitReject' message.

       Note: In the diagram, all messages marked "R7. CommitReject"
       are a single message, but drawn separately in order to convey
       that the message is sent to all devices in the Device Group.


   The new device does not join the group and pEp KeySync is disabled on
   it.  As a consequence, there are no further attempts to join the
   Device Group.

   Once the CommitReject message is sent or received, respectively, the
   new device cannot join the Device Group, and pEp KeySync is disabled
   on the new device.  As a result, there are no further attempts to
   join a Device Group by the new device.





















Hoeneisen & Marques      Expires January 8, 2020               [Page 21]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


2.2.2.3.  Discontinuation Case

     ,-------.            ,-.
     |New    |            `-'           ,--------.          ,--------.
     |device |            /|\           |Active  |          |Passive |
     |to join|             |            |device  |          |devices |
     |group  |            / \           |in group|          |in group|
     `---+---'           User           `---+----'          `---+----'
         |                |                 |                   |
         |                |                 |                   |
    ,---------------------------------------------------------------!.
    |Messages (1-5) are same as in the successful case (see above)  |_\
    `-----------------------------------------------------------------'
         |                |                 |                   |
         |                |                 |                   |
         |  ,-----------------------------. |                   |
         |  |Handshake (user comparison   | |                   |
         |  |of Trustwords) discontinued  | |                   |
         |  `-----------------------------' |                   |
         |          ,------------------------------.            |
         |          |User presses 'Cancel' button  |            |
         |          |on a device in group          |            |
         |          `------------------------------'            |
         |                |    C6. Cancel   |                   |
         |                | - - - - - - - ->|                   |
         |                |                 |                   |
         |          C7. Rollback            |                   |
         |<---------------------------------|                   |
         |                |                 |                   |
         |                |                 |    C7. Rollback   |
         |                |                 |------------------>|
         |                |                 |                   |
   ,----------!.          |                 |                   |
   |New device|_\         |                 |                   |
   |(still not  |         |                 |                   |
   |grouped)    |         |                 |                   |
   |will try    |         |                 |                   |
   |again       |         |                 |                   |
   `------------'         |                 |                   |
         |                |                 |                   |
     ,---+---.           User           ,---+----.          ,---+----.
     |New    |            ,-.           |Active  |          |Passive |
     |device |            `-'           |device  |          |devices |
     |to join|            /|\           |in group|          |in group|
     |group  |             |            `--------'          `--------'
     `-------'            / \





Hoeneisen & Marques      Expires January 8, 2020               [Page 22]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   For discontinued (canceled) KeySync attempts, messages 1-5 are the
   same as in a successful attempt (see above), but once the Trustwords
   are shown, events are as follows:

   C6.  The user decides to discontinue the process and presses the
        'Cancel' button on one of the Grouped Devices.

        Note: The user may also press the 'Cancel' button on the New
        Device first. The end result is not affected by which 'Cancel'-
        Button is pressed first. However, the order and number of the
        messages slightly changes.


   C7. On receipt of the user's 'Cancel', the 'Requester' device sends
       a rollback message.

       Note: In the diagram, all messages marked "C7. Rollback"
       are a single message, but drawn separately in order to convey
       that the message is sent to all devices in the Device Group.


   The new device does not join the Device Group.  KeySync remains
   enabled and joining a Device Group can start again.

2.2.3.  Exchange Private Keys

   [[ TODO ]]

2.2.4.  Leave Device Group

   [[ TODO ]]

2.2.5.  Remove other Device from Device Group

   [[ TODO ]]

2.3.  Simplified Finite-State Machine

   A simplified diagram of the implemented pEp KeySync finite-state
   machine (FSM), which does not contain the transitions that occur when
   pressing the 'Cancel' or 'Reject' buttons, can be found at:
   https://pep.foundation/dev/repos/internet-drafts/raw-
   file/tip/misc/figures/sync/sync_fsm_simplified.svg








Hoeneisen & Marques      Expires January 8, 2020               [Page 23]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


3.  Reference Implementation

   [[ Note: This description of the FSM implementation is Work-In-
   Progress.  For now it is supposed to be sufficient for the reader to
   understand the general functionality of the FSM, and thus lacking
   certain details.  The authors intend to enhance and refine it in
   later revisions of this document. ]]

3.1.  Full Finite-State Machine

   A full diagram of the implemented pEp KeySync FSM can be found at the
   following URL:

   https://pep.foundation/dev/repos/internet-drafts/raw-
   file/tip/misc/figures/sync/sync_fsm_full.svg

3.1.1.  States

3.1.1.1.  InitState

   On initialization, the FSM enters InitState, which evaluates and
   determines a device's group status.  If the device is detected to
   belong to a Device Group, the FSM transitions to state Grouped.
   Otherwise, the FSM transitions to state Sole (cf.  Section 3.1.2.1).

   Please find more information in the following code excerpt:

           state InitState {
               on Init {
                   if deviceGrouped
                       go Grouped;
                   go Sole;
               }
           }


3.1.1.2.  Sole

   This is the default state for an ungrouped device.  On
   initialization, a challenge TID is created and sent out inside a
   Beacon message.  It waits also for Beacons from other devices.  Upon
   receipt of a Beacon message from another device, the received
   challenge TID is compared with the own challenge.  The device with
   the lower challenge TID becomes 'Requester', the one with higher
   challenge TID becomes 'Offerer'.

   If determined to be 'Requester', a NegotiationRequest message is
   sent.



Hoeneisen & Marques      Expires January 8, 2020               [Page 24]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   The device determined as 'Offerer' receives the NegotiationRequest
   message, sends a NegotiationOpen message as response and the FSM
   transitions to state HandshakingOfferer.

   On receipt of the NegotiationOpen message, the 'Requester' FSM
   proceeds in one of two ways.  If the NegotiationOpen message comes
   from a Sole 'Offerer' Device, the FSM transitions to state
   HandshakingRequester.  If the NegotiationOpen message comes from a
   Grouped Device, the FSM transitions to state HandshakingToJoin.

   Please find more information in the following code excerpt:

           state Sole timeout=off {
               on Init {
                   do newChallengeAndNegotiationBase;
                   do showBeingSole;
                   send Beacon;
               }

               on KeyGen {
                   send Beacon;
               }

               on CannotDecrypt { // cry baby
                   send Beacon;
               }

               on Beacon {
                   if sameChallenge {
                       // this is our own Beacon; ignore
                   }
                   else {
                       if weAreOfferer {
                           do useOwnChallenge;
                           send Beacon;
                       }
                       else /* we are requester */ {
                           do openNegotiation;
                           do tellWeAreNotGrouped;
                           // requester is sending NegotiationRequest
                           send NegotiationRequest;
                           do useOwnChallenge;
                       }
                   }
               }
              on NegotiationRequest {
                   if sameChallenge { // challenge accepted
                       if sameNegotiation {



Hoeneisen & Marques      Expires January 8, 2020               [Page 25]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


                           // this is our own NegotiationRequest; ignore
                       }
                       else {
                           do storeNegotiation;
                           // offerer is accepting
                           // by confirming NegotiationOpen
                           send NegotiationOpen;
                           if partnerIsGrouped
                               go HandshakingToJoin;
                           else
                               go HandshakingOfferer;
                       }
                   }
               }

               on NegotiationOpen if sameNegotiationAndPartner {
                   // requester is receiving NegotiationOpen
                   do storeNegotiation;
                   go HandshakingRequester;
               }
           }


3.1.1.3.  HandshakingOfferer

   This state is entered by the 'Offerer' device only.  The FSM waits
   for the user to compare the Trustwords and to press either of the
   following buttons (on the 'Offerer' device):

   o  Accept: A CommitAcceptOfferer message is sent and the FSM
      transitions to state HandshakingPhase1Offerer

   o  Reject: A CommitReject message is sent, pEp KeySync is disabled,
      and the FSM transitions to state End

   o  Cancel: A Rollback message is sent and the FSM transitions to
      state Sole

   If the 'Accept' button was pressed on the 'Requester' device, a
   CommitAcceptRequester message is received and the FSM transitions to
   state HandshakingPhase2Offerer.

   If the 'Reject' button was pressed on the 'Requester' device, a
   CommitReject message is received. pEp KeySync is disabled and the FSM
   transitions to state End.

   If the 'Cancel' button was pressed on the 'Requester' device, a
   Rollback message is received and the FSM transitions to state Sole.



Hoeneisen & Marques      Expires January 8, 2020               [Page 26]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   Please find more information in the following code excerpt:

           // handshaking without existing Device group
           state HandshakingOfferer timeout=600 {
               on Init
                   do showSoleHandshake;

               // Cancel is Rollback
               on Cancel {
                   send Rollback;
                   go Sole;
               }

               on Rollback if sameNegotiationAndPartner
                   go Sole;

               // Reject is CommitReject
               on Reject {
                   send CommitReject;
                   do disable;
                   go End;
               }

               on CommitReject if sameNegotiationAndPartner {
                   do disable;
                   go End;
               }

               // Accept means init Phase1Commit
               on Accept {
                   do trustThisKey;
                   send CommitAcceptOfferer;
                   go HandshakingPhase1Offerer;
               }

               // got a CommitAccept from requester
               on CommitAcceptRequester if sameNegotiationAndPartner
                   go HandshakingPhase2Offerer;
           }


3.1.1.4.  HandshakingRequester

   This state is similar to the HandshakingOfferer (cf.
   Section 3.1.1.3), but with swapped roles.






Hoeneisen & Marques      Expires January 8, 2020               [Page 27]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   This state is entered by the 'Requester' device only.  The FSM waits
   for the user to compare the Trustwords and to press either of the
   following buttons (on the 'Requester' device):

   o  Accept: A CommitAcceptOfferer message is sent and the FSM
      transitions to state HandshakingPhase1Requester

   o  Reject: A CommitReject message is sent, pEp KeySync is disabled,
      and the FSM transitions to state End

   o  Cancel: A Rollback message is sent and the FSM transitions to
      state Sole

   If the 'Accept' button was pressed on the 'Offerer' device, a
   CommitAcceptOfferer message is received and the FSM transitions to
   state HandshakingPhase2Requester.

   If the 'Reject' button was pressed on the 'Offerer' device, a
   CommitReject message is received. pEp KeySync is disabled and the FSM
   transitions to state End.

   If the 'Cancel' button was pressed on the 'Offerer' device, a
   Rollback message is received and the FSM transitions to state Sole.

   Please find more information in the following code excerpt:

           state HandshakingRequester timeout=600 {
               on Init
                   do showSoleHandshake;

               // Cancel is Rollback
               on Cancel {
                   send Rollback;
                   go Sole;
               }

               on Rollback if sameNegotiationAndPartner
                   go Sole;

               // Reject is CommitReject
               on Reject {
                   send CommitReject;
                   do disable;
                   go End;
               }

               on CommitReject if sameNegotiationAndPartner {
                   do disable;



Hoeneisen & Marques      Expires January 8, 2020               [Page 28]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


                   go End;
               }

               // Accept means init Phase1Commit
               on Accept {
                   do trustThisKey;
                   send CommitAcceptRequester;
                   go HandshakingPhase1Requester;
               }

               // got a CommitAccept from offerer
               on CommitAcceptOfferer if sameNegotiationAndPartner
                   go HandshakingPhase2Requester;
           }

           state HandshakingPhase1Offerer {
               on Rollback if sameNegotiationAndPartner {
                   do untrustThisKey;
                   go Sole;
               }

               on CommitReject if sameNegotiationAndPartner {
                   do untrustThisKey;
                   do disable;
                   go End;
               }

               on CommitAcceptRequester if sameNegotiationAndPartner {
                   go FormingGroupOfferer;
               }
           }


3.1.1.5.  HandshakingPhase1Offerer

   This state is entered by the 'Offerer' device only.  The FSM waits
   for the user to finish the handshake on the 'Requester' device (i.e.
   compare the Trustwords and press either of the buttons on the
   'Requester' device):

   If the 'Accept' button was pressed on the 'Requester' device, a
   CommitAcceptRequester message is received and the FSM transitions to
   state FormingGroupOfferer.

   If the 'Reject' button was pressed on the 'Requester' device, a
   CommitReject message is received. pEp KeySync is disabled and the FSM
   transitions to state End.




Hoeneisen & Marques      Expires January 8, 2020               [Page 29]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   If the 'Cancel' button was pressed on the 'Requester' device, a
   Rollback message is received and the FSM transitions to state Sole.

   Please find more information in the following code excerpt:

          state HandshakingPhase1Offerer {
               on Rollback if sameNegotiationAndPartner {
                   do untrustThisKey;
                   go Sole;
               }

               on CommitReject if sameNegotiationAndPartner {
                   do untrustThisKey;
                   do disable;
                   go End;
               }

               on CommitAcceptRequester if sameNegotiationAndPartner {
                   go FormingGroupOfferer;
               }
           }


3.1.1.6.  HandshakingPhase1Requester

   This state is similar to the HandshakingPhase1Offerer (cf.
   Section 3.1.1.5), but with swapped roles.

   This state is entered by the 'Requester' device only.  The FSM waits
   for the user to finish the handshake on the 'Offerer' device (i.e.
   compare the Trustwords and press either of the buttons on the
   'Offerer' device):

   If the 'Accept' button was pressed on the 'Offerer' device, a
   CommitAcceptRequester message is received and the FSM transitions to
   state FormingGroupOfferer.

   If the 'Reject' button was pressed on the 'Offerer' device, a
   CommitReject message is received. pEp KeySync is disabled and the FSM
   transitions to state End.

   If the 'Cancel' button was pressed on the 'Offerer' device, a
   Rollback message is received and the FSM transitions to state Sole.

   Please find more information in the following code excerpt:






Hoeneisen & Marques      Expires January 8, 2020               [Page 30]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


           state HandshakingPhase1Requester {
               on Rollback if sameNegotiationAndPartner {
                   do untrustThisKey;
                   go Sole;
               }

               on CommitReject if sameNegotiationAndPartner {
                   do untrustThisKey;
                   do disable;
                   go End;
               }
               on CommitAcceptOfferer if sameNegotiationAndPartner {
                   go FormingGroupRequester;
               }
           }


3.1.1.7.  HandshakingPhase2Offerer

   This state is entered by the 'Offerer' device only.  The FSM waits
   for the user to compare the Trustwords and to press either of the
   following buttons (on the 'Offerer' device):

   o  Accept: The key used in the handshake is marked 'trusted', a
      CommitAcceptOfferer message is sent and the FSM transitions to
      state FormingGroupOfferer

   o  Reject: A CommitReject message is sent, pEp KeySync is disabled,
      and the FSM transitions to state End

   o  Cancel: A Rollback message is sent and the FSM transitions to
      state Sole

   Please find more information in the following code excerpt:

















Hoeneisen & Marques      Expires January 8, 2020               [Page 31]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


          state HandshakingPhase2Offerer {
               on Cancel {
                   send Rollback;
                   go Sole;
               }

               on Reject {
                   send CommitReject;
                   do disable;
                   go End;
               }

               on Accept {
                   send CommitAcceptOfferer;
                   do trustThisKey;
                   go FormingGroupOfferer;
               }
           }


3.1.1.8.  HandshakingPhase2Requester

   This state is similar to the HandshakingPhase2Offerer (cf.
   Section 3.1.1.7), but with swapped roles.

   This state is entered by the 'Requester' device only.  The FSM waits
   for the user to compare the Trustwords and to press either of the
   following buttons (on the 'Requester' device):

   o  Accept: The key used in the handshake is marked 'trusted', a
      CommitAcceptOfferer message is sent and the FSM transitions to
      state FormingGroupRequester

   o  Reject: A CommitReject message is sent, pEp KeySync is disabled,
      and the FSM transitions to state End

   o  Cancel: A Rollback message is sent and the FSM transitions to
      state Sole

   Please find more information in the following code excerpt:











Hoeneisen & Marques      Expires January 8, 2020               [Page 32]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


          state HandshakingPhase2Requester {
               on Cancel {
                   send Rollback;
                   go Sole;
               }

               on Reject {
                   send CommitReject;
                   do disable;
                   go End;
               }

               on Accept {
                   send CommitAcceptRequester;
                   do trustThisKey;
                   go FormingGroupRequester;
               }
           }


3.1.1.9.  FormingGroupOfferer

   This state is entered by the 'Offerer' device only.  The FSM sends a
   OwnKeysOfferer along with its own keys, and waits to receive the keys
   from the 'Requester' device.  Once received, the 'Requester' keys are
   saved and marked as Default Keys.  The Device Group is created and
   the FSM transitions to state Grouped.

   Please find more information in the following code excerpt:

          state FormingGroupOfferer {
               on Init {
                   do prepareOwnKeys;
                   send OwnKeysOfferer; // we're not grouped yet,
                                        // this is our own keys
               }

               on OwnKeysRequester {
                   do saveGroupKeys;
                   do receivedKeysAreDefaultKeys;
                   do showGroupCreated;
                   go Grouped;
               }
           }







Hoeneisen & Marques      Expires January 8, 2020               [Page 33]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


3.1.1.10.  FormingGroupRequester

   This state is entered by the 'Requester' device only.  The FSM sends
   a OwnKeysRequester along with its own keys, and waits to receive the
   keys from the 'Offerer' device.  Once received, the 'Offerer' keys
   are saved.  The own keys are marked as Default Keys.  The Device
   Group is created and the FSM transitions to state Grouped.

   Please find more information in the following code excerpt:

          state FormingGroupRequester {
               on Init {
                   do prepareOwnKeys;
                   send OwnKeysRequester; // we're not grouped yet,
                                          // this is our own keys
               }

               on OwnKeysOfferer {
                   do saveGroupKeys;
                   do ownKeysAreDefaultKeys;
                   do showGroupCreated;
                   go Grouped;
               }
           }


3.1.1.11.  Grouped

   This is the default state for any grouped device.  The device also
   waits for Beacons from other devices that are not yet part of the
   Device Group.

   Upon receipt of a Beacon message from Sole Device, the device sends a
   NegotiationRequest message and waits for the NegotiationOpen message.

   On receipt of the NegotiationOpen message from the Sole Device the
   FSM of the 'Requester' transitions to state HandshakingGrouped.

   In this state, various other events are also processed, which do not
   result in a transition to another state.

   Please find more information in the following code excerpt:









Hoeneisen & Marques      Expires January 8, 2020               [Page 34]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


           state Grouped timeout=off {
               on Init {
                   do newChallengeAndNegotiationBase;
                   do showBeingInGroup;
               }

               on GroupKeys
                   do saveGroupKeys;

               on KeyGen {
                   do prepareOwnKeys;
                   send GroupKeys;
               }

               on Beacon {
                   do openNegotiation;
                   do tellWeAreGrouped;
                   send NegotiationRequest;
                   do useOwnChallenge;
               }

               on NegotiationOpen if sameNegotiationAndPartner {
                   do storeNegotiation;
                   go HandshakingGrouped;
               }

               on GroupTrustThisKey
                   do trustThisKey;
           }


3.1.1.12.  HandshakingToJoin

   This state is entered by a new device only, i.e. a device that is not
   yet part of a Device Group.

   In this state the FSM waits for the user to compare the Trustwords
   and to press either of the following buttons (on the new device):

   o  Accept: A CommitAccept message is sent and the FSM transitions to
      state HandshakingToJoinPhase1

   o  Reject: A CommitReject message is sent, pEp KeySync is disabled
      (on the new device), and the FSM transitions to state End

   o  Cancel: A Rollback message is sent and the FSM transitions to
      state Sole




Hoeneisen & Marques      Expires January 8, 2020               [Page 35]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   If the 'Accept' button was pressed on a grouped device, a
   CommitAcceptForGroup message is received and the FSM transitions to
   state HandshakingToJoinPhase2

   If the 'Reject' button was pressed on a grouped device, a
   CommitReject message is received. pEp KeySync is disabled (on the new
   device) and the FSM transitions to state End.

   If the 'Cancel' button was pressed on the 'Requester' device, a
   Rollback message is received and the FSM transitions to state Sole.

   Please find more information in the following code excerpt:







































Hoeneisen & Marques      Expires January 8, 2020               [Page 36]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


          // sole device handshaking with group
           state HandshakingToJoin {
               on Init
                   do showJoinGroupHandshake;

               // Cancel is Rollback
               on Cancel {
                   send Rollback;
                   go Sole;
               }

               on Rollback if sameNegotiationAndPartner
                   go Sole;

               // Reject is CommitReject
               on Reject {
                   send CommitReject;
                   do disable;
                   go End;
               }

               on CommitAcceptForGroup if sameNegotiationAndPartner
                   go HandshakingToJoinPhase2;

               on CommitReject if sameNegotiationAndPartner {
                   do disable;
                   go End;
               }

               // Accept is Phase1Commit
               on Accept {
                   do trustThisKey;
                   send CommitAccept;
                   go HandshakingToJoinPhase1;
               }
           }


3.1.1.13.  HandshakingToJoinPhase1

   This state is entered by a new device only, i.e. a device that is not
   yet part of a Device Group.  The FSM waits for the user to finish the
   handshake on a grouped device (i.e. compare the Trustwords and press
   either of the buttons on a grouped device):

   If the 'Accept' button was pressed on a grouped device, a
   CommitAcceptForGroup message is received and the FSM transitions to
   state JoiningGroup.



Hoeneisen & Marques      Expires January 8, 2020               [Page 37]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   If the 'Reject' button was pressed on a grouped device, a
   CommitReject message is received. pEp KeySync is disabled (on the new
   device) and the FSM transitions to state End.

   If the 'Cancel' button was pressed on the 'Requester' device, a
   Rollback message is received and the FSM transitions to state Sole.

   Please find more information in the following code excerpt:

           state HandshakingToJoinPhase1 {
               on Rollback if sameNegotiationAndPartner
                   go Sole;

               on CommitReject if sameNegotiationAndPartner {
                   do disable;
                   go End;
               }

               on CommitAcceptForGroup if sameNegotiationAndPartner
                   go JoiningGroup;
           }


3.1.1.14.  HandshakingToJoinPhase2

   This state is entered by a new device only, i.e. a device that is not
   yet part of a Device Group.

   In this state the FSM waits for the user to compare the Trustwords
   and to press either of the following buttons (on the new device):

   o  Accept: A CommitAccept message is sent and the FSM transitions to
      state JoiningGroup

   o  Reject: A CommitReject message is sent, pEp KeySync is disabled
      (on the new device), and the FSM transitions to state End

   o  Cancel: A Rollback message is sent and the FSM transitions to
      state Sole

   Please find more information in the following code excerpt:










Hoeneisen & Marques      Expires January 8, 2020               [Page 38]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


          state HandshakingToJoinPhase2 {
               on Cancel {
                   send Rollback;
                   go Sole;
               }

               on Reject {
                   send CommitReject;
                   do disable;
                   go End;
               }

               on Accept {
                   do trustThisKey;
                   go JoiningGroup;
               }
           }


3.1.1.15.  JoiningGroup

   This state is entered by a new device only, i.e. a device that is not
   yet part of a Device Group.

   The FSM waits to receive the keys from the active grouped device.
   Once received, these are saved and marked as default keys.  Then it
   sends all keys to the grouped devices and the FSM transitions to
   state Grouped.

   Please find more information in the following code excerpt:

          state JoiningGroup {
               on GroupKeys {
                   do saveGroupKeys;
                   do receivedKeysAreDefaultKeys;
                   do prepareOwnKeys;
                   send GroupKeys;
                   do showDeviceAdded;
                   go Grouped;
               }
           }


3.1.1.16.  HandshakingGrouped

   This state is entered by grouped devices only, i.e., devices that are
   part of a Device Group.




Hoeneisen & Marques      Expires January 8, 2020               [Page 39]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   In this state the FSM waits for the user to compare the Trustwords
   and to press either of the following buttons (on any grouped device,
   which now becomes the 'Active' grouped device):

   o  Accept: A CommitAcceptForGroup message is sent and the FSM
      transitions to state HandshakingGroupedPhase1

   o  Reject: A CommitReject message is sent and the FSM transitions to
      state Grouped

   o  Cancel: A Rollback message is sent and the FSM transitions to
      state Grouped

   If the 'Accept' button was pressed on the new device, a CommitAccept
   message is received and the FSM transitions to state
   HandshakingPhase2

   If the 'Reject' button was pressed on the new device, a CommitReject
   message is received and the FSM transitions to state Grouped.

   If the 'Cancel' button was pressed on the new device, a Rollback
   message is received and the FSM transitions to state Grouped.

   In this state also a various other events are processed, which do not
   result in a transition to another state.

   Please find more information in the following code excerpt:
























Hoeneisen & Marques      Expires January 8, 2020               [Page 40]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


          state HandshakingGrouped {
               on Init
                   do showGroupedHandshake;

               // Cancel is Rollback
               on Cancel {
                   send Rollback;
                   go Grouped;
               }

               on Rollback if sameNegotiationAndPartner
                   go Grouped;

               // Reject is CommitReject
               on Reject {
                   send CommitReject;
                   go Grouped;
               }

               on CommitReject if sameNegotiationAndPartner
                   go Grouped;

               // Accept is Phase1Commit
               on Accept {
                   do trustThisKey;
                   send GroupTrustThisKey;
                   send CommitAcceptForGroup;
                   go HandshakingGroupedPhase1;
               }

               on CommitAccept if sameNegotiationAndPartner
                   go HandshakingGroupedPhase2;

               on GroupTrustThisKey {
                   do hideHandshakeDialog;
                   do trustThisKey;
               }

               on GroupKeys
                   do saveGroupKeys;
           }


3.1.1.17.  HandshakingGroupedPhase1

   This state is entered by grouped devices only, i.e., devices that are
   part of a Device Group.  The FSM waits for the user to finish the




Hoeneisen & Marques      Expires January 8, 2020               [Page 41]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   handshake on the new device (i.e., compare the Trustwords and press
   either of the buttons on the new device):

   If the 'Accept' button was pressed on the new device, a CommitAccept
   message is received and the FSM transitions to state Grouped

   If the 'Reject' button was pressed on the new device, a CommitReject
   message is received and the FSM transitions to state Grouped.

   If the 'Cancel' button was pressed on the new device, a Rollback
   message is received and the FSM transitions to state Grouped.

   In this state also a various other events are processed, which do not
   result in a transition to another state.

   Please find more information in the following code excerpt:

           state HandshakingGroupedPhase1 {
               on Rollback if sameNegotiationAndPartner
                   go Grouped;

               on CommitReject if sameNegotiationAndPartner
                   go Grouped;

               on CommitAccept if sameNegotiationAndPartner {
                   do prepareOwnKeys;
                   send GroupKeys;
                   go Grouped;
               }

               on GroupTrustThisKey {
                   do trustThisKey;
               }

               on GroupKeys
                   do saveGroupKeys;
           }


3.1.1.18.  HandshakingGroupedPhase2

   This state is entered by grouped devices only, i.e. devices that are
   part of a Device Group.

   In this state the FSM waits for the user to compare the Trustwords
   and to press either of the following buttons (on any grouped device,
   which now becomes the 'Active' grouped device):




Hoeneisen & Marques      Expires January 8, 2020               [Page 42]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   o  Accept: A CommitAcceptForGroup message is sent and the FSM
      transitions to state HandshakingGroupedPhase1

   o  Reject: A CommitReject message is sent and the FSM transitions to
      state Grouped

   o  Cancel: A Rollback message is sent and the FSM transitions to
      state Grouped

   In this state also various other events are processed, which do not
   result in a transition to another state, but in the execution of
   certain actions (e.g., saveGroupKeys).

   Please find more information in the following code excerpt:

           state HandshakingGroupedPhase2 {
               on Cancel {
                   send Rollback;
                   go Grouped;
               }

               on Reject {
                   send CommitReject;
                   go Grouped;
               }

               on Accept {
                   do trustThisKey;
                   send GroupTrustThisKey;
                   do prepareOwnKeys;
                   send GroupKeys;
                   go Grouped;
               }

               on GroupTrustThisKey {
                   do trustThisKey;
               }

               on GroupKeys
                   do saveGroupKeys;
           }


3.1.2.  Actions

   Actions describe internal FSM functions, and fall into two general
   types.  The first action type is a conditional 'if' statement, which
   direct the transitional states within the FSM (cf. 'if' statements;



Hoeneisen & Marques      Expires January 8, 2020               [Page 43]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   e.g., 'if deviceGrouped').  The second action type directs state
   changes which KeySync implementers can use to drive UI functionality,
   such as 'do' statements that trigger dialog box changes (cf 'do'
   statements; e.g., 'do hideHandshakeDialog').

3.1.2.1.  deviceGrouped (conditional)

   The 'deviceGrouped' conditional evaluates true if a device is already
   in a Device Group.  This boolean value is available and eventually
   altered locally on every KeySync-enabled device.  For example, in the
   reference implementation, this boolean value is stored in a local SQL
   database.

   The 'deviceGrouped' value is what the KeySync FSM uses upon
   initialization to determine whether a device should transition to
   state Sole or state Grouped.

   The following code excerpt shows where this action is called:

           state InitState {
               on Init {
                   if deviceGrouped
                       go Grouped;
                   go Sole;
               }
           }


3.1.2.2.  disable

   The 'disable' function may be called in an number of scenarios.  For
   example, a user has rejected a pEp Handshake on either device
   involved in a pEp Handshake.  At this time, in all cases, invoking
   the 'disable' function results in the FSM transitioning to state End,
   which disables the KeySync feature.

   The following code excerpt shows where this action is called:

           // handshaking without existing Device group
           state HandshakingOfferer timeout=600 {
               on Init
                   do showSoleHandshake;

               // Cancel is Rollback
               on Cancel {
                   send Rollback;
                   go Sole;
               }



Hoeneisen & Marques      Expires January 8, 2020               [Page 44]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


               on Rollback if sameNegotiationAndPartner
                   go Sole;

               // Reject is CommitReject
               on Reject {
                   send CommitReject;
                   do disable;
                   go End;
               }

               on CommitReject if sameNegotiationAndPartner {
                   do disable;
                   go End;
               }

           [...]

           // handshaking without existing Device group
           state HandshakingRequester timeout=600 {
               on Init
                   do showSoleHandshake;

               // Cancel is Rollback
               on Cancel {
                   send Rollback;
                   go Sole;
               }

               on Rollback if sameNegotiationAndPartner
                   go Sole;

               // Reject is CommitReject
               on Reject {
                   send CommitReject;
                   do disable;
                   go End;
               }

               on CommitReject if sameNegotiationAndPartner {
                   do disable;
                   go End;
               }

           [...]

           state HandshakingPhase1Offerer {
               on Rollback if sameNegotiationAndPartner {
                   do untrustThisKey;



Hoeneisen & Marques      Expires January 8, 2020               [Page 45]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


                   go Sole;
               }

               on CommitReject if sameNegotiationAndPartner {
                   do untrustThisKey;
                   do disable;
                   go End;
               }

           [...]

           state HandshakingPhase1Requester {
               on Rollback if sameNegotiationAndPartner {
                   do untrustThisKey;
                   go Sole;
               }

               on CommitReject if sameNegotiationAndPartner {
                   do untrustThisKey;
                   do disable;
                   go End;
               }

           [...]

           state HandshakingToJoinPhase1 {
               on Rollback if sameNegotiationAndPartner
                   go Sole;

               on CommitReject if sameNegotiationAndPartner {
                   do disable;
                   go End;
               }

               on CommitAcceptForGroup if sameNegotiationAndPartner
                   go JoiningGroup;
           }

           [...]

           [[ TODO: More occurrences exist; perhaps it's better
                    to move to appendix? ]]









Hoeneisen & Marques      Expires January 8, 2020               [Page 46]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


3.1.2.3.  hideHandshakeDialog

   The 'hideHandshakeDialog' function is invoked when a
   GroupTrustThisKey message is received by a device which is in the
   Grouped state and negotiating the addition of a new device, but
   another device within the Device Group has already confirmed the
   Trustwords dialog to accept the new device.

   This action is intended to send an event to the 'Passive' grouped
   devices that forces the closure of any unnecessary dialog boxes.

   The following code excerpt shows where this action is called:







































Hoeneisen & Marques      Expires January 8, 2020               [Page 47]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


          state HandshakingGrouped {
               on Init
                   do showGroupedHandshake;

               // Cancel is Rollback
               on Cancel {
                   send Rollback;
                   go Grouped;
               }

               on Rollback if sameNegotiationAndPartner
                   go Grouped;

               // Reject is CommitReject
               on Reject {
                   send CommitReject;
                   go Grouped;
               }

               on CommitReject if sameNegotiationAndPartner
                   go Grouped;

               // Accept is Phase1Commit
               on Accept {
                   do trustThisKey;
                   send GroupTrustThisKey;
                   send CommitAcceptForGroup;
                   go HandshakingGroupedPhase1;
               }

               on CommitAccept if sameNegotiationAndPartner
                   go HandshakingGroupedPhase2;

               on GroupTrustThisKey {
                   do hideHandshakeDialog;
                   do trustThisKey;
               }

               on GroupKeys
                   do saveGroupKeys;
           }


3.1.2.4.  openNegotiation

   An 'openNegotiation' action is carried out either by a Sole Device in
   the 'Requester' role, or a Grouped device upon receipt of a Beacon
   message from another Sole device.  Most importantly, this action



Hoeneisen & Marques      Expires January 8, 2020               [Page 48]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   ensures that the own TID and the challenge TID of the Sole Device get
   combined by the mathematical XOR function.  In this way, a common TID
   exists which can be used by both devices a user wishes to pair.  This
   TID is crucial in allowing the devices to recognize themselves in a
   particular pairing process, as multiple pairing process can occur
   simultaneously.

   The following code excerpt shows where this action is called:

           state Sole timeout=off {
               on Init {
                   do newChallengeAndNegotiationBase;
                   do showBeingSole;
                   send Beacon;
               }

               on KeyGen {
                   send Beacon;
               }

               on CannotDecrypt { // cry baby
                   send Beacon;
               }

               on Beacon {
                   if sameChallenge {
                       // this is our own Beacon; ignore
                   }
                   else {
                       if weAreOfferer {
                           do useOwnChallenge;
                           send Beacon;
                       }
                       else /* we are requester */ {
                           do openNegotiation;
                           do tellWeAreNotGrouped;
                           // requester is sending NegotiationRequest
                           send NegotiationRequest;
                           do useOwnChallenge;
                       }
                   }

           [...]

           state Grouped timeout=off {
               on Init {
                   do newChallengeAndNegotiationBase;
                   do showBeingInGroup;



Hoeneisen & Marques      Expires January 8, 2020               [Page 49]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


               }

               on GroupKeys
                   do saveGroupKeys;

               on KeyGen {
                   do prepareOwnKeys;
                   send GroupKeys;
               }

               on Beacon {
                   do openNegotiation;
                   do tellWeAreGrouped;
                   send NegotiationRequest;
                   do useOwnChallenge;
               }



3.1.2.5.  ownKeysAreDefaultKeys

   [[ TODO ]]

   The following code excerpt shows where this action is called:



























Hoeneisen & Marques      Expires January 8, 2020               [Page 50]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


           state FormingGroupOfferer {
               on Init {
                   do prepareOwnKeys;
                   send OwnKeysOfferer; // we're not grouped yet,
                                        // this is our own keys
               }

               on OwnKeysRequester {
                   do saveGroupKeys;
                   do receivedKeysAreDefaultKeys;
                   do showGroupCreated;
                   go Grouped;
               }
           }

           state FormingGroupRequester {
               on Init {
                   do prepareOwnKeys;
                   send OwnKeysRequester; // we're not grouped yet,
                                          // this is our own keys
               }

               on OwnKeysOfferer {
                   do saveGroupKeys;
                   do ownKeysAreDefaultKeys;
                   do showGroupCreated;
                   go Grouped;
               }
           }


3.1.2.6.  newChallengeAndNegotiationBase

   [[ TODO ]]

   The following code excerpt shows where this action is called:















Hoeneisen & Marques      Expires January 8, 2020               [Page 51]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


           state Sole timeout=off {
               on Init {
                   do newChallengeAndNegotiationBase;
                   do showBeingSole;
                   send Beacon;
               }

           [...]

           state Grouped timeout=off {
               on Init {
                   do newChallengeAndNegotiationBase;
                   do showBeingInGroup;
               }


3.1.2.7.  partnerIsGrouped (conditional)

   [[ TODO ]]

   The following code excerpt shows where this action is called:

           state Sole timeout=off {

               [...]

               on NegotiationRequest {
                   if sameChallenge { // challenge accepted
                       if sameNegotiation {
                           // this is our own NegotiationRequest; ignore
                       }
                       else {
                           do storeNegotiation;
                           // offerer is accepting by confirming
                           // NegotiationOpen
                           send NegotiationOpen;
                           if partnerIsGrouped
                               go HandshakingToJoin;
                           else
                               go HandshakingOfferer;
                       }
                   }
               }








Hoeneisen & Marques      Expires January 8, 2020               [Page 52]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


3.1.2.8.  prepareOwnKeys

   [[ TODO ]]

   The following code excerpt shows where this action is called:

           state FormingGroupOfferer {
               on Init {
                   do prepareOwnKeys;
                   send OwnKeysOfferer; // we're not grouped yet,
                                        // this is our own keys
               }

               [...]

           [...]

           state FormingGroupRequester {
               on Init {
                   do prepareOwnKeys;
                   send OwnKeysRequester; // we're not grouped yet,
                                          // this is our own keys
               }

               [...]

           [...]

           state Grouped timeout=off {

               [...]

               on KeyGen {
                   do prepareOwnKeys;
                   send GroupKeys;
               }

               [...]

           [...]


3.1.2.9.  receivedKeysAreDefaultKeys

   The 'receivedKeysAreDefaultKeys' action tells the pEp implementer to
   set the keys just received as the default for outgoing
   communications.




Hoeneisen & Marques      Expires January 8, 2020               [Page 53]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   [[ TODO: Clear out, in which cases which keys are used as default
   keys. ]]

   The following code excerpt shows where this action is called:

           state FormingGroupOfferer {
               on Init {
                   do prepareOwnKeys;
                   send OwnKeysOfferer; // we're not grouped yet,
                                        // this is our own keys
               }

               on OwnKeysRequester {
                   do saveGroupKeys;
                   do receivedKeysAreDefaultKeys;
                   do showGroupCreated;
                   go Grouped;
               }
           }

           [...]

           state JoiningGroup {
               on GroupKeys {
                   do saveGroupKeys;
                   do receivedKeysAreDefaultKeys;
                   do prepareOwnKeys;
                   send GroupKeys;
                   do showDeviceAdded;
                   go Grouped;
               }
           }

           [...]


3.1.2.10.  sameChallenge (conditional)

   [[ TODO ]]

   The following code excerpt shows where this action is called:

           state Sole timeout=off {
               on Init {
                   do newChallengeAndNegotiationBase;
                   do showBeingSole;
                   send Beacon;
               }



Hoeneisen & Marques      Expires January 8, 2020               [Page 54]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


               on KeyGen {
                   send Beacon;
               }

               on CannotDecrypt { // cry baby
                   send Beacon;
               }

               on Beacon {
                   if sameChallenge {
                       // this is our own Beacon; ignore
                   }
                   else {
                       if weAreOfferer {
                           do useOwnChallenge;
                           send Beacon;
                       }
                       else /* we are requester */ {
                           do openNegotiation;
                           do tellWeAreNotGrouped;
                           // requester is sending NegotiationRequest
                           send NegotiationRequest;
                           do useOwnChallenge;
                       }
                   }

               on NegotiationRequest {
                   if sameChallenge { // challenge accepted
                       if sameNegotiation {
                           // this is our own NegotiationRequest; ignore
                       }
                       else {
                           do storeNegotiation;
                           // offerer is accepting by confirming
                           // NegotiationOpen
                           send NegotiationOpen;
                           if partnerIsGrouped
                               go HandshakingToJoin;
                           else
                               go HandshakingOfferer;
                       }
                   }
               }

           [...]






Hoeneisen & Marques      Expires January 8, 2020               [Page 55]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


3.1.2.11.  sameNegotiation (conditional)

   The 'sameNegotiation' action evaluates true if the FSM finds a
   NegotiationRequest message that a Sole Device sent out is determined
   to be self-originating.  The Transaction ID (TID) will be an exact
   match upon comparison, and the NegotiationRequest will be ignored as
   a result.

   The following code excerpt shows where this action is called:

           state Sole timeout=off {

               [...]

               on NegotiationRequest {
                   if sameChallenge { // challenge accepted
                       if sameNegotiation {
                           // this is our own NegotiationRequest; ignore
                       }
                       else {
                           do storeNegotiation;
                           // offerer is accepting by confirming
                           // NegotiationOpen
                           send NegotiationOpen;
                           if partnerIsGrouped
                               go HandshakingToJoin;
                           else
                               go HandshakingOfferer;
                       }
                   }
               }


3.1.2.12.  sameNegotiationAndPartner (conditional)

   [[ TODO ]]

   The following code excerpt shows where this action is called:


3.1.2.13.  saveGroupKeys

   [[ TODO ]]

   The following code excerpt shows where this action is called:






Hoeneisen & Marques      Expires January 8, 2020               [Page 56]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


3.1.2.14.  showBeingInGroup

   The 'showBeingInGroup' action (in state Grouped) is used to notify a
   pEp implementer that a device is Grouped and to prepare the necessary
   structures to potentially carry out KeySync (in case any other device
   exists and a Beacon from a Sole Device appears at some point).

   The following code excerpt shows where this action is called:

           state Grouped timeout=off {
               on Init {
                   do newChallengeAndNegotiationBase;
                   do showBeingInGroup;
               }


3.1.2.15.  showBeingSole

   The 'showBeingSole' action (in state Sole) is used to notify a pEp
   implementer that a device is ungrouped (or: sole) and to prepare the
   necessary structures to potentially carry out KeySync (in case any
   other device exists and a negotiation starts).

   The following code excerpt shows where this action is called:

           state Sole timeout=off {
               on Init {
                   do newChallengeAndNegotiationBase;
                   do showBeingSole;
                   send Beacon;
               }


3.1.2.16.  showDeviceAdded

   The 'showDeviceAdded' action is used to notify a pEp implementer that
   a Sole Device was added to an already existing Device Group.

   The following code excerpt shows where this action is called:












Hoeneisen & Marques      Expires January 8, 2020               [Page 57]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


           state JoiningGroup {
               on GroupKeys {
                   do saveGroupKeys;
                   do receivedKeysAreDefaultKeys;
                   do prepareOwnKeys;
                   send GroupKeys;
                   do showDeviceAdded;
                   go Grouped;
               }
           }


3.1.2.17.  showGroupCreated

   In both roles a Sole Device can assume (either as Requester or
   Offerer), this action 'showGroupCreated' ensures that the pEp
   implementer gets a notification that a new Device Group was formed
   (both devices coming from Sole state in their respective FSMs).

   The following code excerpt shows where this action is called:































Hoeneisen & Marques      Expires January 8, 2020               [Page 58]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


           state FormingGroupOfferer {
               on Init {
                   do prepareOwnKeys;
                   send OwnKeysOfferer; // we're not grouped yet,
                                        // this is our own keys
               }

               on OwnKeysRequester {
                   do saveGroupKeys;
                   do receivedKeysAreDefaultKeys;
                   do showGroupCreated;
                   go Grouped;
               }
           }

                  state FormingGroupRequester {
               on Init {
                   do prepareOwnKeys;
                   send OwnKeysRequester; // we're not grouped yet,
                                          // this is our own keys
               }

               on OwnKeysOfferer {
                   do saveGroupKeys;
                   do ownKeysAreDefaultKeys;
                   do showGroupCreated;
                   go Grouped;
               }
           }


3.1.2.18.  showGroupedHandshake

   The 'showGroupedHandshake' action notifies a pEp implementer to show
   a pEp Handshake on the own, already Grouped Device (which is thus in
   state Grouped).  That means, the Handshake should be displayed in a
   way indicating there is another (yet) Sole Device willing to join the
   Device Group one is already a member of.

   The following code excerpt shows where this action is called:

           state HandshakingGrouped {
               on Init
                   do showGroupedHandshake;







Hoeneisen & Marques      Expires January 8, 2020               [Page 59]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


3.1.2.19.  showJoinGroupHandshake

   The 'showJoinGroupHandshake' action is used to notify pEp
   implementers to show a Handshake dialog when a Sole Device is to be
   grouped with an already existing Device Group, such that a user can
   'Accept', 'Cancel' or 'Reject' a group joining process.

   The following code excerpt shows where this action is called:

           // sole device handshaking with group
           state HandshakingToJoin {
               on Init
                   do showJoinGroupHandshake;


3.1.2.20.  showSoleHandshake

   For either the role of the Requester or the Offerer, in case of two
   Sole Devices, 'showSoleHandshake' notifies a pEp implementer that a
   pEp Handshake dialog between the two devices in negotiation has to be
   shown (depending on the role this action is called from two different
   states; see code below), such that the user (on both Sole Devices in
   user-defined sequence) can either press 'Accept', 'Cancel' or
   'Reject' to decide on the group formation process.

   The following code excerpt shows where this action is called:

           // handshaking without existing Device group
           state HandshakingRequester timeout=600 {
               on Init
                   do showSoleHandshake;

           [...]

           // handshaking without existing Device group
           state HandshakingOfferer timeout=600 {
               on Init
                   do showSoleHandshake;


3.1.2.21.  storeNegotiation

   [[ TODO ]]

   The following code excerpt shows where this action is called:






Hoeneisen & Marques      Expires January 8, 2020               [Page 60]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


           state Sole timeout=off {

               [...]

               on NegotiationRequest {
                   if sameChallenge { // challenge accepted
                       if sameNegotiation {
                           // this is our own NegotiationRequest; ignore
                       }
                       else {
                           do storeNegotiation;
                           // offerer is accepting by confirming
                           // NegotiationOpen
                           send NegotiationOpen;
                           if partnerIsGrouped
                               go HandshakingToJoin;
                           else
                               go HandshakingOfferer;
                       }
                   }
               }

               on NegotiationOpen if sameNegotiationAndPartner {
                   // requester is receiving NegotiationOpen
                   do storeNegotiation;
                   go HandshakingRequester;
               }

           [...]

           state Grouped timeout=off {

               [...]

               on NegotiationOpen if sameNegotiationAndPartner {
                   do storeNegotiation;
                   go HandshakingGrouped;
               }

               [...]

           }









Hoeneisen & Marques      Expires January 8, 2020               [Page 61]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


3.1.2.22.  tellWeAreGrouped

   The 'tellWeAreGrouped' action is used in case a device is already is
   in state Grouped; it is used to modify KeySync state marking one is
   grouped.  This plays a role in negotiation with another device being
   Sole, such it knows it is about to join an already existing Device
   Group.

   The following code excerpt shows where this action is called:

           state Grouped timeout=off {
               on Init {
                   do newChallengeAndNegotiationBase;
                   do showBeingInGroup;
               }

               on GroupKeys
                   do saveGroupKeys;

               on KeyGen {
                   do prepareOwnKeys;
                   send GroupKeys;
               }

               on Beacon {
                   do openNegotiation;
                   do tellWeAreGrouped;
                   send NegotiationRequest;
                   do useOwnChallenge;
               }


3.1.2.23.  tellWeAreNotGrouped

   The 'tellWeAreNotGroupd' action is used by Sole Devices (thus in
   state Sole) which get into the role of being a Requester.  This
   action modifies KeySync state such as to mark one is a Sole Device
   (and not already in a Device Group).  That is, the other Sole Device
   (in Offerer role) will learn the negotiation is about to form a
   Device Group.

   The following code excerpt shows where this action is called:









Hoeneisen & Marques      Expires January 8, 2020               [Page 62]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


           state Sole timeout=off {
               on Init {
                   do newChallengeAndNegotiationBase;
                   do showBeingSole;
                   send Beacon;
               }

               on KeyGen {
                   send Beacon;
               }

               on CannotDecrypt { // cry baby
                   send Beacon;
               }

               on Beacon {
                   if sameChallenge {
                       // this is our own Beacon; ignore
                   }
                   else {
                       if weAreOfferer {
                           do useOwnChallenge;
                           send Beacon;
                       }
                       else /* we are requester */ {
                           do openNegotiation;
                           do tellWeAreNotGrouped;
                           // requester is sending NegotiationRequest
                           send NegotiationRequest;
                           do useOwnChallenge;
                       }
                   }
               }


3.1.2.24.  trustThisKey

   The 'trustThisKey' action is executed in all states a user can do
   'Accept' of the Handshake dialog.  The pEp implementer is told to put
   trust on the public key received by the other device, which wants to
   get paired.  This means, depending on the role or grouping status the
   own device is in, this key is candidate to be the new default key.
   (Note: The trust also extends to the private key part of the public
   key received at a later stage of the FSM - given the user does
   effectively 'Accept' on both devices; this trust can also be removed
   if a 'Reject' on the other device occurs, cf. Section 3.1.2.25.)

   The following code excerpt shows where this action is called:



Hoeneisen & Marques      Expires January 8, 2020               [Page 63]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


           // handshaking without existing Device group
           state HandshakingOfferer timeout=600 {

               [...]

               // Accept means init Phase1Commit
               on Accept {
                   do trustThisKey;
                   send CommitAcceptOfferer;

           [...]

           // handshaking without existing Device group
           state HandshakingRequester timeout=600 {

               [...]

               // Accept means init Phase1Commit
               on Accept {
                   do trustThisKey;
                   send CommitAcceptRequester;
                   go HandshakingPhase1Requester;
               }

           state HandshakingPhase2Offerer {

               [...]

               on Accept {
                   send CommitAcceptOfferer;
                   do trustThisKey;
                   go FormingGroupOfferer;
               }
           }

           [...]

           state HandshakingPhase2Requester {

               [...]

               on Accept {
                   send CommitAcceptRequester;
                   do trustThisKey;
                   go FormingGroupRequester;
               }
           }




Hoeneisen & Marques      Expires January 8, 2020               [Page 64]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


           [...]

           state Grouped timeout=off {

               [...]

               on GroupTrustThisKey
                   do trustThisKey;
           }

          [...]

          state HandshakingToJoin {

               [...]

               // Accept is Phase1Commit
               on Accept {
                   do trustThisKey;
                   send CommitAccept;

           [...]

           state HandshakingToJoinPhase2 {

               [...]

               on Accept {
                   do trustThisKey;
                   go JoiningGroup;
               }
           }

           [...]

           state HandshakingGrouped {

               [...]

               // Accept is Phase1Commit
               on Accept {
                   do trustThisKey;
                   send GroupTrustThisKey;
                   send CommitAcceptForGroup;
                   go HandshakingGroupedPhase1;
               }

              [...]



Hoeneisen & Marques      Expires January 8, 2020               [Page 65]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


              on GroupTrustThisKey {
                   do hideHandshakeDialog;
                   do trustThisKey;
               }

           [...]

           state HandshakingGroupedPhase1 {

               [...]

               on GroupTrustThisKey {
                   do trustThisKey;
               }

           [...]

           state HandshakingGroupedPhase2 {

               [...]

               on Accept {
                   do trustThisKey;
                   send GroupTrustThisKey;
                   do prepareOwnKeys;
                   send GroupKeys;
                   go Grouped;
               }


3.1.2.25.  untrustThisKey

   If, after an own 'Accept', the other device returns a 'Reject'
   action, trust on the other device's public key is removed.  The
   action 'untrustThisKey' ensures that the public key that has already
   been imported is untrusted (cf.  Section 3.1.2.24).  As a result, the
   public key, despite being imported, is never attached to messages
   sent to outside peers.

   The following code excerpt shows where this action is called:











Hoeneisen & Marques      Expires January 8, 2020               [Page 66]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


           state HandshakingPhase1Offerer {
               on Rollback if sameNegotiationAndPartner {
                   do untrustThisKey;
                   go Sole;
               }

               on CommitReject if sameNegotiationAndPartner {
                   do untrustThisKey;
                   do disable;
                   go End;
               }

           [...]

           state HandshakingPhase1Requester {
               on Rollback if sameNegotiationAndPartner {
                   do untrustThisKey;
                   go Sole;
               }

               on CommitReject if sameNegotiationAndPartner {
                   do untrustThisKey;
                   do disable;
                   go End;
               }


3.1.2.26.  useOwnChallenge

   [[ TODO ]]

   The following code excerpt shows where this action is called:



















Hoeneisen & Marques      Expires January 8, 2020               [Page 67]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


           state Sole timeout=off {

               [...]

               on Beacon {
                   if sameChallenge {
                       // this is our own Beacon; ignore
                   }
                   else {
                       if weAreOfferer {
                           do useOwnChallenge;
                           send Beacon;
                       }
                       else /* we are requester */ {
                           do openNegotiation;
                           do tellWeAreNotGrouped;
                           // requester is sending NegotiationRequest
                           send NegotiationRequest;
                           do useOwnChallenge;
                       }
                   }

           [...]

           state Sole timeout=off {

              [...]

               on Beacon {
                   if sameChallenge {
                       // this is our own Beacon; ignore
                   }
                   else {
                       if weAreOfferer {
                           do useOwnChallenge;
                           send Beacon;
                       }
                       else /* we are requester */ {
                           do openNegotiation;
                           do tellWeAreNotGrouped;
                           // requester is sending NegotiationRequest
                           send NegotiationRequest;
                           do useOwnChallenge;
                       }
                   }






Hoeneisen & Marques      Expires January 8, 2020               [Page 68]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


3.2.  Messages

   [[ TODO ]]

3.2.1.  Format

   [[ TODO ]]

3.2.2.  List of Messages Used in Finite-State Machine

3.2.2.1.  Beacon

   [[ TODO ]]

   Please find more information in the following code excerpt:

           message Beacon 2, type=broadcast, security=unencrypted {
               field TID challenge;
               auto Version version;
           }


3.2.2.2.  NegotiationRequest

   [[ TODO ]]

   Please find more information in the following code excerpt:

           message NegotiationRequest 3, security=untrusted {
               field TID challenge;
               auto Version version;
               field TID negotiation;
               field bool is_group;
           }


3.2.2.3.  NegotiationOpen

   [[ TODO ]]

   Please find more information in the following code excerpt:

           message NegotiationOpen 4, security=untrusted {
               auto Version version;
               field TID negotiation;
           }





Hoeneisen & Marques      Expires January 8, 2020               [Page 69]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


3.2.2.4.  Rollback

   [[ TODO ]]

   Please find more information in the following code excerpt:

           message Rollback 5, security=untrusted {
               field TID negotiation;
           }


3.2.2.5.  CommitReject

   [[ TODO ]]

   Please find more information in the following code excerpt:

           message CommitReject 6, security=untrusted {
               field TID negotiation;
           }


3.2.2.6.  CommitAcceptOfferer

   [[ TODO ]]

   Please find more information in the following code excerpt:

           message CommitAcceptOfferer 7, security=untrusted {
               field TID negotiation;
           }


3.2.2.7.  CommitAcceptRequester

   [[ TODO ]]

   Please find more information in the following code excerpt:

           message CommitAcceptRequester 8, security=untrusted {
               field TID negotiation;
           }









Hoeneisen & Marques      Expires January 8, 2020               [Page 70]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


3.2.2.8.  CommitAccept

   [[ TODO ]]

   Please find more information in the following code excerpt:

           message CommitAccept 9, security=untrusted {
               field TID negotiation;
           }


3.2.2.9.  CommitAcceptForGroup

   [[ TODO ]]

   Please find more information in the following code excerpt:

           message CommitAcceptForGroup 10, security=untrusted {
               field TID negotiation;
           }


3.2.2.10.  GroupTrustThisKey

   [[ TODO ]]

   Please find more information in the following code excerpt:

           // default: security=trusted only
           message GroupTrustThisKey 11 {
               field Hash key;
           }


3.2.2.11.  GroupKeys

   [[ TODO ]]

   Please find more information in the following code excerpt:

           // trust in future
           message GroupKeys 12, security=attach_own_keys {
               field IdentityList ownIdentities;
           }







Hoeneisen & Marques      Expires January 8, 2020               [Page 71]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


3.2.2.12.  OwnKeysOfferer

   [[ TODO ]]

   Please find more information in the following code excerpt:

           message OwnKeysOfferer 13, security=attach_own_keys {
               field IdentityList ownIdentities;
           }


3.2.2.13.  OwnKeysRequester

   [[ TODO ]]

   Please find more information in the following code excerpt:

           message OwnKeysRequester 14, security=attach_own_keys {
               field IdentityList ownIdentities;
           }


3.2.3.  Example Messages

   [[ TODO ]]

4.  Security Considerations

   [[ TODO ]]

5.  Privacy Considerations

   [[ TODO ]]

6.  IANA Considerations

   This document has no actions for IANA.

7.  Acknowledgments

   The authors would like to thank the following people who have
   provided significant contributions to actual Running Code and the
   development of this document: Volker Birk and Krista Bennett.

   Furthermore, the authors would like to thank the following people who
   provided helpful comments and suggestions for this document: Claudio
   Luck, Damian Rutz, Kelly Bristol, and Nana Karlstetter.




Hoeneisen & Marques      Expires January 8, 2020               [Page 72]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


   This work was initially created by pEp Foundation, and then reviewed
   and extended with funding by the Internet Society's Beyond the Net
   Programme on standardizing pEp.  [ISOC.bnet]

8.  References

8.1.  Normative References

   [I-D.birk-pep]
              Marques, H. and B. Hoeneisen, "pretty Easy privacy (pEp):
              Privacy by Default", draft-birk-pep-03 (work in progress),
              March 2019.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC4949]  Shirey, R., "Internet Security Glossary, Version 2",
              FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007,
              <https://www.rfc-editor.org/info/rfc4949>.

   [RFC7435]  Dukhovni, V., "Opportunistic Security: Some Protection
              Most of the Time", RFC 7435, DOI 10.17487/RFC7435,
              December 2014, <https://www.rfc-editor.org/info/rfc7435>.

8.2.  Informative References

   [I-D.birk-pep-trustwords]
              Birk, V., Marques, H., and B. Hoeneisen, "IANA
              Registration of Trustword Lists: Guide, Template and IANA
              Considerations", draft-birk-pep-trustwords-03 (work in
              progress), March 2019.

   [I-D.marques-pep-handshake]
              Marques, H. and B. Hoeneisen, "pretty Easy privacy (pEp):
              Contact and Channel Authentication through Handshake",
              draft-marques-pep-handshake-02 (work in progress), March
              2019.

   [ISOC.bnet]
              Simao, I., "Beyond the Net. 12 Innovative Projects
              Selected for Beyond the Net Funding. Implementing Privacy
              via Mass Encryption: Standardizing pretty Easy privacy's
              protocols", June 2017, <https://www.internetsociety.org/
              blog/2017/06/12-innovative-projects-selected-for-beyond-
              the-net-funding/>.




Hoeneisen & Marques      Expires January 8, 2020               [Page 73]


Internet-Draft      pretty Easy privacy (pEp) KeySync          July 2019


Appendix A.  Document Changelog

   [[ RFC Editor: This section is to be removed before publication ]]

   o  draft-hoeneisen-pep-keysync-00:

      *  Initial version

Appendix B.  Open Issues

   [[ RFC Editor: This section should be empty and is to be removed
   before publication ]]

   o  Resolve several TODOs / add missing text

Authors' Addresses

   Bernie Hoeneisen
   Ucom Standards Track Solutions GmbH
   CH-8046 Zuerich
   Switzerland

   Phone: +41 44 500 52 40
   Email: bernie@ietf.hoeneisen.ch (bernhard.hoeneisen AT ucom.ch)
   URI:   https://ucom.ch/


   Hernani Marques
   pEp Foundation
   Oberer Graben 4
   CH-8400 Winterthur
   Switzerland

   Email: hernani.marques@pep.foundation
   URI:   https://pep.foundation/
















Hoeneisen & Marques      Expires January 8, 2020               [Page 74]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/