add more text and structure / still contains a lot of TODO's, however it builds

master
Bernie Hoeneisen 4 years ago
parent 84472774a1
commit 354accc577
  1. 4
      pep-keysync/Makefile
  2. 422
      pep-keysync/draft-hoeneisen-pep-keysync.mkd

@ -4,6 +4,8 @@ NAME := draft-hoeneisen-pep-keysync
REV := 00
DRAFT := $(NAME)-$(REV)
OLD_NAME := draft-birk-pep-keysync
OUTPUTS = $(DRAFT).xml $(DRAFT).txt $(DRAFT).html
all: $(OUTPUTS)
@ -19,6 +21,7 @@ $(DRAFT).xml: $(NAME).mkd \
../shared/text-blocks/tofu.mkd \
../shared/text-blocks/mitm.mkd \
../shared/text-blocks/implementation-status.mkd \
# ../shared/author_tags/claudio_luck.mkd \
# ../shared/ascii-arts/basic-msg-flow.mkd \
# ../shared/ascii-arts/pep_id_system.mkd \
# ../shared/references/ed-keysync.mkd \
@ -36,5 +39,6 @@ clean:
distclean:
rm -f -r $(NAME)-* .refcache
rm -f -r $(OLD_NAME)-*
.PHONY: clean all

@ -2,7 +2,7 @@
coding: utf-8
title: "pretty Easy privacy (pEp): Key Synchronization Protocol"
abbrev: pretty Easy privacy (pEp) Key Sync
abbrev: pretty Easy privacy (pEp) KeySync
docname: draft-birk-pep-keysync-00
category: std
@ -12,13 +12,14 @@ pi: [toc, sortrefs, symrefs, comments]
author:
{::include ../shared/author_tags/bernie_hoeneisen.mkd}
{::include ../shared/author_tags/hernani_marques.mkd}
# {::include ../shared/author_tags/claudio_luck.mkd}
normative:
RFC2119:
RFC4949:
# RFC5322:
RFC7435:
# I-D.birk-pep:
I-D.birk-pep:
informative:
@ -72,9 +73,9 @@ Using encryption on multiple devices often leads to situations where
messages cannot be decrypted due to missing private key on the device
used for reading the message. Such messages have likely been
encrypted with a key that has been generated on another device
belonging to the same user. For exmample the sender encrypts with a
belonging to the same user. For example the sender encrypts with a
key that has been generated on the home laptop of the receiver and the
receiver gets the message to his mobile phone, where the corrspsonding
receiver gets the message to his mobile phone, where the corresponding
private key is not available.
## Approach
@ -107,32 +108,88 @@ not leaked or exposed to theft.
-->
# Use case
# General Description
Assuming two devices from Alice configured with pEp-implementing
messaging clients, Alice_A and Alice_B and sharing the same identity
for some communication channel (e.g., an email address). Both devices
already have a key pair, which was automatically generated by the
pEp protocol. Neither device knows anything about the other nor are
the chances realistic that the independently created key pairs match.
This section describes the general concepts of pEp KeySync, focusing
on the main procedures only. This means, the description outlines only
the successful cases, while aspects of unexpected user behavior, error
handling, race conditions and alike are skipped in this section for
the sake of a better understanding of the general concepts. Some of
these aspects will be covered more detailed in
{implementation-description}, ff..
## Use Cases
### Forming Device Group
Assuming two devices from Alice (let's call them Alice_R and Alice_O)
configured with pEp-implementing messaging clients and sharing the
same identity for some communication channel (e.g., an email
address). Both devices already have a key pair, which was
automatically generated by the pEp protocol. Neither device knows
anything about the other.
If Alice wants to communicate from both of her devices, she needs that
messages be readable across her devices. Alice may use pEp Keysync to
add her devices to a so-called Device Group (to be formed), so that
private keys can be exchanged among its members.
### Adding New Device to Existing Device Group
Alice_R and Alice_O are part of a Device Group
(cf. {forming-device-group}). In the meantime she buys another device
(let's call it Alice_J) configured with pEp-implementing messaging
clients and sharing the same identity for some communication channel
(e.g., an email address). Alice_J has a key pair, which was
automatically generated by the pEp protocol; so do the grouped devices
Alice_R and Alice_O. While the grouped devices know from each other
and even already got each others private keys, Alice_J and the grouped
devices don't know anything each other.
If Alice wants to communicate from all of her devices, she needs that
messages be readable across her devices. Alice may use pEp Keysync add
her Alice_J to the existing Device Group, so that private keys can be
exchanged among its members.
### Exchange Private Keys
All devices from Alice are part of a Device Group
(cf. {forming-device-group} and
{adding-new-device-to-existing-device-group}).However, as keys may
expire or get reset <!-- TODO: Key Reset Reference, when out --> ,
occasionally new key pairs are generated. For Alice to be able to read
all encrypted messages on all devices, any new private needs to be
sharing with the other devices in the device group.
If Alice wants to communicate from both of her devices, she expects
that messages be readable across her devices.
<!--
### Synchronizing Trust
Furthermore, while sending messages she expects the same level of
privacy she's used to as with just using one device, i.e., she wants all
of the trust she gave her contacts synchronized. That is, the trust
should be reflected on any device she uses.
-->
This requires her to have her devices be part of a so-called Device
Group.
This scenario can be fulfilled using the following steps, assuming the
process is started with device Alice_A:
\[\[Drawing here \]\]
## Interaction Diagrams
The following interaction diagrams depict the implementations of the
above Use Case in a simplified manner (as mentioned above, some
aspects are skipped for the sake of better readability):
### Forming Device Group
\[\[TODO]\]: Interaction diagrams and descriptions for the use cases above
<!--
This scenario can be fulfilled using the following steps, assuming the
process is started with device Alice_A:
1. Alice automatically invokes a broadcast from the first device, which is
connected, e.g. Alice_A: its public key is attached.
@ -161,18 +218,305 @@ some former communications with the outside world.
-->
# Sync Handshake Signals
### Adding New Device to Existing Device Group
\[\[TODO]\]: Interaction diagrams and descriptions for the use cases above
### Exchange Private Keys
\[\[TODO]\]: Interaction diagrams and descriptions for the use cases above
<!--
### Synchronizing Trust
\[\[TODO]\]: Interaction diagrams and descriptions for the use cases above
-->
## Simplified Finite State Machine
The following figures are simplified excepts of the Finite State
Machine (FSM) implementing pEp Keysync. The full pictures of the FSM
can be found here \[\[ TODO: add reference \]\]
The States and Events that fire a transition are described in
{full-finite-state-machine}.
### FSM Forming Device Group
#### Requester's Side
\[\[TODO]\]: Add simplified FSM diagram and descriptions
#### Offerer's Side
\[\[TODO]\]: Add simplified FSM diagram and descriptions
### FSM New Device to Existing Device Group
# Sync State Machine
Finite-State-Machine from reference implementation from sync/devicegroup.fsm:
#### Device Group's Side
include ./fsm.yml2
\[\[TODO]\]: Add simplified FSM diagram and descriptions
~~~~
~~~~
#### Joining Device's side
\[\[TODO]\]: Add simplified FSM diagram and descriptions
### Exchange Private Keys
As the exchange of Private Keys is rather simple to understand
(cf. {exchange-private-keys1}), no FSM is drawn here.
# Implementation Description
## Full Finite State Machine
\[\[ TODO \]\]
The full pictures of the FSM can be found here
\[\[ TODO: add reference \]\]
### States
\[\[ TODO \]\]
#### None
KeySync_state_None = None
#### Init
KeySync_state_Init = Init
#### Sole (Ungrouped)
#### HandshakingOfferer
#### HandshakingRequester
#### HandshakingPhase1Offerer
#### HandshakingPhase1Requester
#### HandshakingPhase2Offerer
#### HandshakingPhase2Requester
#### FormingGroupOfferer
#### FormingGroupRequester
#### Grouped
#### HandshakingToJoin
#### HandshakingToJoinPhase1
#### HandshakingToJoinPhase2
#### JoiningGroup
#### HandshakingGrouped
#### HandshakingGroupedPhase1
#### HandshakingGroupedPhase2
### Transitions
\[\[ TODO \]\]
### Events
\[\[ TODO \]\]
#### Events triggered by FSM
\[\[ TODO \]\]
##### Beacon
##### NegotiationRequest
##### NegotiationOpen
##### Rollback
##### CommitReject
##### CommitAcceptOfferer
##### CommitAcceptRequester
##### CommitAccept
##### CommitAcceptForGroup
##### GroupTrustThisKey
##### GroupKeys
##### OwnKeys
##### OwnKeysOfferer
##### OwnKeysRequester
#### Events Triggered by User Interaction
\[\[ TODO \]\]
##### Accept
##### Reject
##### Cancel
#### Local Events
\[\[ TODO, not sure this distinction is useful/sensible \]\]
##### KeyGen
##### CannotDecrypt
#### System Events
\[\[ TODO, not sure this distinction is useful/sensible \]\]
##### None
KeySync_event_None = None
##### Init
KeySync_event_Init = Init
##### Extra
KeySync_event_Extra = Extra
## Messages
\[\[ TODO \]\]
### Format
\[\[ TODO \]\]
### List of Messages Used in Finite State Machine
#### Version
major INTEGER (0..255) DEFAULT 1,
minor INTEGER (0..255) DEFAULT 2
#### Beacon
challenge TID,
version Version
#### NegotiationRequest
challenge TID,
version Version,
negotiation TID,
is-group BOOLEAN
#### NegotiationOpen
version Version,
negotiation TID
#### Rollback
negotiation TID
#### CommitReject
negotiation TID
#### CommitAcceptOfferer
negotiation TID
#### CommitAcceptRequester
negotiation TID
#### CommitAccept
negotiation TID
#### CommitAcceptForGroup
negotiation TID
#### GroupTrustThisKey
key Hash
#### GroupKeys
ownIdentities IdentityList
#### OwnKeys
ownIdentities IdentityList
#### OwnKeysOfferer
ownIdentities IdentityList
#### OwnKeysRequester
ownIdentities IdentityList
### Example Messages
\[\[ TODO \]\]
# Security Considerations
@ -196,7 +540,7 @@ This document has no actions for IANA.
The authors would like to thank the following people who have provided
feedback or significant contributions to the development of this
document: \[\[ TODO \]\]
document: Volker Birk \[\[ TODO \]\]
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
@ -218,7 +562,7 @@ reference implementation pEp engine (C99 programming language).
\[\[ RFC Editor: This section is to be removed before publication \]\]
* draft-birk-pep-keysync-00:
* draft-hoeneisen-pep-keysync-00:
* Initial version
@ -227,20 +571,24 @@ reference implementation pEp engine (C99 programming language).
\[\[ RFC Editor: This section should be empty and is to be removed
before publication \]\]
* Include shared file (cf. other drafts)
* resolve TODO's
* Major update
* Add reference (section?) to sync code
* Verify Dummy Sections
* Implementation Status
* Acknowledgements
* Excerpts from the pEp Reference Implementation
* Open Issues
* Remove unused references
* Remove unused Terms
* Check List of Authors
<!--
* shorten overlong lines in code examples
LocalWords: utf docname toc sortrefs symrefs KeySync Offerer's Init
LocalWords: Ungrouped HandshakingOfferer HandshakingRequester KeyGen
LocalWords: HandshakingPhase Offerer FormingGroupOfferer GroupKeys
LocalWords: FormingGroupRequester HandshakingToJoin JoiningGroup TID
LocalWords: HandshakingToJoinPhase HandshakingGrouped CommitReject
LocalWords: HandshakingGroupedPhase NegotiationRequest CommitAccept
LocalWords: NegotiationOpen CommitAcceptOfferer CommitAcceptForGroup
LocalWords: CommitAcceptRequester GroupTrustThisKey OwnKeys ISOC
LocalWords: OwnKeysOfferer OwnKeysRequester CannotDecrypt bnet
LocalWords: ownIdentities IdentityList Changelog hoeneisen
-->
Loading…
Cancel
Save