idnits 2.17.1 draft-birk-pep-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 08, 2019) is 1725 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '3' on line 1096 ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Downref: Normative reference to an Informational RFC: RFC 7435 == Outdated reference: A later version (-05) exists of draft-birk-pep-trustwords-04 == Outdated reference: A later version (-01) exists of draft-hoeneisen-pep-keysync-00 == Outdated reference: A later version (-05) exists of draft-marques-pep-handshake-03 == Outdated reference: A later version (-03) exists of draft-marques-pep-rating-02 Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group H. Marques 3 Internet-Draft C. Luck 4 Intended status: Standards Track pEp Foundation 5 Expires: January 9, 2020 B. Hoeneisen 6 Ucom.ch 7 July 08, 2019 9 pretty Easy privacy (pEp): Privacy by Default 10 draft-birk-pep-04 12 Abstract 14 The pretty Easy privacy (pEp) model and protocols describe a set of 15 conventions for the automation of operations traditionally seen as 16 barriers to the use and deployment of secure, privacy-preserving end- 17 to-end interpersonal messaging. These include, but are not limited 18 to, key management, key discovery, and private key handling 19 (including peer-to-peer synchronization of private keys and other 20 user data across devices). Human Rights-enabling principles like 21 Data Minimization, End-to-End and Interoperability are explicit 22 design goals. For the goal of usable privacy, pEp introduces means 23 to verify communication between peers and proposes a trust-rating 24 system to denote secure types of communications and signal the 25 privacy level available on a per-user and per-message level. 26 Significantly, the pEp protocols build on already available security 27 formats and message transports (e.g., PGP/MIME with email), and are 28 written with the intent to be interoperable with already widely- 29 deployed systems in order to ease adoption and implementation. This 30 document outlines the general design choices and principles of pEp. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on January 9, 2020. 49 Copyright Notice 51 Copyright (c) 2019 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (https://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 1.1. Relationship to other pEp documents . . . . . . . . . . . 5 68 1.2. Requirements Language . . . . . . . . . . . . . . . . . . 5 69 1.3. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 5 70 2. Protocol's Core Design Principles . . . . . . . . . . . . . . 6 71 2.1. Privacy by Default . . . . . . . . . . . . . . . . . . . 6 72 2.2. Data Minimization . . . . . . . . . . . . . . . . . . . . 7 73 2.3. Interoperability . . . . . . . . . . . . . . . . . . . . 7 74 2.4. Peer-to-Peer . . . . . . . . . . . . . . . . . . . . . . 7 75 2.5. User Interaction . . . . . . . . . . . . . . . . . . . . 8 76 3. Identity System . . . . . . . . . . . . . . . . . . . . . . . 8 77 3.1. User . . . . . . . . . . . . . . . . . . . . . . . . . . 9 78 3.2. Address . . . . . . . . . . . . . . . . . . . . . . . . . 9 79 3.3. Identity . . . . . . . . . . . . . . . . . . . . . . . . 9 80 4. Key Management . . . . . . . . . . . . . . . . . . . . . . . 10 81 4.1. Key Generation . . . . . . . . . . . . . . . . . . . . . 10 82 4.2. Private Keys . . . . . . . . . . . . . . . . . . . . . . 10 83 4.2.1. Storage . . . . . . . . . . . . . . . . . . . . . . . 10 84 4.2.2. Passphrase . . . . . . . . . . . . . . . . . . . . . 11 85 4.3. Key Reset . . . . . . . . . . . . . . . . . . . . . . . . 11 86 4.4. Public Key Distribution . . . . . . . . . . . . . . . . . 11 87 4.4.1. UX Considerations . . . . . . . . . . . . . . . . . . 12 88 4.4.2. No addition of unnecessary metadata . . . . . . . . . 12 89 4.4.3. No centralized public key storage or retrieval by 90 default . . . . . . . . . . . . . . . . . . . . . . . 12 91 4.4.4. Example message flow . . . . . . . . . . . . . . . . 12 92 4.5. Key Reset . . . . . . . . . . . . . . . . . . . . . . . . 15 93 5. Trust Management . . . . . . . . . . . . . . . . . . . . . . 15 94 5.1. Privacy Status . . . . . . . . . . . . . . . . . . . . . 15 95 5.2. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 15 96 5.3. Trust Rating . . . . . . . . . . . . . . . . . . . . . . 16 97 5.4. Trust Revoke . . . . . . . . . . . . . . . . . . . . . . 16 98 6. Synchronization . . . . . . . . . . . . . . . . . . . . . . . 16 99 6.1. Private Key Synchronization . . . . . . . . . . . . . . . 16 100 6.2. Trust Synchronization . . . . . . . . . . . . . . . . . . 16 101 7. Interoperability . . . . . . . . . . . . . . . . . . . . . . 17 102 8. Options in pEp . . . . . . . . . . . . . . . . . . . . . . . 17 103 8.1. Option "Passive Mode" . . . . . . . . . . . . . . . . . . 17 104 8.2. Option "Disable Protection" . . . . . . . . . . . . . . . 17 105 8.3. Option "Extra Keys" . . . . . . . . . . . . . . . . . . . 17 106 8.3.1. Use Case for Organizations . . . . . . . . . . . . . 17 107 8.3.2. Use Case for Key Synchronization . . . . . . . . . . 18 108 8.4. Option "Blacklist Keys" . . . . . . . . . . . . . . . . . 18 109 9. Security Considerations . . . . . . . . . . . . . . . . . . . 18 110 10. Privacy Considerations . . . . . . . . . . . . . . . . . . . 18 111 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 112 12. Implementation Status . . . . . . . . . . . . . . . . . . . . 19 113 12.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 19 114 12.2. Current software implementing pEp . . . . . . . . . . . 19 115 12.3. Reference implementation of pEp's core . . . . . . . . . 20 116 12.4. Abstract Crypto API examples . . . . . . . . . . . . . . 21 117 13. Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 118 14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21 119 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 120 15.1. Normative References . . . . . . . . . . . . . . . . . . 22 121 15.2. Informative References . . . . . . . . . . . . . . . . . 22 122 Appendix A. Code Excerpts . . . . . . . . . . . . . . . . . . . 24 123 A.1. pEp Identity . . . . . . . . . . . . . . . . . . . . . . 24 124 A.1.1. Corresponding SQL . . . . . . . . . . . . . . . . . . 24 125 A.2. pEp Communication Type . . . . . . . . . . . . . . . . . 25 126 A.3. Abstract Crypto API examples . . . . . . . . . . . . . . 27 127 A.3.1. Encrypting a Message . . . . . . . . . . . . . . . . 27 128 A.3.2. Decrypting a Message . . . . . . . . . . . . . . . . 28 129 A.3.3. Obtain Common Trustwords . . . . . . . . . . . . . . 30 130 Appendix B. Document Changelog . . . . . . . . . . . . . . . . . 30 131 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 32 132 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 32 134 1. Introduction 136 Secure and private communications are vital for many different 137 reasons, and there are particular properties that privacy-preserving 138 protocols need to fulfill in order to best serve users. In 139 particular, [RFC8280] has identified and documented important 140 principles such as data minimization, the end-to-end principle, and 141 interoperability as integral properties which enable access to Human 142 Rights. Today's applications widely lack privacy support that 143 ordinary users can easily adapt. The pretty Easy privacy (pEp) 144 protocols generally conform to the principles outlined in [RFC8280], 145 and, as such, can facilitate the adoption and correct usage of secure 146 and private communications technology. 148 The pretty Easy privacy (pEp) protocols are propositions to the 149 Internet community to create software for peers to automatically 150 encrypt, anonymize (where possible), and verify their daily written 151 digital communications. This is achieved by building upon already 152 existing standards and tools and automating each step a user needs to 153 carry out in order to engage in secure end-to-end encrypted 154 communications. Significantly, the pEp protocols describe how do to 155 this without dependence on centralized infrastructures. 157 The pEp project emerged from the CryptoParty movement. During that 158 time, the initiators learned that while step-by-step guides can help 159 some users engage in secure end-to-end communications, it is both 160 more effective and convenient for the vast majority of users if these 161 step-by-step guides are put into running code (following a protocol), 162 which automates the initial configuration and general usage of 163 cryptographic tools. To facilitate this goal, pEp proposes the 164 automation of key management, key discovery, and key synchronization 165 through an in-band approach which follows the end-to-end principle. 167 To mitigate man-in-the-middle attacks (MITM) by an active adversary, 168 and as the only manual step users carry out in the course of the 169 protocols, the proposed Trustwords [I-D.birk-pep-trustwords] 170 mechanism uses natural language representations of two peers' 171 fingerprints for users to verify their trust in a paired 172 communication channel. 174 The privacy-by-default principles that pEp introduces are in 175 accordance with the perspective outlined in [RFC7435], aiming to 176 provide opportunistic security in the sense of "some protection most 177 of the time". This is done, however, with the subtle but important 178 difference that when privacy is weighed against security, the choice 179 defaults to privacy. Therefore, data minimization is a primary goal 180 in pEp (e.g., hiding subject lines and headers unnecessary for email 181 transport inside the encrypted payload of a message). 183 The pEp propositions are focused on (but not limited to) written 184 digital communications and cover asynchronous (offline) types of 185 communications like email as well as synchronous (online) types such 186 as chat. 188 pEp's goal is to bridge different standardized and widely-used 189 communications channels such that users can reach communications 190 partners in the most privacy-enhancing way possible. 192 1.1. Relationship to other pEp documents 194 While this document outlines the general design choices and 195 principles of pEp, other related documents specialize in more 196 particular aspects of the model, or the application of pEp on a 197 specific protocol like as follows: 199 1. pEp-enabled applications (e.g., pEp email 200 [I-D.marques-pep-email]). 202 2. Helper functions for peer interaction, which facilitate 203 understanding and handling of the cryptographic aspects of pEp 204 implementation for users (e.g., pEp Handshake 205 [I-D.marques-pep-handshake]). 207 3. Helper functions for interactions between a user's own devices, 208 which give the user the ability to run pEp applications on 209 different devices at the same time, such as a computer, mobile 210 phone, or tablets (e.g., pEp KeySync 211 [I-D.hoeneisen-pep-keysync]). 213 In addition, there are documents that do not directly depend on this 214 one, but provide generic functions needed in pEp, e.g., IANA 215 Registration of Trustword Lists [I-D.birk-pep-trustwords]. 217 [[ Note: At this stage it is not yet clear to us how many of our 218 implementation details should be part of new RFCs and where we can 219 safely refer to already existing RFCs to clarify which RFCs we rely 220 on. ]] 222 1.2. Requirements Language 224 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 225 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 226 document are to be interpreted as described in [RFC2119]. 228 1.3. Terms 230 The following terms are defined for the scope of this document: 232 o pEp Handshake: The process of one user contacting another over an 233 independent channel in order to verify Trustwords (or by fallback: 234 fingerprints). This can be done in-person or through established 235 verbal communication channels, like a phone call. 236 [I-D.marques-pep-handshake] 238 o Trustwords: A scalar-to-word representation of 16-bit numbers (0 239 to 65535) to natural language words. When doing a Handshake, 240 peers are shown combined Trustwords of both public keys involved 241 to ease the comparison. [I-D.birk-pep-trustwords] 243 o Trust On First Use (TOFU): cf. [RFC7435], which states: "In a 244 protocol, TOFU calls for accepting and storing a public key or 245 credential associated with an asserted identity, without 246 authenticating that assertion. Subsequent communication that is 247 authenticated using the cached key or credential is secure against 248 an MiTM attack, if such an attack did not succeed during the 249 vulnerable initial communication." 251 o Man-in-the-middle (MITM) attack: cf. [RFC4949], which states: "A 252 form of active wiretapping attack in which the attacker intercepts 253 and selectively modifies communicated data to masquerade as one or 254 more of the entities involved in a communication association." 256 2. Protocol's Core Design Principles 258 2.1. Privacy by Default 260 pEp's most important goal is to ensure privacy above all else. To 261 clarify, pEp's protocol defaults are designed to maximize both 262 security and privacy, but in the few cases where achieving both more 263 privacy and more security are in conflict, pEp chooses more privacy. 265 In contrast to pEp's prioritization of user privacy, OpenPGP's Web- 266 of-Trust (WoT) releases user and trust level relationships to the 267 public. In addition, queries to OpenPGP keyservers dynamically 268 disclose the social graph, indicating a user's intent to communicate 269 with specific peers. Similar issues exist in other security 270 protocols that rely upon a centralized trust model, such as the 271 certificate revocation protocols used in XPKI (S/MIME). 273 [[*TODO*: Fix the wording and reference to XPKI, S/MIME]]. 275 In pEp messaging (e.g., when using HTML) content and information 276 SHALL NOT be obtained from remote locations as this constitutes a 277 privacy breach. 279 Because of the inherent privacy risks in using remote or centralized 280 infrastructures, implementations of pEp messaging, by default, SHALL 281 NOT obtain content and information from remote or centralized 282 locations, as this constitutes a privacy breach. In email this issue 283 exists with HTML mails. 285 2.2. Data Minimization 287 Data minimization keeps data spare and hides all technically 288 concealable information whenever possible. It is an important design 289 goal of pEp. 291 2.3. Interoperability 293 The proposed pEp protocols seek interoperability with established 294 message formats, as well as cryptographic security protocols and 295 their widespread implementations. 297 To achieve this interoperability, pEp MUST follow Postel's Robustness 298 Principle outlined in [RFC1122]: "Be liberal in what you accept, and 299 conservative in what you send." 301 Particularly, pEp applies Postel's principle as follows: 303 o pEp is conservative (strict) in requirements for pEp 304 implementations and how they interact with pEp or other compatible 305 implementations. 307 o pEp liberally accepts input from non-pEp implementations. For 308 example, in email, pEp will not produce outgoing messages, but 309 will transparently support decryption of incoming PGP/INLINE 310 messages. 312 o Finally, where pEp requires divergence from established RFCs due 313 to privacy concerns (e.g., from OpenPGP propositions as defined in 314 [OpenPGP], options SHOULD be implemented which empower the user to 315 override pEp's defaults. 317 2.4. Peer-to-Peer 319 Messaging and verification processes in pEp are designed to work in a 320 peer-to-peer (P2P) manner, without the involvement of intermediaries. 322 This means there MUST NOT be any pEp-specific central services 323 whatsoever needed for pEp implementations, both in the case of 324 verification of peers and for the actual encryption. 326 However, implementers of pEp MAY provide options for interoperation 327 with providers of centralized infrastructures (e.g., to enable users 328 to communicate with their peers on platforms with vendor lock-in). 330 Trust provided by global Certificate Authorities (e.g., commercial 331 X.509 CAs) SHALL NOT be signaled as trustworthy (cf. 333 [I-D.marques-pep-rating]) to users of pEp (e.g., when interoperating 334 with peers using S/MIME) by default. 336 2.5. User Interaction 338 Implementers of pEp MUST take special care not to overburden users 339 with technical terms, especially those specific to cryptography, like 340 "keys", "certificates", or "fingerprints". Users may explicitly opt 341 for exposure to these terms; i.e., advanced settings MAY be 342 available, and in some cases, these options may be required. 343 However, these options SHALL NOT be exposed to users of pEp 344 implementations unless necessary or opted-for." 346 The authors believe that widespread adoption of end-to-end 347 cryptography is possible if users are not required to understand 348 cryptography and key management. This belief forms the central goal 349 of pEp, which is that users can simply rely on the principles of 350 Privacy by Default. 352 On the other hand, to preserve usability, users MUST NOT be required 353 to wait for cryptographic tasks such as key generation to complete 354 before being able to use their respective message client for its 355 default purpose. In short, pEp implementers MUST ensure that the 356 ability to draft, send, and receive messages is always preserved, 357 even if that means a message is sent unencrypted, in accordance with 358 the Opportunistic Security approach outlined in [RFC7435]. 360 In turn, pEp implementers MUST ensure that an unambiguous privacy 361 status is clearly visible to the user, both on a per-contact as well 362 as per-message level. This allows users to see at a glance both the 363 privacy level for the message and the trust level of its intended 364 recipients before choosing to send it. 366 [[ *NOTE*: We are aware of the fact that usually UX requirements are 367 not part of RFCs. However, in order to encourage massive adoption of 368 secure end-to-end encryption while at the same time avoiding putting 369 users at risk, we believe certain straightforward signaling 370 requirements for users to be a good idea, just as it is currently 371 done for already-popular instant messaging services. ]] 373 3. Identity System 375 Everyone has the right to choose how to reveal themselves to the 376 world, both offline and online. This is an important element to 377 maintain psychological, physical, and digital privacy. As such, pEp 378 users MUST have the option to choose their identity, and they MUST 379 have the ability to maintain multiple identities. 381 These different identities MUST NOT be externally correlatable with 382 each other by default. On the other hand, combining different 383 identities when such information is known MUST be supported (alias 384 support). 386 3.1. User 388 A user is a real world human being or a group of human beings. If it 389 is a single human being, it can be called person. 391 A user is identified by a user ID (user_id). The user_id SHOULD be a 392 UUID, it MAY be an arbitrary unique string. 394 The own user can have a user_id like all other users. If the own 395 user does not have a user_id, then it is assigned a "pEp_own_userId" 396 instead. 398 A user can have a default key. [[ TODO: Provide ref explaining this. 399 ]] 401 3.2. Address 403 A pEp address is a network address, e.g., an SMTP address or another 404 Universal Resource Identifier (URI). 406 [[ Note: It might be necessary to introduce further addressing 407 schemes through IETF contributions or IANA registrations, e.g., 408 implementing pEp to bridge to popular messaging services with no URIs 409 defined. ]] 411 3.3. Identity 413 An identity is a representation of a user, encapsulating how this 414 user appears within the network of a messaging system. This 415 representation may or may not be pseudonymous in nature. 417 An identity is defined by mapping a user_id to an address. If no 418 user_id is known, it is guessed by mapping a username to an address. 420 An identity can have a temporary user_id as a placeholder until a 421 real user_id is known. 423 For this reason, in pEp a different key pair for each (e.g., email) 424 account MUST be created. This allows a user to retain different 425 identities, which are not correlated by the usage of the same key for 426 all of those. This is beneficial in terms of privacy. 428 A user MAY have a default key; each identity a user has MAY have a 429 default key (of its own). 431 [[ TODO: Provide ref explaining this. ]] 433 In Appendix A.1, the definition of a pEp identity can be found 434 according to the reference implementation by the pEp engine. 436 4. Key Management 438 In order to achieve the goal of widespread adoption of secure 439 communications, key management in pEp MUST be automated. 441 4.1. Key Generation 443 A pEp implementation MUST ensure that cryptographic keys for every 444 configured identity are available. If a corresponding key pair for 445 the identity of a user is found and said identity fulfills the 446 requirements (e.g., for email, as set out in 447 [I-D.marques-pep-email]), said key pair MUST be reused. Otherwise a 448 new key pair MUST be generated. This may be carried out instantly 449 upon its configuration. 451 On devices with limited processing power (e.g., mobile devices) the 452 key generation may take more time than a user is willing to wait. If 453 this is the case, users SHOULD NOT be stopped from communicating, 454 i.e., the key generation process SHOULD be carried out in the 455 background. 457 4.2. Private Keys 459 4.2.1. Storage 461 Private keys in pEp implementations MUST always be held on the end 462 user's device(s): pEp implementers MUST NOT rely on private keys 463 stored in centralized remote locations. This applies even for key 464 storages where the private keys are protected with sufficiently long 465 passphrases. It is considered a violation of pEp's P2P design 466 principle to rely on centralized infrastructures (cf. Section 2.4). 467 This also applies for pEp implementations created for applications 468 not residing on a user's device (e.g., web-based MUAs). In such 469 cases, pEp implementations MUST be done in a way such that the 470 locally-held private key can neither be directly accessed nor leaked 471 to the outside world. 473 [[ Note: It is particularly important that browser add-ons 474 implementing pEp functionality do not obtain their cryptographic code 475 from a centralized (cloud) service, as this must be considered a 476 centralized attack vector allowing for backdoors, negatively 477 impacting privacy. ]] 479 Cf. Section 6.1 for a means to synchronize private keys among 480 different devices of the same network address in a secure manner. 482 4.2.2. Passphrase 484 Passphrases to protect a user's private key MUST be supported by pEp 485 implementations, but MUST NOT be enforced by default. That is, if a 486 pEp implementation finds a suitable (i.e., secure enough) 487 cryptographic setup, which uses passphrases, pEp implementations MUST 488 provide a way to unlock the key. However, if a new key pair is 489 generated for a given identity, no passphrase MUST be put in place. 490 The authors assume that the enforcement of secure (i.e., unique and 491 long enough) passphrases would massively reduce the number of pEp 492 users (by hassling them), while providing little to no additional 493 privacy for the common cases of passive monitoring being carried out 494 by corporations or state-level actors. 496 4.3. Key Reset 498 4.4. Public Key Distribution 500 As the key is available (cf. Section 4.1) implementers of pEp are 501 REQUIRED to ensure that the identity's public key is attached to 502 every outgoing message. However, this MAY be omitted if the peer has 503 previously received a message encrypted with the public key of the 504 sender. 506 The sender's public key SHOULD be sent encrypted whenever possible, 507 i.e., when a public key of the receiving peer is available. If no 508 encryption key of the recipient is available, the sender's public key 509 MAY be sent unencrypted. In either case, this approach ensures that 510 messaging clients (e.g., MUAs that at least implement OpenPGP) do not 511 need to have pEp implemented to see a user's public key. Such peers 512 thus have the chance to (automatically) import the sender's public 513 key. 515 If there is already a known public key from the sender of a message 516 and it is still valid and not expired, new keys MUST NOT be used for 517 future communication unless they are signed by the previous key (to 518 avoid a MITM attack). Messages MUST always be encrypted with the 519 receiving peer's oldest public key, as long as it is valid and not 520 expired. 522 4.4.1. UX Considerations 524 Implementers of pEp SHALL prevent the display of public keys attached 525 to messages (e.g, in email) to the user in order to prevent user 526 confusion by files they are potentially unaware of how to handle. 528 4.4.2. No addition of unnecessary metadata 530 Metadata, such as email headers, MUST NOT be added in order to 531 announce a user's public key. This is considered unnecessary 532 information leakage, may affect user privacy, and may be subject to a 533 country's data retention laws (cf. Section 2.2). Furthermore, this 534 may affect interoperability to existing users that have no knowledge 535 of such header fields, such as users of OpenPGP in email, and lose 536 the ability to import any keys distributed in this way as a result. 537 The ability to extract and receive public keys from such metadata 538 SHOULD be supported, however, in the event these approaches become 539 widespread. 541 4.4.3. No centralized public key storage or retrieval by default 543 Keyservers or generally intermediate approaches to obtain a peer's 544 public key SHALL NOT be used by default. On the other hand, the user 545 MAY be provided with the option to opt-in for remote locations to 546 obtain keys, considering the widespread adoption of such approaches 547 for key distribution. 549 Keys generated or obtained by pEp clients MUST NOT be uploaded to any 550 (intermediate) keystore locations without the user's explicit 551 consent. 553 4.4.4. Example message flow 555 The following example roughly describes a pEp scenario with a typical 556 initial message flow to demonstrate key exchange and basic trust 557 management: 559 The following example describes a pEp scenario between two users - 560 Alice and Bob - in order to demonstrate the message flow that occurs 561 when exchanging keys and determining basic trust management for the 562 first time: 564 1. Alice - knowing nothing of Bob - sends a message to Bob. As Alice 565 has no public key from Bob, this message is sent out unencrypted. 566 However, Alice's public key is automatically attached. 568 2. Bob receives Alice's message and her public key. He is able to 569 reply to her and encrypt the message. His public key is 570 automatically attached to the message. Because he has her public 571 key now, Alice's rating in his message client changes to 572 'encrypted'. From a UX perspective, this status is displayed in 573 yellow (cf. Section 5.3). 575 3. Alice receives Bob's key. As of now Alice is also able to send 576 secure messages to Bob. The rating for Bob changes to "encrypted" 577 (with yellow color) in Alice's messaging client (cf. 578 Section 5.3). 580 4. Alice receives Bob's reply with his public key attached. Now, 581 Alice can send secure messages to Bob as well. The rating for 582 Bob changes to yellow, or 'encrypted', in Alice's messaging 583 client Section 5.3. 585 5. If Alice and Bob want to prevent man-in-the-middle (MITM) 586 attacks, they can engage in a pEp Handshake comparing their so- 587 called Trustwords (cf. Section 5.2) and confirm this process if 588 those match. After doing so, their identity rating changes to 589 "encrypted and authenticated" (cf. Section 5.3), which (UX-wise) 590 can be displayed using a green color. See also Section 5. 592 6. Alice and Bob can encrypt now, but they are not yet 593 authenticated, leaving them vulnerable to man-in-the-middle 594 (MitM) attacks. To prevent this from occurring, Alice and Bob 595 can engage in a pEp Handshake to compare their Trustwords (cf. 596 Section 5.2) and confirm if they match. After this step is 597 performed, their respective identity ratings change to "encrypted 598 and authenticated", which is represented by a green color (cf. 599 Section 5. 601 ----- ----- 602 | A | | B | 603 ----- ----- 604 | | 605 +------------------------+ +------------------------+ 606 | auto-generate key pair | | auto-generate key pair | 607 | (if no key yet) | | (if no key yet) | 608 +------------------------+ +------------------------+ 609 | | 610 +-----------------------+ +-----------------------+ 611 | Privacy Status for B: | | Privacy Status for A: | 612 | *Unencrypted* | | *Unencrypted* | 613 +-----------------------+ +-----------------------+ 614 | | 615 | A sends message to B (Public Key | 616 | attached) / optionally signed, but | 617 | NOT ENCRYPTED | 618 +------------------------------------------>| 619 | | 620 | +-----------------------+ 621 | | Privacy Status for A: | 622 | | *Encrypted* | 623 | +-----------------------+ 624 | | 625 | B sends message to A (Public Key | 626 | attached) / signed and ENCRYPTED | 627 |<------------------------------------------+ 628 | | 629 +-----------------------+ | 630 | Privacy Status for B: | | 631 | *Encrypted* | | 632 +-----------------------+ | 633 | | 634 | A and B successfully compare their | 635 | Trustwords over an alternative channel | 636 | (e.g., phone line) | 637 |<-- -- -- -- -- -- -- -- -- -- -- -- -- -->| 638 | | 639 +-----------------------+ +-----------------------+ 640 | Privacy Status for B: | | Privacy Status for A: | 641 | *Trusted* | | *Trusted* | 642 +-----------------------+ +-----------------------+ 643 | | 645 4.5. Key Reset 647 [[ TODO: This section will explain how to deal with invalid keys, 648 e.g., if expired or (potentially) leaked. ]] 650 5. Trust Management 652 [[ TODO: Intro ]] 654 5.1. Privacy Status 656 The trust status for an identity can change due to a number of 657 factors. These shifts will cause the color code assigned to this 658 identity to change accordingly, and is applied to future 659 communications with this identity. 661 For end-users, the most important component of pEp, which MUST be 662 made visible on a per-recipient and per-message level, is the Privacy 663 Status. 665 By colors, symbols and texts a user SHALL immediately understand how 666 private 668 o a communication channel with a given peer was or ought to be and 670 o a given message was or ought to be. 672 5.2. Handshake 674 To establishing trust between peers and to upgrade Privacy Status, 675 pEp defines a handshake, which is specified in 676 [I-D.marques-pep-handshake]. 678 In pEp, Trustwords [I-D.birk-pep-trustwords] are used for users to 679 compare the authenticity of peers in order to mitigate MITM attacks. 681 By default, Trustwords MUST be used to represent two peers' 682 fingerprints of their public keys in pEp implementations. 684 In order to retain compatibility with peers not using pEp 685 implementations (e.g., Mail User Agents (MUAs) with OpenPGP 686 implementations without Trustwords), it is REQUIRED that pEp 687 implementers give the user the choice to show both peers' 688 fingerprints instead of just their common Trustwords. 690 5.3. Trust Rating 692 pEp includes a Trust Rating system defining Rating and Color Codes to 693 express the Privacy Status of a peer or message 694 [I-D.marques-pep-rating]. The ratings are labeled, e.g., as 695 "Unencrypted", "Encrypted", "Trusted", "Under Attack", etc. The 696 Privacy Status in its most general form is expressed with traffic 697 lights semantics (and respective symbols and texts), whereas the 698 three colors yellow, green and red can be applied for any peer or 699 message - like this immediately indicating how secure and trustworthy 700 (and thus private) a communication was or ought to be considered. 702 The pEp Trust Rating system with all its states and respective 703 representations to be followed is outlined in 704 [I-D.marques-pep-rating]. 706 Note: An example for the rating of communication types, the 707 definition of the data structure by the pEp Engine reference 708 implementation is provided in Appendix A.2. 710 5.4. Trust Revoke 712 [[ TODO: This section will explain how to deal with the situation 713 when a peer can no longer be trusted, e.g., if a peer's device is 714 compromised. ]] 716 6. Synchronization 718 An important feature of pEp is to assist the user to run pEp 719 applications on different devices, such as personal computers, mobile 720 phones and tablets, at the same time. Therefore, state needs to be 721 synchronized among the different devices. 723 6.1. Private Key Synchronization 725 The pEp KeySync protocol (cf. [I-D.hoeneisen-pep-keysync]) is a 726 decentralized proposition which defines how pEp users can distribute 727 their private keys among their different devices in a user- 728 authenticated manner. This allows users to read their messages 729 across their various devices, as long as they share a common address, 730 such as an email account. 732 6.2. Trust Synchronization 734 [[ TODO: This section will explain how trust and other related state 735 is synchronized among different devices in a user-authenticated 736 manner. ]] 738 7. Interoperability 740 pEp aims to be interoperable with existing applications designed to 741 enable privacy, e.g., OpenPGP and S/MIME in email. 743 8. Options in pEp 745 In this section a non-exhaustive selection of options is provided. 747 8.1. Option "Passive Mode" 749 By default, the sender attaches its public key to any outgoing 750 message (cf. Section 4.4). For situations where a sender wants to 751 ensure that it only attaches a public key to an Internet user which 752 has a pEp implementation, a Passive Mode MUST be made available. 754 8.2. Option "Disable Protection" 756 Using this option, protection can be disabled generally or 757 selectively. Implementers of pEp MUST provide an option "Disable 758 Protection" to allow a user to disable encryption and signing for: 760 1. all communication 762 2. specific contacts 764 3. specific messages 766 The public key still attached, unless the option "Passive Mode" (cf. 767 Section 8.1) is activated at the same time. 769 8.3. Option "Extra Keys" 771 8.3.1. Use Case for Organizations 773 For internal or enterprise environments, authorized personnel may 774 need to centrally decrypt user messages for archival or other legal 775 purposes. Therefore, pEp implementers MAY provide an "Extra Keys" 776 option in which a message is encrypted with at least one additional 777 public key. The corresponding secret key(s) are intended to be 778 secured by CISO staff or other authorized personnel for the 779 organization. 781 However, it is crucial that the "Extra Keys" feature MUST NOT be 782 activated by default for any network address, and is intended to be 783 an option used only for organization-specific identities, as well as 784 their corresponding network addresses and accounts. The "Extra Keys" 785 feature SHOULD NOT be applied to the private identities, addresses, 786 or accounts a user might possess once it is activated. 788 8.3.2. Use Case for Key Synchronization 790 The "Extra Keys" feature also plays a role during pEp's KeySync 791 protocols, where the additional keys are used to decipher message 792 transactions by both parties involved during the negotiation process 793 for private key synchronization. During the encrypted (but 794 untrusted) transactions, KeySync messages are not just encrypted with 795 the sending device's default key, but also with the default keys of 796 both parties involved in the synchronization process. 798 8.4. Option "Blacklist Keys" 800 A "Blacklist Keys" option MAY be provided for an advanced user, 801 allowing them to disable keys of peers that they no longer want to 802 use in new communications. However, the keys SHALL NOT be deleted. 803 It MUST still be possible to verify and decipher past communications 804 that used these keys. 806 9. Security Considerations 808 By attaching the sender's public key to outgoing messages, Trust on 809 First Use (TOFU) is established. However, this is prone to MITM 810 attacks. Cryptographic key subversion is considered Pervasive 811 Monitoring (PM) according to [RFC7258]. Those attacks can be 812 mitigated, if the involved users compare their common Trustwords. 813 This possibility MUST be made easily accessible to pEp users in the 814 user interface implementation. If for compatibility reasons (e.g., 815 with OpenPGP users) no Trustwords can be used, then a comparatively 816 easy way to verify the respective public key fingerprints MUST be 817 implemented. 819 As the use of passphrases for private keys is not advised, devices 820 themselves SHOULD use encryption. 822 10. Privacy Considerations 824 [[ TODO ]] 826 11. IANA Considerations 828 This document has no actions for IANA. 830 12. Implementation Status 832 12.1. Introduction 834 This section records the status of known implementations of the 835 protocol defined by this specification at the time of posting of this 836 Internet-Draft, and is based on a proposal described in [RFC7942]. 837 The description of implementations in this section is intended to 838 assist the IETF in its decision processes in progressing drafts to 839 RFCs. Please note that the listing of any individual implementation 840 here does not imply endorsement by the IETF. Furthermore, no effort 841 has been spent to verify the information presented here that was 842 supplied by IETF contributors. This is not intended as, and must not 843 be construed to be, a catalog of available implementations or their 844 features. Readers are advised to note that other implementations may 845 exist. 847 According to [RFC7942], "[...] this will allow reviewers and working 848 groups to assign due consideration to documents that have the benefit 849 of running code, which may serve as evidence of valuable 850 experimentation and feedback that have made the implemented protocols 851 more mature. It is up to the individual working groups to use this 852 information as they see fit." 854 12.2. Current software implementing pEp 856 The following software implementing the pEp protocols (to varying 857 degrees) already exists: 859 o pEp for Outlook as add-on for Microsoft Outlook, release 860 [SRC.pepforoutlook] 862 o pEp for Android (based on a fork of the K9 MUA), release 863 [SRC.pepforandroid] 865 o Enigmail/pEp as add-on for Mozilla Thunderbird, release 866 [SRC.enigmailpep] 868 o pEp for iOS (implemented in a new MUA), beta [SRC.pepforios] 870 pEp for Android, iOS and Outlook are provided by pEp Security, a 871 commercial entity specializing in end-user software implementing pEp 872 while Enigmail/pEp is pursued as community project, supported by the 873 pEp Foundation. 875 All software is available as Free Software and published also in 876 source form. 878 12.3. Reference implementation of pEp's core 880 The pEp Foundation provides a reference implementation of pEp's core 881 principles and functionalities, which go beyond the documentation 882 status of this Internet-Draft. [SRC.pepcore] 884 pEp's reference implementation is composed of pEp Engine and pEp 885 Adapters (or bindings), alongside with some libraries which pEp 886 Engine relies on to function on certain platforms (like a NetPGP fork 887 we maintain for the iOS platform). 889 The pEp engine is a Free Software library encapsulating 890 implementations of: 892 o Key Management 894 Key Management in pEp engine is based on GnuPG key chains (NetPGP 895 on iOS). Keys are stored in an OpenPGP compatible format and can 896 be used for different crypto implementations. 898 o Trust Rating 900 pEp engine is sporting a two phase trust rating system. In phase 901 one there is a rating based on channel, crypto and key security 902 named "comm_types". In phase 2 these are mapped to user 903 representable values which have attached colors to present them in 904 traffic light semantics. 906 o Abstract Crypto API 908 The Abstract Crypto API is providing functions to encrypt and 909 decrypt data or full messages without requiring an application 910 programmer to understand the different formats and standards. 912 o Message Transports 914 pEp engine will support a growing list of Message Transports to 915 support any widespread text messaging system including email, SMS, 916 XMPP and many more. 918 pEp engine is written in C99 programming language. It is not meant 919 to be used in application code directly. Instead, pEp engine is 920 coming together with a list of software adapters for a variety of 921 programming languages and development environments, which are: 923 o pEp COM Server Adapter 925 o pEp JNI Adapter 926 o pEp JSON Adapter 928 o pEp ObjC (and Swift) Adapter 930 o pEp Python Adapter 932 o pEp Qt Adapter 934 12.4. Abstract Crypto API examples 936 A selection of code excerpts from the pEp Engine reference 937 implementation (encrypt message, decrypt message, and obtain 938 trustwords) can be found in Appendix A.3. 940 13. Notes 942 The pEp logo and "pretty Easy privacy" are registered trademarks 943 owned by the non-profit pEp Foundation based in Switzerland. 945 Primarily, we want to ensure the following: 947 o Software using the trademarks MUST be backdoor-free. 949 o Software using the trademarks MUST be accompanied by a serious 950 (detailed) code audit carried out by a reputable third-party, for 951 any proper release. 953 The pEp Foundation will help to support any community-run (non- 954 commercial) project with the latter, be it organizationally or 955 financially. 957 Through this, the foundation wants to make sure that software using 958 the pEp trademarks is as safe as possible from a security and privacy 959 point of view. 961 14. Acknowledgments 963 The authors would like to thank the following people who have 964 provided significant contributions to the development of this 965 document: Volker Birk, Krista Bennett, and S. Shelburn. 967 Furthermore, the authors would like to thank the following people who 968 who provided helpful comments and suggestions for this document: 970 Alexey Melnikov, Athena Schumacher, Ben Campbell, Brian Trammell, 971 Bron Gondwana, Daniel Kahn Gillmor, Enrico Tomae, Eric Rescorla, 972 Gabriele Lenzini, Hans-Peter Dittler, Iraklis Symeonidis, Kelly 973 Bristol, Mirja Kuehlewind, Nana Kerlstetter, Neal Walfield, Pete 974 Resnick, Russ Housley, and Stephen Farrel. 976 This work was initially created by pEp Foundation, and then reviewed 977 and extended with funding by the Internet Society's Beyond the Net 978 Programme on standardizing pEp. [ISOC.bnet] 980 15. References 982 15.1. Normative References 984 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 985 Requirement Levels", BCP 14, RFC 2119, 986 DOI 10.17487/RFC2119, March 1997, 987 . 989 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 990 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 991 . 993 [RFC7435] Dukhovni, V., "Opportunistic Security: Some Protection 994 Most of the Time", RFC 7435, DOI 10.17487/RFC7435, 995 December 2014, . 997 15.2. Informative References 999 [I-D.birk-pep-trustwords] 1000 Hoeneisen, B. and H. Marques, "IANA Registration of 1001 Trustword Lists: Guide, Template and IANA Considerations", 1002 draft-birk-pep-trustwords-04 (work in progress), July 1003 2019. 1005 [I-D.hoeneisen-pep-keysync] 1006 Hoeneisen, B. and H. Marques, "pretty Easy privacy (pEp): 1007 Key Synchronization Protocol", draft-hoeneisen-pep- 1008 keysync-00 (work in progress), July 2019. 1010 [I-D.marques-pep-email] 1011 Marques, H., "pretty Easy privacy (pEp): Email Formats and 1012 Protocols", draft-marques-pep-email-02 (work in progress), 1013 October 2018. 1015 [I-D.marques-pep-handshake] 1016 Marques, H. and B. Hoeneisen, "pretty Easy privacy (pEp): 1017 Contact and Channel Authentication through Handshake", 1018 draft-marques-pep-handshake-03 (work in progress), July 1019 2019. 1021 [I-D.marques-pep-rating] 1022 Marques, H. and B. Hoeneisen, "pretty Easy privacy (pEp): 1023 Mapping of Privacy Rating", draft-marques-pep-rating-02 1024 (work in progress), July 2019. 1026 [ISOC.bnet] 1027 Simao, I., "Beyond the Net. 12 Innovative Projects 1028 Selected for Beyond the Net Funding. Implementing Privacy 1029 via Mass Encryption: Standardizing pretty Easy privacy's 1030 protocols", June 2017, . 1034 [OpenPGP] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R. 1035 Thayer, "OpenPGP Message Format", RFC 4880, 1036 DOI 10.17487/RFC4880, November 2007, 1037 . 1039 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 1040 Communication Layers", STD 3, RFC 1122, 1041 DOI 10.17487/RFC1122, October 1989, 1042 . 1044 [RFC7258] Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an 1045 Attack", BCP 188, RFC 7258, DOI 10.17487/RFC7258, May 1046 2014, . 1048 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1049 Code: The Implementation Status Section", BCP 205, 1050 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1051 . 1053 [RFC8280] ten Oever, N. and C. Cath, "Research into Human Rights 1054 Protocol Considerations", RFC 8280, DOI 10.17487/RFC8280, 1055 October 2017, . 1057 [SRC.enigmailpep] 1058 "Source code for Enigmail/pEp", July 2019, 1059 . 1061 [SRC.pepcore] 1062 "Core source code and reference implementation of pEp 1063 (engine and adapters)", July 2018, 1064 . 1066 [SRC.pepforandroid] 1067 "Source code for pEp for Android", July 2019, 1068 . 1070 [SRC.pepforios] 1071 "Source code for pEp for iOS", July 2019, 1072 . 1074 [SRC.pepforoutlook] 1075 "Source code for pEp for Outlook", July 2019, 1076 . 1078 Appendix A. Code Excerpts 1080 This section provides excerpts of the running code from the pEp 1081 reference implementation pEp engine (C99 programming language). 1083 A.1. pEp Identity 1085 How the pEp identity is defined in the data structure (cf. src/ 1086 pEpEngine.h): 1088 typedef struct _pEp_identity { 1089 char *address; // C string with address UTF-8 encoded 1090 char *fpr; // C string with fingerprint UTF-8 1091 // encoded 1092 char *user_id; // C string with user ID UTF-8 encoded 1093 char *username; // C string with user name UTF-8 1094 // encoded 1095 PEP_comm_type comm_type; // type of communication with this ID 1096 char lang[3]; // language of conversation 1097 // ISO 639-1 ALPHA-2, last byte is 0 1098 bool me; // if this is the local user 1099 // herself/himself 1100 identity_flags_t flags; // identity_flag1 | identity_flag2 1101 // | ... 1102 } pEp_identity; 1104 A.1.1. Corresponding SQL 1106 Relational table scheme excerpts (in SQL) used in current pEp 1107 implementations, held locally for every pEp installation in a SQLite 1108 database: 1110 CREATE TABLE person ( 1111 id text primary key, 1112 username text not null, 1113 main_key_id text 1114 references pgp_keypair (fpr) 1115 on delete set null, 1116 lang text, 1117 comment text, 1118 device_group text, 1119 is_pep_user integer default 0 1120 ); 1122 CREATE TABLE identity ( 1123 address text, 1124 user_id text 1125 references person (id) 1126 on delete cascade on update cascade, 1127 main_key_id text 1128 references pgp_keypair (fpr) 1129 on delete set null, 1130 comment text, 1131 flags integer default 0, 1132 is_own integer default 0, 1133 timestamp integer default (datetime('now')), 1134 primary key (address, user_id) 1135 ); 1137 CREATE TABLE pgp_keypair ( 1138 fpr text primary key, 1139 created integer, 1140 expires integer, 1141 comment text, 1142 flags integer default 0 1143 ); 1144 CREATE INDEX pgp_keypair_expires on pgp_keypair ( 1145 expires 1146 ); 1148 A.2. pEp Communication Type 1150 In the following, is an example for the rating of communication types 1151 as defined by a data structure (cf. src/pEpEngine.h [SRC.pepcore]): 1153 typedef enum _PEP_comm_type { 1154 PEP_ct_unknown = 0, 1156 // range 0x01 to 0x09: no encryption, 0x0a to 0x0e: 1157 // nothing reasonable 1158 PEP_ct_no_encryption = 0x01, // generic 1159 PEP_ct_no_encrypted_channel = 0x02, 1160 PEP_ct_key_not_found = 0x03, 1161 PEP_ct_key_expired = 0x04, 1162 PEP_ct_key_revoked = 0x05, 1163 PEP_ct_key_b0rken = 0x06, 1164 PEP_ct_my_key_not_included = 0x09, 1166 PEP_ct_security_by_obscurity = 0x0a, 1167 PEP_ct_b0rken_crypto = 0x0b, 1168 PEP_ct_key_too_short = 0x0c, 1170 PEP_ct_compromized = 0x0e, // known compromized connection 1171 PEP_ct_mistrusted = 0x0f, // known mistrusted key 1173 // range 0x10 to 0x3f: unconfirmed encryption 1175 PEP_ct_unconfirmed_encryption = 0x10, // generic 1176 PEP_ct_OpenPGP_weak_unconfirmed = 0x11, // RSA 1024 is weak 1178 PEP_ct_to_be_checked = 0x20, // generic 1179 PEP_ct_SMIME_unconfirmed = 0x21, 1180 PEP_ct_CMS_unconfirmed = 0x22, 1182 PEP_ct_strong_but_unconfirmed = 0x30, // generic 1183 PEP_ct_OpenPGP_unconfirmed = 0x38, // key at least 2048 bit 1184 // RSA or EC 1185 PEP_ct_OTR_unconfirmed = 0x3a, 1187 // range 0x40 to 0x7f: unconfirmed encryption and anonymization 1189 PEP_ct_unconfirmed_enc_anon = 0x40, // generic 1190 PEP_ct_pEp_unconfirmed = 0x7f, 1192 PEP_ct_confirmed = 0x80, // this bit decides if trust 1193 // is confirmed 1195 // range 0x81 to 0x8f: reserved 1196 // range 0x90 to 0xbf: confirmed encryption 1198 PEP_ct_confirmed_encryption = 0x90, // generic 1199 PEP_ct_OpenPGP_weak = 0x91, // RSA 1024 is weak (unused) 1201 PEP_ct_to_be_checked_confirmed = 0xa0, //generic 1202 PEP_ct_SMIME = 0xa1, 1203 PEP_ct_CMS = 0xa2, 1205 PEP_ct_strong_encryption = 0xb0, // generic 1206 PEP_ct_OpenPGP = 0xb8, // key at least 2048 bit RSA or EC 1207 PEP_ct_OTR = 0xba, 1209 // range 0xc0 to 0xff: confirmed encryption and anonymization 1211 PEP_ct_confirmed_enc_anon = 0xc0, // generic 1212 PEP_ct_pEp = 0xff 1213 } PEP_comm_type; 1215 A.3. Abstract Crypto API examples 1217 The following code excerpts are from the pEp Engine reference 1218 implementation, to be found in src/message_api.h. 1220 [[ Note: Just a selection; more functionality is available. ]] 1222 A.3.1. Encrypting a Message 1224 Cf. src/message_api.h [SRC.pepcore]: 1226 // encrypt_message() - encrypt message in memory 1227 // 1228 // parameters: 1229 // session (in) session handle 1230 // src (in) message to encrypt 1231 // extra (in) extra keys for encryption 1232 // dst (out) pointer to new encrypted message or NULL if 1233 // no encryption could take place 1234 // enc_format (in) encrypted format 1235 // flags (in) flags to set special encryption features 1236 // 1237 // return value: 1238 // PEP_STATUS_OK on success 1239 // PEP_KEY_HAS_AMBIG_NAME at least one of the recipient 1240 // keys has an ambiguous name 1241 // PEP_UNENCRYPTED no recipients with usable key, 1242 // message is left unencrypted, 1243 // and key is attached to it 1244 // 1245 // caveat: 1246 // the ownership of src remains with the caller 1247 // the ownership of dst goes to the caller 1248 DYNAMIC_API PEP_STATUS encrypt_message( 1249 PEP_SESSION session, 1250 message *src, 1251 stringlist_t *extra, 1252 message **dst, 1253 PEP_enc_format enc_format, 1254 PEP_encrypt_flags_t flags 1255 ); 1257 Cf. src/message_api.h [SRC.pepcore]: 1259 A.3.2. Decrypting a Message 1261 Cf. src/message_api.h [SRC.pepcore]: 1263 // decrypt_message() - decrypt message in memory 1264 // 1265 // parameters: 1266 // session (in) session handle 1267 // src (in) message to decrypt 1268 // dst (out) pointer to new decrypted message 1269 // or NULL on failure 1270 // keylist (out) stringlist with keyids 1271 // rating (out) rating for the message 1272 // flags (out) flags to signal special decryption features 1273 // 1274 // return value: 1275 // error status 1276 // or PEP_DECRYPTED if message decrypted but not verified 1277 // or PEP_CANNOT_REENCRYPT if message was decrypted (and 1278 // possibly verified) but a reencryption operation is 1279 // expected by the caller and failed 1280 // or PEP_STATUS_OK on success 1281 // 1282 // flag values: 1283 // in: 1284 // PEP_decrypt_flag_untrusted_server 1285 // used to signal that decrypt function should engage in 1286 // behaviour specified for when the server storing the 1287 // source is untrusted 1288 // out: 1289 // PEP_decrypt_flag_own_private_key 1290 // private key was imported for one of our addresses 1291 // (NOT trusted or set to be used - handshake/trust is 1292 // required for that) 1293 // PEP_decrypt_flag_src_modified 1294 // indicates that the src object has been modified. At 1295 // the moment, this is always as a direct result of the 1296 // behaviour driven by the input flags. This flag is the 1297 // ONLY value that should be relied upon to see if such 1298 // changes have taken place. 1299 // PEP_decrypt_flag_consume 1300 // used by sync 1301 // PEP_decrypt_flag_ignore 1302 // used by sync 1303 // 1304 // 1305 // caveat: 1306 // the ownership of src remains with the caller - however, the 1307 // contents might be modified (strings freed and allocated anew 1308 // or set to NULL, etc) intentionally; when this happens, 1309 // PEP_decrypt_flag_src_modified is set. 1310 // the ownership of dst goes to the caller 1311 // the ownership of keylist goes to the caller 1312 // if src is unencrypted this function returns PEP_UNENCRYPTED 1313 // and sets 1314 // dst to NULL 1315 DYNAMIC_API PEP_STATUS decrypt_message( 1316 PEP_SESSION session, 1317 message *src, 1318 message **dst, 1319 stringlist_t **keylist, 1320 PEP_rating *rating, 1321 PEP_decrypt_flags_t *flags 1323 ); 1325 A.3.3. Obtain Common Trustwords 1327 Cf. src/message_api.h [SRC.pepcore]: 1329 // get_trustwords() - get full trustwords string 1330 // for a *pair* of identities 1331 // 1332 // parameters: 1333 // session (in) session handle 1334 // id1 (in) identity of first party in communication 1335 // - fpr can't be NULL 1336 // id2 (in) identity of second party in communication 1337 // - fpr can't be NULL 1338 // lang (in) C string with ISO 639-1 language code 1339 // words (out) pointer to C string with all trustwords 1340 // UTF-8 encoded, separated by a blank each 1341 // NULL if language is not supported or 1342 // trustword wordlist is damaged or unavailable 1343 // wsize (out) length of full trustwords string 1344 // full (in) if true, generate ALL trustwords for these 1345 // identities. 1346 // else, generate a fixed-size subset. 1347 // (TODO: fixed-minimum-entropy subset 1348 // in next version) 1349 // 1350 // return value: 1351 // PEP_STATUS_OK trustwords retrieved 1352 // PEP_OUT_OF_MEMORY out of memory 1353 // PEP_TRUSTWORD_NOT_FOUND at least one trustword not found 1354 // 1355 // caveat: 1356 // the word pointer goes to the ownership of the caller 1357 // the caller is responsible to free() it 1358 // (on Windoze use pEp_free()) 1359 // 1360 DYNAMIC_API PEP_STATUS get_trustwords( 1361 PEP_SESSION session, const pEp_identity* id1, 1362 const pEp_identity* id2, const char* lang, 1363 char **words, size_t *wsize, bool full 1364 ); 1366 Appendix B. Document Changelog 1368 [[ RFC Editor: This section is to be removed before publication ]] 1370 o draft-birk-pep-04: 1372 * Fix internal reference 1374 * Add IANA Considerations section 1376 * Add other use case of Extra Keys 1378 * Add Claudio Luck as author 1380 * Incorporate review changes by Kelly Bristol and Nana 1381 Karlstetter 1383 o draft-birk-pep-03: 1385 * Major restructure of the document 1387 * Adapt authors to the actual authors and extend Acknowledgments 1388 section 1390 * Added several new sections, e.g., Key Reset, Trust Revoke, 1391 Trust Synchronization, Private Key Export / Import, Privacy 1392 Considerations (content yet mostly TODO) 1394 * Added reference to HRPC work / RFC8280 1396 + Added text and figure to better explain pEp's automated Key 1397 Exchange and Trust management (basic message flow) 1399 * Lots of improvement in text and editorial changes 1401 o draft-birk-pep-02: 1403 * Move (updated) code to Appendix 1405 * Add Changelog to Appendix 1407 * Add Open Issue section to Appendix 1409 * Fix description of what Extra Keys are 1411 * Fix Passive Mode description 1413 * Better explain pEp's identity system 1415 o draft-birk-pep-01: 1417 * Mostly editorial 1419 o draft-birk-pep-00: 1421 * Initial version 1423 Appendix C. Open Issues 1425 [[ RFC Editor: This section should be empty and is to be removed 1426 before publication ]] 1428 o Shorten Introduction and Abstract 1430 o References to RFC6973 (Privacy Considerations) 1432 o Add references to prior work, and what differs here - PEM (cf. 1433 RFC1421-1424) 1435 o Better explain Passive Mode 1437 o Better explain / illustrate pEp's identity system 1439 o Explain Concept of Key Mapping (e.g. to S/MIME, which is to be 1440 refined in pEp application docs auch as pEp email 1441 [I-D.marques-pep-email]) 1443 o Add more information to deal with organizational requirements 1445 o Add text to Key Reset (Section 4.3) as well as reference as soon 1446 as available 1448 o Add text to Trust Revoke (Section 5.4) as well as reference as 1449 soon as available 1451 o Add text to Trust Synchronization (Section 6.2) as well as 1452 reference as soon as available 1454 o Add text to Privacy Considerations (Section 10) 1456 o Scan for leftovers of email-specific stuff and move it to pEp 1457 email I-D [I-D.marques-pep-email], while replacing it herein with 1458 generic descriptions. 1460 Authors' Addresses 1461 Hernani Marques 1462 pEp Foundation 1463 Oberer Graben 4 1464 CH-8400 Winterthur 1465 Switzerland 1467 Email: hernani.marques@pep.foundation 1468 URI: https://pep.foundation/ 1470 Claudio Luck 1471 pEp Foundation 1472 Oberer Graben 4 1473 CH-8400 Winterthur 1474 Switzerland 1476 Email: claudio.luck@pep.foundation 1477 URI: https://pep.foundation/ 1479 Bernie Hoeneisen 1480 Ucom Standards Track Solutions GmbH 1481 CH-8046 Zuerich 1482 Switzerland 1484 Phone: +41 44 500 52 40 1485 Email: bernie@ietf.hoeneisen.ch (bernhard.hoeneisen AT ucom.ch) 1486 URI: https://ucom.ch/