pretty Easy privacy (pEp): Key Synchronization Protocol
draft-hoeneisen-pep-keysync-00
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Replaced".
|
|
|---|---|---|---|
| Authors | Bernie Hoeneisen , Hernâni Marques | ||
| Last updated | 2019-07-07 | ||
| Replaced by | draft-pep-keysync | ||
| RFC stream | (None) | ||
| Formats | |||
| Additional resources | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-hoeneisen-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]