Network Working Group B. Hoeneisen
Internet-Draft pEp Foundation
Intended status: Standards Track 16 December 2022
Expires: 19 June 2023
pretty Easy privacy (pEp): Key Reset
draft-pep-keyreset-00
Abstract
The pretty Easy privacy (pEp) model and protocols describe a set of
conventions for the automation of operations traditionally seen as
barriers to the use and deployment of secure, privacy-preserving end-
to-end messaging. These include, but are not limited to, key
management, key discovery, and private key handling (including peer-
to-peer synchronization of private keys and other user data across
devices).
This document specifies the pEp KeyReset protocol that allows
applications to provide simple high-level functionality to users
needing to perform some of the aforementioned functions while still
ensuring that the appropriate low-level changes in keyrings and trust
management are handled consistently, and that communication of these
changes to active partners (where necessary) happens seamlessly,
without explicit action on the part of the user.
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 19 June 2023.
Copyright Notice
Copyright (c) 2022 IETF Trust and the persons identified as the
document authors. All rights reserved.
Hoeneisen Expires 19 June 2023 [Page 1]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
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 Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Relationship to Other pEp Documents . . . . . . . . . . . 3
1.2. Requirements Language . . . . . . . . . . . . . . . . . . 4
1.3. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.4. Problem Statement . . . . . . . . . . . . . . . . . . . . 6
1.4.1. Context: pEp, Default Keys, and Trust . . . . . . . . 6
1.4.2. Problem Summary . . . . . . . . . . . . . . . . . . . 7
1.5. Background . . . . . . . . . . . . . . . . . . . . . . . 8
1.6. Use Cases and Requirements . . . . . . . . . . . . . . . 9
1.6.1. Overall Requirements . . . . . . . . . . . . . . . . 9
1.6.2. Example 1: Own Single Key Replacement with New Key . 9
1.6.3. Example 2: Device Compromise - Simple Case (Single
Device) . . . . . . . . . . . . . . . . . . . . . . . 10
1.6.4. Example 3: Encryption to a Revoked pEp Partner Key . 11
1.6.5. Example 4: Manually Changing Use of Incorrect Partner
Key . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.6.6. Example 5: Removing Trust or Mistrust from
Communications Partner Key . . . . . . . . . . . . . 12
1.6.7. Example 6: KeySync: Reset Own Keys . . . . . . . . . 13
2. Implementation . . . . . . . . . . . . . . . . . . . . . . . 14
2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 14
2.2. Functions . . . . . . . . . . . . . . . . . . . . . . . . 15
2.2.1. Sending Side . . . . . . . . . . . . . . . . . . . . 15
2.2.2. Receiving Side . . . . . . . . . . . . . . . . . . . 17
2.2.3. DDL Impacts . . . . . . . . . . . . . . . . . . . . . 18
2.3. Protocol Descriptions with Examples . . . . . . . . . . . 19
2.3.1. Example 1: Own Single Key Replacement with New Key . 19
2.3.2. Example 2: Device Compromise - Simple Case (Single
Device) . . . . . . . . . . . . . . . . . . . . . . . 20
2.3.3. Example 3: Encryption to Revoked pEp Partner Key . . 20
2.3.4. Example 4: Manually Changing Use of Incorrect Partner
Key . . . . . . . . . . . . . . . . . . . . . . . . . 21
3. Security Considerations . . . . . . . . . . . . . . . . . . . 23
4. Privacy Considerations . . . . . . . . . . . . . . . . . . . 24
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 25
Hoeneisen Expires 19 June 2023 [Page 2]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
7.1. Normative References . . . . . . . . . . . . . . . . . . 25
7.2. Informative References . . . . . . . . . . . . . . . . . 25
Appendix A. Document Changelog . . . . . . . . . . . . . . . . . 26
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 26
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 26
1. Introduction
The pretty Easy privacy (pEp) [I-D.pep-general] 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.
pEp is an an encryption product which automates as much of the key
management and trust process as possible. As a result, one of its
greatest challenges is that when there are key related issues - e.g.,
compromise, revocation, or simply need to use a different Default Key
for a partner - the software must be able to provide both internal
and user access to the ability to change these Default Keys without
actually exposing the concept of keys, which goes against pEp's
"Pretty Easy" principle, or the details of trust management.
This document specifies the pEp KeyReset protocol that allows
applications to provide simple high-level functionality to users
needing to perform some of the aforementioned functions while still
ensuring that the appropriate low-level changes in keyrings and trust
management are handled consistently, and that communication of these
changes to active partners (where necessary) happens seamlessly,
without explicit action on the part of the user. Additionally, the
protocol provides important lower-level internal functionality to
other internal protocols (e.g., KeySync [I-D.pep-keysync]).
1.1. Relationship to Other pEp Documents
While this document provides a general description of pEp KeyReset,
including use cases, diagrams, and examples of messages that may be
generated during the KeyReset process, other related documents
specialize in more particular aspects of the model, or the
application of pEp on a specific protocol like as follows:
1. General description and functionalities of pep (cf. pEp General
[I-D.pep-general]).
2. pEp-enabled applications (e.g., pEp email [I-D.pep-email]).
Hoeneisen Expires 19 June 2023 [Page 3]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
3. Helper functions for peer interaction, which facilitate
understanding and handling of the cryptographic aspects of pEp
implementation for users (e.g., pEp Handshake
[I-D.pep-handshake]).
4. Helper functions for interactions between a user's own devices,
which give the user the ability to run pEp applications on
different devices at the same time, such as a computer, mobile
phone, or tablets (e.g., pEp KeySync [I-D.pep-keysync]).
In addition, there are documents that do not directly depend on this
one, but provide generic functions needed in pEp, e.g., IANA
Registration of Trustword Lists [I-D.pep-trustwords].
[[ Note: At this stage it is not yet clear to us how many of our
implementation details should be part of new RFCs and where we can
safely refer to already existing RFCs to clarify which RFCs we rely
on. ]]
1.2. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
1.3. Terms
The following terms are defined for the scope of this document:
* pEp Handshake: The process of one user contacting another over an
independent channel in order to verify Trustwords (or fingerprints
as a fallback). This can be done in-person or through established
verbal communication channels, like a phone call.
[I-D.pep-handshake]
* Trustwords: A scalar-to-word representation of 16-bit numbers (0
to 65535) to natural language words. Trustwords are generated
from the combined public key fingerprints of a both communication
partners. Trustwords are used for verification and establishment
of trust (for the respective keys and communication partners).
[I-D.pep-trustwords]
* 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 Expires 19 June 2023 [Page 4]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
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."
* 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."
Note: Historically, MITM has stood for '_Man_-in-the-middle'.
However, to indicate that the entity in the middle is not always a
human attacker, MITM can also stand for 'Machine-in-the-middle' or
'Meddler-in-the-middle'.
* User: An individual entity using pEp. A User may have one or more
Identities.
* User-ID: A unique identifier for a given User.
* Own User: The pEp user that is controlling the local client in
question.
* Address: An address in pEp means the designator of a destination
where messages can be routed to and accessed from, e.g., email
address, Uniform Resource Identifier (URI), Network Access
Identifier (NAI), phone number, etc. An address may belong to one
or more users. A user may have multiple Addresses.
* Identity: A binding between a user (unique User-ID) and an Address
(email, network ID, URI, etc.). Each Identity is uniquely
identified by this binding. Identities contain a number of
different pieces of information, often including, but not limited
to:
- User-ID
- Address
- Default Key
- Username
- Preferred encryption format
- Information about whether this is an Own Identity
- ...
Hoeneisen Expires 19 June 2023 [Page 5]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
A single user may have multiple identities. See also [RFC4949].
* Own Identity: An Identity corresponding to one of the Own User's
Addresses.
* KeySync: A synchronisation protocol for sharing and maintaining
private keys across a user's pEp installations (cf.
[I-D.pep-keysync]).
* Device Group: A set of devices controlled by one pEp User that
have successfully completed the KeySync setup process and
synchronize Indentiy information, such as cryptographic keys.
This data is synchronized through a common channel for a given
Identity. For example, if a user's Identity is tied to a specific
email address, the common channel for this Identity could be an
inbox.
* Default Key: The Identity's or user's key that is marked as the
key to be used to encrypt to (in the case of communications
partners) or to sign with (in the case of the Own User).
* Own Key: A public/private keypair corresponding to a user's Own
Identity.
1.4. Problem Statement
1.4.1. Context: pEp, Default Keys, and Trust
pEp has, for every Identity (where possible), a Default Key used for
encryption and signing of messages (or their verification/
decryption).
For the individual pEp User and corresponding Address, their Own
Default Key is the key they use to sign messages to others, to
decrypt messages from communications partners, and to encrypt
messages to themselves.
Additionally, however, for every Identity that this User communicates
with, there is (where available) a Default Key belonging to the
communications partner which is used to encrypt messages to that
Identity and to verify messages signed by that Identity.
A User may have several Identities, and each of those Identities may
have a distinct Default Key.
These defaults generally stay stable unless a key becomes invalid or
unusable. However, there are times when a User or an internal
protocol needs to reset these defaults and replace them with new
Hoeneisen Expires 19 June 2023 [Page 6]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
ones. Additionally, when a User begins using a new Default Key, they
may need to communicate this change of desired defaults to
communications partners. Or an automated internal protocol may, for
example, have a reason to invalidate one or more of a User's Own
Keys.
Within the pEp environment, there are several circumstances under
which we might need to reset the Default Key that pEp would
ordinarily use as the Default Key either for the User themselves to
sign messages and data, or for a communications partner in order to
encrypt it. A User may need to revoke one or more of their Own Keys
due to compromise or accidental creation of a new key. And
internally, there are protocols, such as KeySync (cf.
[I-D.pep-keysync]), which, as part of automated key management, may
need to securely force removal and regeneration of Default Keys
across devices.
And finally, pEp allows Users to assign trust (through the exchange
of Trustwords) or mistrust to a key associated with an Identity, and
sometimes Users desire that these values are reset, either due to
error or a change in their own perception of trust. A mechanism
needs to be available to reset this information about keys as well.
1.4.2. Problem Summary
The largest part of the problem comes in two parts:
1. Users who have had their devices/systems compromised need a fast
and easy way to ensure that their Own Default Keys are revoked
and replaced, that these changes are communicated to partners as
seamlessly as possible, and that their partners are able to start
using the correct key with little or no interaction.
2. In the case that a partner is using a key which is either not the
User's real key or is a key that the User no longer has access
to, there needs to be a way for that User to contact the partner
on a second channel to tell them to stop using that key for their
Address.
Because we want to abstract the idea of keys away from the User,
having them only focus on their contacts and the expression of trust
with these contacts as applied to the sending and receipt of
messages, pEp must provide a way for apps to create this abstraction
without needing to retain information about specific keys, especially
since we want to avoid Users interacting with the idea of keys at all
costs.
Hoeneisen Expires 19 June 2023 [Page 7]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
Thus, we need a way for implementations to provide this functionality
for both (1) the reset of Own Keys belonging to an Own Identity, and
(2) such a reset for partner keys belonging to a partner Identity
which does not require any information about keys from the
application or external protocol layer, while still ensuring that the
appropriate low-level (keyring and management database) actions can
occur appropriately.
We also need to be able to ensure that the partners regularly
contacted by a User who has reset their Own Key(s) can be notified
and informed that they should use the new key (and stop using the old
one) corresponding to the specific User Address they have been
communicating with without the need for the User to inform partners
explicitly while still ensuring some verification that this
information actually came from the User.
The KeyReset protocol aims to solve this problem of providing an
abstraction to the application layer as well as providing both
opportunistic and situation-based automated communication of changes
to partners without compromising the trust system and minimizing man-
in-the-middle attacks. This can be achieved, e.g., by providing API
functions which operate at both the User and Identity levels for both
Own Users and partners. Implementations ensure mapping of Identity
information to keys, all necessary key manipulation and management
database functions as well as automation of the partner-notification
process.
1.5. Background
Early implementations of pEp lacked an easy means for high-level Key
revocation of Own Keys, for partners to stop using a key at the
request of the User, and for notification of Default Key changes
through revocation to communications partners. This made it very
difficult to clear Default Key data when desired without forcing
applications to keep track of Default Key information, and without
having partners continue encrypting messages to the older Default
Key. There was no means for applications to simply tell, "please
reset all key data for this Identity", or to automatically tell
partners they were using a revoked key and to start using a new one.
KeyReset provides this functionality, which can be used both by
applications and by internal protocols to provide these functions
under a variety of circumstances.
Hoeneisen Expires 19 June 2023 [Page 8]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
1.6. Use Cases and Requirements
This section uses key use cases to create a list of requirements the
KeyReset protocol must fulfill. This is central to designing a
solution.
Note: The requirements are labeled with the letter 'R' followed by a
consecutive number, e.g., R7.
1.6.1. Overall Requirements
One preexisting requirement that impacts all of the examples is this,
and is driven by one of the principles of the system, which is that
Users should neither need to know or care about the concept of
"keys":
R1: Default Key removal and/or replacements MUST be possible from
the application or external protocol level without the application
or external protocol having to have knowledge of the specific
Default Key, only the Identity or User. Implementations use this
information to determine which keys to reset.
1.6.2. Example 1: Own Single Key Replacement with New Key
A pEp User decides, for any reason, that they want to replace their
current Default Key for one of their Identities. The key MUST NOT be
used by communication partners in the future. The goal is to ensure
the old key is invalid for future use by communications partners or
adversaries.
This creates the following additional requirements (in addition to R1
above):
R2: The protocol MUST provide a mechanism at the cryptographic level
(e.g., within the keyring) for the revocation of the Own Default
Key associated with this Identity.
R3: The protocol MUST provide a mechanism for the generation of a
new key pair corresponding to this Identity and to assign this key
as the Identity default.
R4: If the key being replaced was also the User's Default Key, the
new key generated by R3 above MUST replace the first key in the
management database as the User Default Key.
R5: Communications partners MUST be informed, at the latest at the
first reply to a message encrypted to the now-revoked key, of the
revocation of the first key and its replacement with the second.
Hoeneisen Expires 19 June 2023 [Page 9]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
R6: The notification in R5 MUST include communication of both the
revocation in R2 via a revocation certificate (signed by the now-
revoked key) and the public part of the new key pair.
R7: The notification in R5 MUST, at the very least, contain some
artifact that requires the private key of the now-revoked key to
produce (e.g., a revocation certificate).
R8: The notification in R5 MUST, at a minimum, be signed with the
private key of the new key pair.
1.6.3. Example 2: Device Compromise - Simple Case (Single Device)
A pEp User is forced to unlock and give up their phone at the border.
(The "device compromise" use case can happen in other ways, but we
want to initially provide the simplest case, where the User recovers
the same device after compromise. Dealing with device compromise
from another device is handled later). They want to ensure that the
keys on that phone are no longer valid for use in order to prevent
unauthorized parties from decrypting their future communications or
posing as an imposter, sending mails which can be falsely "verified"
as them.
This creates the following requirements:
R9: Expanding on R2 above, the protocol MUST provide a mechanism for
the revocation of all Own Keys at the cryptographic engine level
(i.e. within the keyring) associated with:
1. the User, and
2. all of the User's Identities
R10: Expanding on R3 above, the protocol MUST provide a mechanism
for the generation of new keys corresponding to each impacted
Identity and to assign them as new Default Keys for that
corresponding Identity.
R11: The User Default Key MUST be replaced with one of the new
Default Keys of the impacted Identities.
R12: For each newly-revoked key, communications partners MUST be
informed from the corresponding Identity they have corresponded
with of the revocation of the first key and replacement of the
second according to R5-R8.
Hoeneisen Expires 19 June 2023 [Page 10]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
1.6.4. Example 3: Encryption to a Revoked pEp Partner Key
A pEp User, Alice, has the public key of another pEp User, Bob. Bob
has done a KeyReset of his Own Key, but Alice is not among the people
he has yet notified of this change. Because Alice does not know that
Bob has a new key, the public key she uses to encrypt to him
corresponds to a key he has already revoked and does not want others
to use. While the initial encryption to Bob using this key cannot be
stopped, as Alice is unaware of its invalidity, Bob needs to be
certain that on the next round of communication originating from
Alice, she uses the correct new key to encrypt to him, replacing the
older key as its default in the corresponding Bob Identity in her
database.
That said, if Alice and Bob have exchanged Trustwords and Bob's old
key was trusted (creating a "green" channel in the parlance of the
applications), Bob's new key should not retain this trust; rather,
Alice and Bob should have to exchange Trustwords again to establish
trust for this particular new key, while still maintaining other
communications channel information, such as whether or not Bob is a
pEp User.
This creates the following additional requirements:
R13: The protocol MUST detect when a message has been sent to an Own
Key that is revoked
R14: If such a message was sent by a pEp User, then the protocol
MUST, as a response, generate and send a notification to the
relevant partner as specified in R5-R8.
The pEp communications partner must have the means to process and
validate such a notification. This creates the following relevant
requirements:
R15: The protocol MUST provide the means for processing and
validating notifications as specified in R5-R8. This requires
R16-R21:
R16: The protocol MUST verify that the notification contains at
least one artifact signed by the now-revoked previous key.
R17: The protocol MUST process the revocation certificate of the
sender, recording the revocation with the cryptographic engine and
mistrusting the revoked key in the management database. This
certificate fulfills the requirements R5-R8 above.
R18: The protocol MUST verify that this revoked key corresponds to
Hoeneisen Expires 19 June 2023 [Page 11]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
the extant Default Key of the User.
R19: The protocol MUST verify that the replacement key is attached
to the message and corresponds to the key information given in the
received KeyReset message.
R20: The protocol MUST set the received key as the Default Key for
the communications partner.
R21: The protocol MUST ensure that any trusted status gained by the
previous exchange of Trustwords with the sending partner is
removed; trusted status can only be set with the new key upon a
new exchange of Trustwords.
1.6.5. Example 4: Manually Changing Use of Incorrect Partner Key
A pEp User has a key set as default for a communications partner that
this partner does not want used for communication for a particular
Address (and, thus, in pEp terms, a particular Identity). However,
that partner is not using, and may not have access to, the KeyReset
mechanism for that key. This could happen if the partner is an
OpenPGP partner, if the partner only had their private key on one
device which is now inaccessible to them, or if the partner does not
intend to revoke that key, they simply do not want it used for the
Address associated with the Identity in question.
pEp needs to provide a mechanism for the User to manually indicate
that this key should not be used as the default.
This creates the following requirement:
R22: The protocol MUST provide a means for the User to manually
remove the Default Key for a partner Identity.
(Note that if there is a compromise indicated, the pEp protocol
itself provides the means for Users to mistrust keys of their
contacts, and that this is not an explicit part of manual KeyReset of
partner keys.)
1.6.6. Example 5: Removing Trust or Mistrust from Communications
Partner Key
A pEp User may have exchanged Trustwords with a partner and
accidentally or intentionally confirmed them and want to rescind that
decision. Alternately, a pEp User may have mistrusted a partner key
and want to rescind that decision.
These two possibilities imply the following requirements:
Hoeneisen Expires 19 June 2023 [Page 12]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
R23: The protocol MUST provide a means for Users to reset trusted or
mistrusted status for Default communications partner Keys.
1.6.7. Example 6: KeySync: Reset Own Keys
Note that this example requires understanding of the KeySync protocol
(cf. [I-D.pep-keysync]), which is out of scope for this document.
Minimal key terms are defined in the glossary above.
KeySync is a protocol which allows several of a User's different
devices running pEp to synchronize and use the same private keys for
synchronized Own Identities. This group of devices is called a
Device Group.
A User may decide to reset one or more keys associated with
Identities marked for synchronization. The request for reset is done
on a single device, but must be propagated to the other devices.
Because this is an automated reset of Own private Keys initiated
externally for the other devices, it has some additional special
requirements for security reasons, in addition to R9-R12:
R24: The protocol MUST provide the means for notifying own devices
of the reset of shared keys
R25: The protocol MUST provide the means for the initiating device
to communicate KeyReset information in a message signed by one of
the keys to be reset, which will still be valid from the recipient
device point of view upon receipt
R26: The protocol MUST provide the means for the initiating device
to fulfill R9-R12, while still fulfilling R25.
R27: The protocol MUST provide the means for communicating the
following additional KeyReset information to non-initiating
devices within the Device Group:
1. Identities impacted
2. New public/private key material for the respective replacement
Default Keys and their binding
3. Mapping of old Defaults Keys to new keys
R28: The protocol MUST provide the means for receipt and
verification of this reset communication by non-initiating devices
in the Device Group, including ensuring signature by an Own,
extant Key from one the synchronized Identities in the Device
Group.
Hoeneisen Expires 19 June 2023 [Page 13]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
R29: The protocol MUST provide the means for the import and setting
of these replacement keys according to their respective,
Identities, along with local revocation of the Default Keys being
replaced, according to R2 and R4 for each respective Identity, as
well as enabling communications corresponding to R5-R8 when in
receipt of messages to a revoked key.
R30: If initial opportunistic notification of recent contact
partners is desired as part of the implementation, then the
initiating device MUST perform the unsolicited notification to
contact partners according to R12.
2. Implementation
2.1. Overview
Note: In the following the term "application" refers to the part of
the implementation that directly interacts with the User. The
"application" may be integrated in a whole implementation or be in a
separate code base that interacts e.g., with an underlying library or
"engine". In the former case the term "application" refers to the
code parts that directly interact with the User.
This specification defines the functions addressing the requirements
above. It also includes high-level APIs. The KeyReset protocol is
divided into sender and receiver functions. A KeyReset function
affects either all of a User's Default Keys in the database or only
the Default Key associated with a specific Identity. These functions
are further subdivided into those (in addition to local processing)
also affecting peers (communication partners) and those affecting
other devices of the same User (KeySync, cf. [I-D.pep-keysync]).
These functions are opaque to the upper layers; any necessary
communications MUST be dropped into the applications message queue
directly by the protocol, and all underlying database manipulation,
key generation, etc. MUST be performed without further interaction
with the application.
The implementation MUST evaluate the input Identity (or Identities,
if only the User is specified), determine whether it is an Own
Identity or a partner Identity, and process the reset appropriately
according to the requirements. This includes management database
manipulation, Default Key setting, and (where appropriate) key
revocation, key generation, as well as sending of any initial
KeyReset notification messages.
Hoeneisen Expires 19 June 2023 [Page 14]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
On receiving KeyReset messages, the implementation MUST process the
KeyReset messages - both from partner Identities and from Own
Identities - and interact with them in accordance with the
requirements above.
Implementations MAY also provide a mechanism for opportunistic
notification of recently contacted partners (where "recently
contacted" indicates contacts originating from the User, i.e. not
received communications) at the time an Own Key Reset is made. Such
a mechanism can speed up the process of appropriate key usage by
frequent communications partners, as there is no delay until the
first message encrypted with a revoked key is received and replied
to.
2.2. Functions
2.2.1. Sending Side
2.2.1.1. Key Reset Identity
key_reset_identity(pEp_SESSION session, pEp_identity* ident, const
char* fpr)
This function resets the default management database status for the
Identity / key pair provided: The key identified by fpr MUST be
removed as a Default Key for this identity and any trusted or
mistrusted status MUST be removed from the trust database for this
key and this Identity's User. If the Identity provided corresponds
to an Own Identity and a private key, this key MUST be revoked, a new
key MUST be generated, and the reset MUST be communicated to recently
contacted pEp partners for this Identity.
If fpr is empty, then whatever key is set as the default for this
Identity MUST be treated as above. Note that if the KeyReset by this
function is the default for any other User or Identity, it MUST be
unset as the default for that Identity.
2.2.1.2. Key Reset User
key_reset_user(pEp_SESSION session, const char* user_id, const
char* fpr)
This function effectively applies the function key_reset_identity()
(cf. Section 2.2.1.1) to a series of Identities corresponding to the
User (as indicated by user_id), as follows:
1. If the User is a communications partner (not the Own User):
Hoeneisen Expires 19 June 2023 [Page 15]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
1. If the key identified by fpr is present, key_reset_identity()
(cf. Section 2.2.1.1) MUST be applied for each of the
partner's Identities containing fpr as the Default Key.
2. Otherwise, a key_reset_identity() (cf. Section 2.2.1.1) MUST
be performed on ALL of the partner's Identities corresponding
to their user_id (with an empty fpr as defined in
Section 2.2.1.1).
2. If the user_id indicates the Own User:
3. If the key identified by fpr is present, key_reset_identity()
(cf. Section 2.2.1.1) MUST be applied for each of the partner's
Identities containing fpr as the Default Key. Note: The
functionality is the same with the communications partner case
(see above).
4. Otherwise the function key_reset_all_own_keys() (cf.
Section 2.2.1.3) MUST be executed.
Note: key_reset_identity() (cf. Section 2.2.1.1) and
key_reset_all_own_keys() (cf. Section 2.2.1.3) MUST also unset as
default every key which is reset, for all Users and Identities.
2.2.1.3. Key Reset All Own Keys
key_reset_all_own_keys(pEp_SESSION session)
This function MUST revoke and mistrust all Own Keys, generate new
keys for all Own Identities, and MAY opportunistically communicate
KeyReset information to people we have recently contacted. This
function effectively performs the work of key_reset_identity() (cf.
Section 2.2.1.1) for every Own Identity and Own Default Key.
Note that if any Identities share one of these Own Keys as their
Default Key, they will each have different (separate) new Default
Keys after completion.
2.2.1.4. Key Reset Own Grouped Keys
key_reset_own_grouped_keys(pEp_SESSION session)
This function is, on the surface, like key_reset_all_own_keys() (cf.
Section 2.2.1.3), however it MUST be applied to (and only to) the
Default Keys for Identities that are marked for synchronization as
part of a KeySync (cf. [I-D.pep-keysync]) Device Group.
Furthermore, because of the fact that these are synchronized
Identities, this function performs some additional work.
Hoeneisen Expires 19 June 2023 [Page 16]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
In addition to what is defined in key_reset_all_own_keys() (cf.
Section 2.2.1.3), this function MUST create a special KeyReset
message to be used internally in order to communicate to each grouped
device the following information:
1. The Identity whose Default Key is to be revoked
2. The Default Key for each corresponding Identity to revoke
3. The new Default Key which will replace each Default Key (for each
corresponding Identity)
4. The public/private key pair for each corresponding replacement
key
This whole message MUST be encrypted to and, more importantly, signed
by one of the device group's current valid keys at the time the reset
function is called. This function MUST first produce and sign this
KeyReset message, and then perform (on the caller device) the
revocation functionality associated with KeyReset of Own Keys and
replace them with the new defaults it generated and sent.
The device on which this function is called is the sole device
responsible for communicating any opportunistic KeyReset messages to
partners as described in the requirements section above.
2.2.2. Receiving Side
2.2.2.1. Processing Received key_reset_identity() and key_reset_user()
Messages
Practically speaking, from the receiver point of view, this will only
involve individual messages issued by function key_reset_identity()
(cf. Section 2.2.1.1).
For any given message, the recipient MUST verify that:
1. there is an extant matching Identity,
2. they have the key being reset in their keyring,
3. if the key is present, that they have imported a revocation
(which implies an object signed by the known private key of the
sender)
4. that the public part of the replacement key indicated in the
KeyReset message is attached and imported
Hoeneisen Expires 19 June 2023 [Page 17]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
If all of these conditions are true, the recipient MUST replace the
new key as the default for this Identity in their database and
mistrust the revoked key.
Note that if the reset key is not the Default Key for this Identity,
the database will not change, but the revocation certificate will be
imported as well as the new key. This means that if another Identity
contains the to-be-replaced key as a Default Key, it will not be
valid; however, it will not be unset as the Default Key for that
Identity until the engine tries to use it, and it will not be
replaced by the newly-sent key unless a specific KeyReset message is
received for that Identity indicating it should do so.
2.2.2.2. Processing Received key_reset_own_grouped_keys() Messages
Processing received key_reset_own_grouped_keys() (cf.
Section 2.2.1.4) messages is perhaps the most security-critical part
of the protocol from the User's perspective, as it is processed
automatically, it changes the User's Default private Keys, and it
revokes their extant private keys.
When receiving a key_reset_own_grouped_keys() (cf. Section 2.2.1.4)
message, the implementation MUST verify that the key used to sign the
message corresponds to the Default Own Identity it was sent from,
that the corresponding key is still valid, and that it contains a
private key. Note that because key_reset_own_grouped_keys() (cf.
Section 2.2.1.4) does not send revocation certificates, but rather
references to these keys to devices in the Device Group indicating
which keys to replace and revoke locally, this key will still be
valid if it is an actionable and correct own grouped KeyReset
message.
Should this be the case, for every transmitted Identity and
replacement key pair, the recipient device MUST revoke the old key
for that Identity and replace it with the indicated new key (instead
of generating a new key). Recipient devices MUST not send out
KeyReset notifications to partners, as this is handled by the device
that generated the reset message.
These new keys MUST then be trusted as new keys and operation can
continue as normal.
2.2.3. DDL Impacts
Implementation requires the following features, many of which were
present before KeyReset was implemented:
Hoeneisen Expires 19 June 2023 [Page 18]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
1. A social_graph table, binding partner Identities with the
addresses the User has contacted them from. This is to avoid
exposing Own User aliases to the partner when sending KeyReset
messages and ensures there is a match between the Address the
reset is for and the Identity the partner associates with the key
to be reset on the recipient end. Note that only Identities the
User as proactively contacted themselves are contained in this
table, an important note for 2).
2. Timestamps on Identities indicating recent access or update.
This is used to filter which partners to opportunistically
contact. Note that only Identities which the User has
intentionally communicated with (rather than just receiving a
message from) will be sent these opportunistic messages; this is
to prevent spammers from receiving KeyReset messages.
Other tables and fields (e.g., main_key_fpr for Identity Default
Keys, etc) are already integral to the system and are used here, but
their DDL semantics remain unaltered.
2.3. Protocol Descriptions with Examples
In this section, we take the indicated use cases from the
requirements section and show how the protocol operates.
2.3.1. Example 1: Own Single Key Replacement with New Key
Recall that the pEp User, in this example, wants to replace one
Default Key from one Identity.
The application must provide a way for the user to select the
Identity (presumably by Address) they wish to reset. Since the
application does not keep track of the Default Key for that Address,
but does have a constant representation of the own user_id, it will
call key_reset_identity with the session argument, the appropriate
Own Identity, and an empty fpr.
The implementation then:
1. retrieves the Own Identity, including the Default Key
fingerprint, and
2. if it is not already revoked and contains a private key:
1. tells the cryptographic engine to revoke the private key,
2. asks the cryptographic engine to generate a new public/
private key pair,
Hoeneisen Expires 19 June 2023 [Page 19]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
3. records the binding of the revoked key and its replacement
in the key management database,
4. sets the new key as the Identity default,
5. replaces the User Default Key with the new one if the
Identity Default Key and the User Default Key were the same,
6. mistrusts the old key in the management database,
7. repeats ii-vi for any other Own Identity for which this key
was the default,
8. searches the Identity database for any Identities in the
social graph which have been actively contacted by this
Identity and whose Identities have been updated in the last
two weeks,
9. generates KeyReset messages as described in requirements
R5-R8 for each of those Identities from the reset Identity,
and
10. places those messages into the application message queue,
which is sent in at session initialization (if there is no
message queue present, no messages are sent).
2.3.2. Example 2: Device Compromise - Simple Case (Single Device)
This example featured a pEp User which wanted to reset all of their
Own Keys on their single, ungrouped device and wished to invalidate
their keys for future use.
In this case, the application provides a mechanism for the User to
simply reset all Own Keys. This will call key_reset_all_own_keys()
with the current session as the argument.
The engine will then use its knowledge of its own user_id to fetch
all Own Identities, and then, for each Own Identity, proceed as in
step 2 of Example 1 above.
2.3.3. Example 3: Encryption to Revoked pEp Partner Key
In this example, a pEp User, Alice, only has an outdated key from her
pEp communications partner, Bob. Bob has revoked the key, but Alice
is unaware of it, and so sends Bob a message encrypted to the key he
has revoked.
Hoeneisen Expires 19 June 2023 [Page 20]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
Bob, who still has the revoked key in his keyring and can decrypt
with it, decrypts and verifies Alice's message as usual. However, in
decrypt_message(), the engine notes that Alice is using one of Bob's
revoked, mistrusted keys.
The engine looks up the revoked key in the database. If its
replacement key is his current default, it creates a KeyReset message
for Alice containing the revocation certificate of the old key (this
can be done by just sending the revoked key, which contains the
revocation certificate), his new key along with the specified
KeyReset information.
If, however, the engine notes that the key that replaced his revoked
key is also revoked, it follows the chain of replacements until it
finds the current valid Default Key and uses this in the KeyReset
message.
Alice then receives Bob's message. On decrypting his message, the
engine will import both the new key and the revocation certificate.
On processing the KeyReset message, the engine will, if it notes that
the old key is now revoked in her keyring and the message is signed
by the new key, mistrust Bob's old Default Key and replace the
Default Key for Bob's respective Identity with the new key; however,
no trust status will carry over to the new key.
If Alice wishes to trust Bob's new key, she will contact Bob on a
side channel and exchange Trustwords for their combined public keys
and set the trust for the new key pair if she can verify them.
2.3.4. Example 4: Manually Changing Use of Incorrect Partner Key
There are two likely scenarios which generate this use case: Bob is
an OpenPGP user with several keys, and Alice's pEp installation has
chosen to make the wrong one the default, or perhaps Bob is a pEp
User who has reinstalled his client several times without resetting
keys, and thus has partners who have an unusable (for Bob) public key
for him.
In either event, Bob contacts Alice and says, "Hey, I need you to
stop using that public key" in the first case, or in the second,
"Hey, I can't decrypt the messages you sent me."
Hoeneisen Expires 19 June 2023 [Page 21]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
In both cases, the application provides the means for Alice to either
reset an Identity or reset the User (note that in engine parlance
this is resetting the key of the Identity or User, but the
application does not keep track of keys). Presuming the application
allows resets at the Identity level of granularity (e.g., contact
address rather than contact), it will call key_reset_identity() with
Bob's Identity and an empty fpr.
The engine will then see that this is a partner Identity and remove
the current Default Key as the default as well as resetting its trust
status in the database. This will leave an empty default.
If, on the other hand, only the User (e.g., the User's keys) is
available as a reset option in the application UI, the application
will call key_reset_user with Bob's user_id and an empty fpr. This
will repeat the process above for individual Identities for each of
Bob's known Identities.
Bob should then mail Alice again. If he is mailing from a pEp
client, he will automatically attach his new key and it should be
selected as the default on receipt. If it was a full User reset, he
will at some point need to mail from all impacted accounts in order
to ensure Alice has keys for each. If Alice and Bob wish to trust
these keys, they must exchange Trustwords (possibly again) for each
impacted Identity.
If Bob is mailing from an OpenPGP client, he should simply attach his
key to a message and mail Alice at his earliest convenience.
2.3.4.1. Example 5: Removing Trust or Mistrust From Communications
Partner Key
Recall that this involves a User wanting to reset the trusted or
mistrusted status of a communications partner Identity.
The application must provide the means for the User to select an
Identity whose trust should be reset. This functionality should call
key_reset_identity() or key_reset_user() as in example 4 and will
take the same steps with the same remedy.
2.3.4.2. Example 6: KeySync: Reset Own Keys
In this example, the User wishes to reset the synchronized keys in a
Device Group using KeySync (cf. [I-D.pep-keysync]).
Hoeneisen Expires 19 June 2023 [Page 22]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
There are a couple of examples where this could happen - a grouped
device is reset with reset_all_own_keys(), and some of the Identities
corresponding to some keys are marked for synchronization, or as an
internal function, a device leaves a Device Group and the remaining
member devices need to revoke old keys and set new ones.
2.3.4.2.1. Manual Reset of Grouped Keys
In the first case, reset_all_own_keys() separates out the Identities
which are synchronized Identities and which ones are non-synchronized
Identities. Non-synchronized Identities are subjected to the same
treatment as examples 1/2. The remaining Identities are processed
with key_reset_own_grouped_keys(); through this function, the engine
collects all Identities which are marked for synchronization and
proceeds as specified in key_reset_own_grouped_keys() (from the
initiating device) and the processing description for KeyReset
messages generated by key_reset_own_grouped_keys() (for the recipient
devices).
2.3.4.2.2. Leaving a Device Group
In the case where the User decides to take a device out of a Device
Group, this part of the protocol becomes more complicated. We divide
the actors, at first, into two groups: the leaver, and the remaining
group.
When the leaving device calls leave_device_group() within the KeySync
protocol, two sets of events are triggered, one set for the leaving
device, and one for the remaining group.
The leaving device notifies the group it is leaving, unmarks all of
its Identities for synchronization, and then resets all of them
locally via key_reset_user() and proceeds as with Example 2.
The group, on the other hand, chooses a leader. This leader calls
key_reset_own_grouped_keys() and both the leader, as the initiating
device, and the rest of the group, as recipient devices, proceed as
under manual reset of grouped keys above in this example.
3. Security Considerations
The Privacy Considerations outlined in Section 4 may also impose
risks to security. In particular a compromised private key may be
misused (e.g. impersonation) and remain undetected until the
communication partner (and all its devices) gets aware of the
KeyReset (see also Section 4).
Hoeneisen Expires 19 June 2023 [Page 23]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
4. Privacy Considerations
KeyReset messages are not sent immediately to all communication
partners, which may use the revoked key. Thus, there is a period of
time during which incoming communication from peers, that did not get
a KeyReset message yet, may no longer be private. To mitigate this
risk, implementations should provide a mechanism for sending instant
KeyReset notifications to previously contacted communication partners
(cf. Section 2.1).
In case a communication partner uses two or more devices that are not
part of a Device Group for KeySync (cf. [I-D.pep-keysync]), the
KeyReset messages may be consumed by one device of a User, while the
other devices remain unaware of the KeyReset (at least until they
have a chance to consume a follow-up KeyReset message). As a
consequence, incoming communication from such peers may no longer be
private (at least for some time). To mitigate this risk implementers
should implement pEp KeySync and Users should be advised to form
Device Groups with all their devices.
Depending on the implementation of the peer, communication partners
may not be able to consume a KeyReset message and act on it. As a
consequence such communication partners continue to use keys that
have been reset so that incoming communication from such peers may no
longer be private. This concerns mainly non-pEp implementations, but
also pEp implementations that have not implemented pEp KeyReset.
Note: The above mentioned issues exist similarly also with other
encryption protocols, when a key is compromised and peers are unaware
of it.
5. IANA Considerations
This document has no actions for IANA.
6. Acknowledgments
The concept of KeyReset was invented and further developed by Volker
Birk.
A substantial amount of content taken over to this document has been
originally drafted by Krista Bennett.
Additionally, the authors would like to thank the following people
who provided substantial contributions, helpful comments or
suggestions for this document: Hernani Marques, Linda Carmen Schmid,
and Luca Saiu.
Hoeneisen Expires 19 June 2023 [Page 24]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
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]
7. References
7.1. Normative References
[I-D.pep-general]
Birk, V., Marques, H., and B. Hoeneisen, "pretty Easy
privacy (pEp): Privacy by Default", Work in Progress,
Internet-Draft, draft-pep-general-01, 21 October 2022,
<https://www.ietf.org/archive/id/draft-pep-general-
01.txt>.
[I-D.pep-keysync]
Birk, V., Hoeneisen, B., and K. Bristol, "pretty Easy
privacy (pEp): Key Synchronization Protocol (KeySync)",
Work in Progress, Internet-Draft, draft-pep-keysync-02, 13
July 2020, <https://www.ietf.org/archive/id/draft-pep-
keysync-02.txt>.
[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>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
7.2. Informative References
[I-D.pep-email]
Marques, H., "pretty Easy privacy (pEp): Email Formats and
Protocols", Work in Progress, Internet-Draft, draft-pep-
email-01, 2 November 2020,
<https://www.ietf.org/archive/id/draft-pep-email-01.txt>.
Hoeneisen Expires 19 June 2023 [Page 25]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
[I-D.pep-handshake]
Marques, H. and B. Hoeneisen, "pretty Easy privacy (pEp):
Contact and Channel Authentication through Handshake",
Work in Progress, Internet-Draft, draft-marques-pep-
handshake-05, 8 July 2020,
<https://www.ietf.org/archive/id/draft-marques-pep-
handshake-05.txt>.
[I-D.pep-trustwords]
Hoeneisen, B. and H. Marques, "IANA Registration of
Trustword Lists: Guide, Template and IANA Considerations",
Work in Progress, Internet-Draft, draft-birk-pep-
trustwords-05, 9 January 2020,
<https://www.ietf.org/archive/id/draft-birk-pep-
trustwords-05.txt>.
[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/>.
Appendix A. Document Changelog
[[ RFC Editor: This section is to be removed before publication ]]
* draft-pep-keyreset-00:
- Initial version
Appendix B. Open Issues
[[ RFC Editor: This section should be empty and is to be removed
before publication ]]
* Check whether in IETF there is a concept of "technical messages",
i.e. messages that are meant for the client, but not for the User.
Author's Address
Bernie Hoeneisen
pEp Foundation
Oberer Graben 4
CH- 8400 Winterthur
Switzerland
Email: bernie.hoeneisen@pep.foundation
Hoeneisen Expires 19 June 2023 [Page 26]
Internet-Draft pretty Easy privacy (pEp) Key Reset December 2022
URI: https://pep.foundation/
Hoeneisen Expires 19 June 2023 [Page 27]