idnits 2.17.1 draft-birk-pep-05.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 (November 04, 2019) is 1606 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 1104 ** 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 (-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 (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group V. Birk 3 Internet-Draft H. Marques 4 Intended status: Standards Track B. Hoeneisen 5 Expires: May 7, 2020 pEp Foundation 6 November 04, 2019 8 pretty Easy privacy (pEp): Privacy by Default 9 draft-birk-pep-05 11 Abstract 13 The pretty Easy privacy (pEp) model and protocols describe a set of 14 conventions for the automation of operations traditionally seen as 15 barriers to the use and deployment of secure, privacy-preserving end- 16 to-end interpersonal messaging. These include, but are not limited 17 to, key management, key discovery, and private key handling 18 (including peer-to-peer synchronization of private keys and other 19 user data across devices). Human Rights-enabling principles like 20 Data Minimization, End-to-End and Interoperability are explicit 21 design goals. For the goal of usable privacy, pEp introduces means 22 to verify communication between peers and proposes a trust-rating 23 system to denote secure types of communications and signal the 24 privacy level available on a per-user and per-message level. 25 Significantly, the pEp protocols build on already available security 26 formats and message transports (e.g., PGP/MIME with email), and are 27 written with the intent to be interoperable with already widely- 28 deployed systems in order to ease adoption and implementation. This 29 document outlines the general design choices and principles of pEp. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at https://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on May 7, 2020. 48 Copyright Notice 50 Copyright (c) 2019 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (https://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 1.1. Relationship to other pEp documents . . . . . . . . . . . 5 67 1.2. Requirements Language . . . . . . . . . . . . . . . . . . 5 68 1.3. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 5 69 2. Protocol's Core Design Principles . . . . . . . . . . . . . . 6 70 2.1. Privacy by Default . . . . . . . . . . . . . . . . . . . 6 71 2.2. Data Minimization . . . . . . . . . . . . . . . . . . . . 7 72 2.3. Interoperability . . . . . . . . . . . . . . . . . . . . 7 73 2.4. Peer-to-Peer . . . . . . . . . . . . . . . . . . . . . . 7 74 2.5. User Interaction . . . . . . . . . . . . . . . . . . . . 8 75 3. Identity System . . . . . . . . . . . . . . . . . . . . . . . 8 76 3.1. User . . . . . . . . . . . . . . . . . . . . . . . . . . 9 77 3.2. Address . . . . . . . . . . . . . . . . . . . . . . . . . 9 78 3.3. Key . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 79 3.4. 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 . . . . . . . . . . . . . . . . . . . . . . . 33 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 fingerprints 234 as a fallback). 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 NOT expose users to technical terms and 339 views, especially those specific to cryptography, like "keys", 340 "certificates", or "fingerprints". Users may explicitly opt-in to 341 see such terms wanting seeking for more options; i.e., advanced 342 settings MAY be available, and in some cases, these options may be 343 required. 345 The authors believe that widespread adoption of end-to-end 346 cryptography is possible if users are not required to understand 347 cryptography and key management. This belief forms the central goal 348 of pEp, which is that users can simply rely on the principles of 349 Privacy by Default. 351 On the other hand, to preserve usability, users MUST NOT be required 352 to wait for cryptographic tasks such as key generation to complete 353 before being able to use their respective message client for its 354 default purpose. In short, pEp implementers MUST ensure that the 355 ability to draft, send, and receive messages is always preserved, 356 even if that means a message is sent unencrypted, in accordance with 357 the Opportunistic Security approach outlined in [RFC7435]. 359 In turn, pEp implementers MUST ensure that a distinguishable privacy 360 status is clearly visible to the user, both on a per-contact as well 361 as per-message level. This allows users to assess both the privacy 362 level for the message and the trust level of its intended recipients 363 before choosing to send it. 365 [[ *NOTE*: We are aware of the fact that usually UX requirements are 366 not part of RFCs. However, in order to encourage massive adoption of 367 secure end-to-end encryption while at the same time avoiding putting 368 users at risk, we believe certain straightforward signaling 369 requirements for users to be a good idea, just as it is currently 370 done for already-popular instant messaging services. ]] 372 3. Identity System 374 Everyone has the right to choose how to reveal themselves to the 375 world, both offline and online. This is an important element to 376 maintain psychological, physical, and digital privacy. As such, pEp 377 users MUST have the option to choose their identity, and they MUST 378 have the ability to maintain multiple identities. 380 These different identities MUST NOT be externally correlatable with 381 each other by default. On the other hand, combining different 382 identities when such information is known MUST be supported (alias 383 support). 385 3.1. User 387 A user is a real world human being or a group of human beings. If it 388 is a single human being, it can be called person. 390 A user is identified by a user ID (user_id). The user_id SHOULD be a 391 UUID, it MAY be an arbitrary unique string. 393 The own user can have a user_id like all other users. If the own 394 user does not have a user_id, then it is assigned a "pEp_own_userId" 395 instead. 397 A user can have a default key. [[ TODO: Provide ref explaining this. 398 ]] 400 3.2. Address 402 A pEp address is a network address, e.g., an SMTP address or another 403 Universal Resource Identifier (URI). 405 [[ Note: It might be necessary to introduce further addressing 406 schemes through IETF contributions or IANA registrations, e.g., 407 implementing pEp to bridge to popular messaging services with no URIs 408 defined. ]] 410 3.3. Key 412 A key is an OpenPGP-compatible asymmetric cryptographic key pair. 414 Keys in pEp are identified by the full fingerprint (fpr) of the 415 public key. The fingerprint is to be obtained from the specific 416 cryptographic service used to handle the keys. The canonical 417 representation in pEp is upper-case hexadecimal with zero-padding and 418 no separators or spaces. 420 3.4. Identity 422 An identity is a representation of a user, encapsulating how this 423 user appears within the network of a messaging system. This 424 representation may or may not be pseudonymous in nature. 426 An identity is defined by mapping a user_id to an address. If no 427 user_id is known, it is guessed by mapping a username to an address. 429 An identity can have a temporary user_id as a placeholder until a 430 real user_id is known. 432 In pEp a different key pair for each (e.g., email) account MUST be 433 created. This allows a user to retain different identities, which 434 are not correlated by the usage of the same key for all of those. 435 This is beneficial in terms of privacy. 437 A user MAY have a default key; each identity a user has MAY have a 438 default key (of its own). When both an Identity and the related User 439 have a default key set, the Identity's default key MUST override the 440 User's default key. 442 [[ TODO: Provide ref explaining this. ]] 444 In Appendix A.1, the definition of a pEp identity can be found 445 according to the reference implementation by the pEp engine. 447 4. Key Management 449 In order to achieve the goal of widespread adoption of secure 450 communications, key management in pEp MUST be automated. 452 4.1. Key Generation 454 A pEp implementation MUST ensure that cryptographic keys for every 455 configured identity are available. If a corresponding key pair for 456 the identity of a user is found and said identity fulfills the 457 requirements (e.g., for email, as set out in 458 [I-D.marques-pep-email]), said key pair MUST be reused. Otherwise a 459 new key pair MUST be generated. This may be carried out instantly 460 upon its configuration. 462 On devices with limited processing power (e.g., mobile devices) the 463 key generation may take more time than a user is willing to wait. If 464 this is the case, users SHOULD NOT be stopped from communicating, 465 i.e., the key generation process SHOULD be carried out in the 466 background. 468 4.2. Private Keys 470 4.2.1. Storage 472 Private keys in pEp implementations MUST always be held on the end 473 user's device(s): pEp implementers MUST NOT rely on private keys 474 stored in centralized remote locations. This applies even for key 475 storages where the private keys are protected with sufficiently long 476 passphrases. It is considered a violation of pEp's P2P design 477 principle to rely on centralized infrastructures (cf. Section 2.4). 478 This also applies for pEp implementations created for applications 479 not residing on a user's device (e.g., web-based MUAs). In such 480 cases, pEp implementations MUST be done in a way such that the 481 locally-held private key can neither be directly accessed nor leaked 482 to the outside world. 484 [[ Note: It is particularly important that browser add-ons 485 implementing pEp functionality do not obtain their cryptographic code 486 from a centralized (cloud) service, as this must be considered a 487 centralized attack vector allowing for backdoors, negatively 488 impacting privacy. ]] 490 Cf. Section 6.1 for a means to synchronize private keys among 491 different devices of the same network address in a secure manner. 493 4.2.2. Passphrase 495 Passphrases to protect a user's private key MUST be supported by pEp 496 implementations, but MUST NOT be enforced by default. That is, if a 497 pEp implementation finds a suitable (i.e., secure enough) 498 cryptographic setup, which uses passphrases, pEp implementations MUST 499 provide a way to unlock the key. However, if a new key pair is 500 generated for a given identity, no passphrase MUST be put in place. 501 The authors assume that the enforcement of secure (i.e., unique and 502 long enough) passphrases would massively reduce the number of pEp 503 users (by hassling them), while providing little to no additional 504 privacy for the common cases of passive monitoring being carried out 505 by corporations or state-level actors. 507 4.3. Key Reset 509 4.4. Public Key Distribution 511 As the key is available (cf. Section 4.1) implementers of pEp are 512 REQUIRED to ensure that the identity's public key is attached to 513 every outgoing message. However, this MAY be omitted if the peer has 514 previously received a message encrypted with the public key of the 515 sender. 517 The sender's public key SHOULD be sent encrypted whenever possible, 518 i.e., when a public key of the receiving peer is available. If no 519 encryption key of the recipient is available, the sender's public key 520 MAY be sent unencrypted. In either case, this approach ensures that 521 messaging clients (e.g., MUAs that at least implement OpenPGP) do not 522 need to have pEp implemented to see a user's public key. Such peers 523 thus have the chance to (automatically) import the sender's public 524 key. 526 If there is already a known public key from the sender of a message 527 and it is still valid and not expired, new keys MUST NOT be used for 528 future communication unless they are signed by the previous key (to 529 avoid a MITM attack). Messages MUST always be encrypted with the 530 receiving peer's oldest public key, as long as it is valid and not 531 expired. 533 4.4.1. UX Considerations 535 Implementers of pEp SHALL prevent the display of public keys attached 536 to messages (e.g, in email) to the user in order to prevent user 537 confusion by files they are potentially unaware of how to handle. 539 4.4.2. No addition of unnecessary metadata 541 Metadata, such as email headers, MUST NOT be added in order to 542 announce a user's public key. This is considered unnecessary 543 information leakage, may affect user privacy, and may be subject to a 544 country's data retention laws (cf. Section 2.2). Furthermore, this 545 may affect interoperability to existing users that have no knowledge 546 of such header fields, such as users of OpenPGP in email, and lose 547 the ability to import any keys distributed in this way as a result. 548 The ability to extract and receive public keys from such metadata 549 SHOULD be supported, however, in the event these approaches become 550 widespread. 552 4.4.3. No centralized public key storage or retrieval by default 554 Keyservers or generally intermediate approaches to obtain a peer's 555 public key SHALL NOT be used by default. On the other hand, the user 556 MAY be provided with the option to opt-in for remote locations to 557 obtain keys, considering the widespread adoption of such approaches 558 for key distribution. 560 Keys generated or obtained by pEp clients MUST NOT be uploaded to any 561 (intermediate) keystore locations without the user's explicit 562 consent. 564 4.4.4. Example message flow 566 The following example roughly describes a pEp scenario with a typical 567 initial message flow to demonstrate key exchange and basic trust 568 management: 570 The following example describes a pEp scenario between two users - 571 Alice and Bob - in order to demonstrate the message flow that occurs 572 when exchanging keys and determining basic trust management for the 573 first time: 575 1. Alice - knowing nothing of Bob - sends a message to Bob. As Alice 576 has no public key from Bob, this message is sent out unencrypted. 577 However, Alice's public key is automatically attached. 579 2. Bob receives Alice's message and her public key. He is able to 580 reply to her and encrypt the message. His public key is 581 automatically attached to the message. Because he has her public 582 key now, Alice's rating in his message client changes to 583 'encrypted'. From a UX perspective, this status is displayed in 584 yellow (cf. Section 5.3). 586 3. Alice receives Bob's key. As of now Alice is also able to send 587 secure messages to Bob. The rating for Bob changes to "encrypted" 588 (with yellow color) in Alice's messaging client (cf. 589 Section 5.3). 591 4. Alice receives Bob's reply with his public key attached. Now, 592 Alice can send secure messages to Bob as well. The rating for 593 Bob changes to yellow, or 'encrypted', in Alice's messaging 594 client Section 5.3. 596 5. If Alice and Bob want to prevent man-in-the-middle (MITM) 597 attacks, they can engage in a pEp Handshake comparing their so- 598 called Trustwords (cf. Section 5.2) and confirm this process if 599 those match. After doing so, their identity rating changes to 600 "encrypted and authenticated" (cf. Section 5.3), which (UX-wise) 601 can be displayed using a green color. See also Section 5. 603 6. Alice and Bob can encrypt now, but they are not yet 604 authenticated, leaving them vulnerable to man-in-the-middle 605 (MitM) attacks. To prevent this from occurring, Alice and Bob 606 can engage in a pEp Handshake to compare their Trustwords (cf. 607 Section 5.2) and confirm if they match. After this step is 608 performed, their respective identity ratings change to "encrypted 609 and authenticated", which is represented by a green color (cf. 610 Section 5. 612 ----- ----- 613 | A | | B | 614 ----- ----- 615 | | 616 +------------------------+ +------------------------+ 617 | auto-generate key pair | | auto-generate key pair | 618 | (if no key yet) | | (if no key yet) | 619 +------------------------+ +------------------------+ 620 | | 621 +-----------------------+ +-----------------------+ 622 | Privacy Status for B: | | Privacy Status for A: | 623 | *Unencrypted* | | *Unencrypted* | 624 +-----------------------+ +-----------------------+ 625 | | 626 | A sends message to B (Public Key | 627 | attached) / optionally signed, but | 628 | NOT ENCRYPTED | 629 +------------------------------------------>| 630 | | 631 | +-----------------------+ 632 | | Privacy Status for A: | 633 | | *Encrypted* | 634 | +-----------------------+ 635 | | 636 | B sends message to A (Public Key | 637 | attached) / signed and ENCRYPTED | 638 |<------------------------------------------+ 639 | | 640 +-----------------------+ | 641 | Privacy Status for B: | | 642 | *Encrypted* | | 643 +-----------------------+ | 644 | | 645 | A and B successfully compare their | 646 | Trustwords over an alternative channel | 647 | (e.g., phone line) | 648 |<-- -- -- -- -- -- -- -- -- -- -- -- -- -->| 649 | | 650 +-----------------------+ +-----------------------+ 651 | Privacy Status for B: | | Privacy Status for A: | 652 | *Trusted* | | *Trusted* | 653 +-----------------------+ +-----------------------+ 654 | | 656 4.5. Key Reset 658 [[ TODO: This section will explain how to deal with invalid keys, 659 e.g., if expired or (potentially) leaked. ]] 661 5. Trust Management 663 [[ TODO: Intro ]] 665 5.1. Privacy Status 667 The trust status for an identity can change due to a number of 668 factors. These shifts will cause the color code assigned to this 669 identity to change accordingly, and is applied to future 670 communications with this identity. 672 For end-users, the most important component of pEp, which MUST be 673 made visible on a per-recipient and per-message level, is the Privacy 674 Status. 676 By colors, symbols and texts a user SHALL immediately understand how 677 private 679 o a communication channel with a given peer was or ought to be and 681 o a given message was or ought to be. 683 5.2. Handshake 685 To establishing trust between peers and to upgrade Privacy Status, 686 pEp defines a handshake, which is specified in 687 [I-D.marques-pep-handshake]. 689 In pEp, Trustwords [I-D.birk-pep-trustwords] are used for users to 690 compare the authenticity of peers in order to mitigate MITM attacks. 692 By default, Trustwords MUST be used to represent two peers' 693 fingerprints of their public keys in pEp implementations. 695 In order to retain compatibility with peers not using pEp 696 implementations (e.g., Mail User Agents (MUAs) with OpenPGP 697 implementations without Trustwords), it is REQUIRED that pEp 698 implementers give the user the choice to show both peers' 699 fingerprints instead of just their common Trustwords. 701 5.3. Trust Rating 703 pEp includes a Trust Rating system defining Rating and Color Codes to 704 express the Privacy Status of a peer or message 705 [I-D.marques-pep-rating]. The ratings are labeled, e.g., as 706 "Unencrypted", "Encrypted", "Trusted", "Under Attack", etc. The 707 Privacy Status in its most general form is expressed with traffic 708 lights semantics (and respective symbols and texts), whereas the 709 three colors yellow, green and red can be applied for any peer or 710 message - like this immediately indicating how secure and trustworthy 711 (and thus private) a communication was or ought to be considered. 713 The pEp Trust Rating system with all its states and respective 714 representations to be followed is outlined in 715 [I-D.marques-pep-rating]. 717 Note: An example for the rating of communication types, the 718 definition of the data structure by the pEp Engine reference 719 implementation is provided in Appendix A.2. 721 5.4. Trust Revoke 723 [[ TODO: This section will explain how to deal with the situation 724 when a peer can no longer be trusted, e.g., if a peer's device is 725 compromised. ]] 727 6. Synchronization 729 An important feature of pEp is to assist the user to run pEp 730 applications on different devices, such as personal computers, mobile 731 phones and tablets, at the same time. Therefore, state needs to be 732 synchronized among the different devices. 734 6.1. Private Key Synchronization 736 The pEp KeySync protocol (cf. [I-D.hoeneisen-pep-keysync]) is a 737 decentralized proposition which defines how pEp users can distribute 738 their private keys among their different devices in a user- 739 authenticated manner. This allows users to read their messages 740 across their various devices, as long as they share a common address, 741 such as an email account. 743 6.2. Trust Synchronization 745 [[ TODO: This section will explain how trust and other related state 746 is synchronized among different devices in a user-authenticated 747 manner. ]] 749 7. Interoperability 751 pEp aims to be interoperable with existing applications designed to 752 enable privacy, e.g., OpenPGP and S/MIME in email. 754 8. Options in pEp 756 In this section a non-exhaustive selection of options is provided. 758 8.1. Option "Passive Mode" 760 By default, the sender attaches its public key to any outgoing 761 message (cf. Section 4.4). For situations where a sender wants to 762 ensure that it only attaches a public key to an Internet user which 763 has a pEp implementation, a Passive Mode MUST be made available. 765 8.2. Option "Disable Protection" 767 Using this option, protection can be disabled generally or 768 selectively. Implementers of pEp MUST provide an option "Disable 769 Protection" to allow a user to disable encryption and signing for: 771 1. all communication 773 2. specific contacts 775 3. specific messages 777 The public key still attached, unless the option "Passive Mode" (cf. 778 Section 8.1) is activated at the same time. 780 8.3. Option "Extra Keys" 782 8.3.1. Use Case for Organizations 784 For internal or enterprise environments, authorized personnel may 785 need to centrally decrypt user messages for archival or other legal 786 purposes. Therefore, pEp implementers MAY provide an "Extra Keys" 787 option in which a message is encrypted with at least one additional 788 public key. The corresponding secret key(s) are intended to be 789 secured by CISO staff or other authorized personnel for the 790 organization. 792 However, it is crucial that the "Extra Keys" feature MUST NOT be 793 activated by default for any network address, and is intended to be 794 an option used only for organization-specific identities, as well as 795 their corresponding network addresses and accounts. The "Extra Keys" 796 feature SHOULD NOT be applied to the private identities, addresses, 797 or accounts a user might possess once it is activated. 799 8.3.2. Use Case for Key Synchronization 801 The "Extra Keys" feature also plays a role during pEp's KeySync 802 protocols, where the additional keys are used to decipher message 803 transactions by both parties involved during the negotiation process 804 for private key synchronization. During the encrypted (but 805 untrusted) transactions, KeySync messages are not just encrypted with 806 the sending device's default key, but also with the default keys of 807 both parties involved in the synchronization process. 809 8.4. Option "Blacklist Keys" 811 A "Blacklist Keys" option MAY be provided for an advanced user, 812 allowing them to disable keys of peers that they no longer want to 813 use in new communications. However, the keys SHALL NOT be deleted. 814 It MUST still be possible to verify and decipher past communications 815 that used these keys. 817 9. Security Considerations 819 By attaching the sender's public key to outgoing messages, Trust on 820 First Use (TOFU) is established. However, this is prone to MITM 821 attacks. Cryptographic key subversion is considered Pervasive 822 Monitoring (PM) according to [RFC7258]. Those attacks can be 823 mitigated, if the involved users compare their common Trustwords. 824 This possibility MUST be made easily accessible to pEp users in the 825 user interface implementation. If for compatibility reasons (e.g., 826 with OpenPGP users) no Trustwords can be used, then a comparatively 827 easy way to verify the respective public key fingerprints MUST be 828 implemented. 830 As the use of passphrases for private keys is not advised, devices 831 themselves SHOULD use encryption. 833 10. Privacy Considerations 835 [[ TODO ]] 837 11. IANA Considerations 839 This document has no actions for IANA. 841 12. Implementation Status 843 12.1. Introduction 845 This section records the status of known implementations of the 846 protocol defined by this specification at the time of posting of this 847 Internet-Draft, and is based on a proposal described in [RFC7942]. 848 The description of implementations in this section is intended to 849 assist the IETF in its decision processes in progressing drafts to 850 RFCs. Please note that the listing of any individual implementation 851 here does not imply endorsement by the IETF. Furthermore, no effort 852 has been spent to verify the information presented here that was 853 supplied by IETF contributors. This is not intended as, and must not 854 be construed to be, a catalog of available implementations or their 855 features. Readers are advised to note that other implementations may 856 exist. 858 According to [RFC7942], "[...] this will allow reviewers and working 859 groups to assign due consideration to documents that have the benefit 860 of running code, which may serve as evidence of valuable 861 experimentation and feedback that have made the implemented protocols 862 more mature. It is up to the individual working groups to use this 863 information as they see fit." 865 12.2. Current software implementing pEp 867 The following software implementing the pEp protocols (to varying 868 degrees) already exists: 870 o pEp for Outlook as add-on for Microsoft Outlook, release 871 [SRC.pepforoutlook] 873 o pEp for Android (based on a fork of the K9 MUA), release 874 [SRC.pepforandroid] 876 o Enigmail/pEp as add-on for Mozilla Thunderbird, release 877 [SRC.enigmailpep] 879 o pEp for iOS (implemented in a new MUA), beta [SRC.pepforios] 881 pEp for Android, iOS and Outlook are provided by pEp Security, a 882 commercial entity specializing in end-user software implementing pEp 883 while Enigmail/pEp is pursued as community project, supported by the 884 pEp Foundation. 886 All software is available as Free Software and published also in 887 source form. 889 12.3. Reference implementation of pEp's core 891 The pEp Foundation provides a reference implementation of pEp's core 892 principles and functionalities, which go beyond the documentation 893 status of this Internet-Draft. [SRC.pepcore] 895 pEp's reference implementation is composed of pEp Engine and pEp 896 Adapters (or bindings), alongside with some libraries which pEp 897 Engine relies on to function on certain platforms (like a NetPGP fork 898 we maintain for the iOS platform). 900 The pEp engine is a Free Software library encapsulating 901 implementations of: 903 o Key Management 905 Key Management in pEp engine is based on GnuPG key chains (NetPGP 906 on iOS). Keys are stored in an OpenPGP compatible format and can 907 be used for different crypto implementations. 909 o Trust Rating 911 pEp engine is sporting a two phase trust rating system. In phase 912 one there is a rating based on channel, crypto and key security 913 named "comm_types". In phase 2 these are mapped to user 914 representable values which have attached colors to present them in 915 traffic light semantics. 917 o Abstract Crypto API 919 The Abstract Crypto API is providing functions to encrypt and 920 decrypt data or full messages without requiring an application 921 programmer to understand the different formats and standards. 923 o Message Transports 925 pEp engine will support a growing list of Message Transports to 926 support any widespread text messaging system including email, SMS, 927 XMPP and many more. 929 pEp engine is written in C99 programming language. It is not meant 930 to be used in application code directly. Instead, pEp engine is 931 coming together with a list of software adapters for a variety of 932 programming languages and development environments, which are: 934 o pEp COM Server Adapter 936 o pEp JNI Adapter 937 o pEp JSON Adapter 939 o pEp ObjC (and Swift) Adapter 941 o pEp Python Adapter 943 o pEp Qt Adapter 945 12.4. Abstract Crypto API examples 947 A selection of code excerpts from the pEp Engine reference 948 implementation (encrypt message, decrypt message, and obtain 949 trustwords) can be found in Appendix A.3. 951 13. Notes 953 The pEp logo and "pretty Easy privacy" are registered trademarks 954 owned by the non-profit pEp Foundation based in Switzerland. 956 Primarily, we want to ensure the following: 958 o Software using the trademarks MUST be backdoor-free. 960 o Software using the trademarks MUST be accompanied by a serious 961 (detailed) code audit carried out by a reputable third-party, for 962 any proper release. 964 The pEp Foundation will help to support any community-run (non- 965 commercial) project with the latter, be it organizationally or 966 financially. 968 Through this, the foundation wants to make sure that software using 969 the pEp trademarks is as safe as possible from a security and privacy 970 point of view. 972 14. Acknowledgments 974 The authors would like to thank the following people who provided 975 substantial contributions, helpful comments or suggestions for this 976 document: Alexey Melnikov, Athena Schumacher, Ben Campbell, Brian 977 Trammell, Bron Gondwana, Claudio Luck, Daniel Kahn Gillmor, Enrico 978 Tomae, Eric Rescorla, Gabriele Lenzini, Hans-Peter Dittler, Iraklis 979 Symeonidis, Kelly Bristol, Krista Bennett, Mirja Kuehlewind, Nana 980 Kerlstetter, Neal Walfield, Pete Resnick, Russ Housley, S. Shelburn, 981 and Stephen Farrel. 983 This work was initially created by pEp Foundation, and then reviewed 984 and extended with funding by the Internet Society's Beyond the Net 985 Programme on standardizing pEp. [ISOC.bnet] 987 15. References 989 15.1. Normative References 991 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 992 Requirement Levels", BCP 14, RFC 2119, 993 DOI 10.17487/RFC2119, March 1997, 994 . 996 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 997 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 998 . 1000 [RFC7435] Dukhovni, V., "Opportunistic Security: Some Protection 1001 Most of the Time", RFC 7435, DOI 10.17487/RFC7435, 1002 December 2014, . 1004 15.2. Informative References 1006 [I-D.birk-pep-trustwords] 1007 Hoeneisen, B. and H. Marques, "IANA Registration of 1008 Trustword Lists: Guide, Template and IANA Considerations", 1009 draft-birk-pep-trustwords-04 (work in progress), July 1010 2019. 1012 [I-D.hoeneisen-pep-keysync] 1013 Hoeneisen, B., Marques, H., and K. Bristol, "pretty Easy 1014 privacy (pEp): Key Synchronization Protocol (KeySync)", 1015 draft-hoeneisen-pep-keysync-01 (work in progress), October 1016 2019. 1018 [I-D.marques-pep-email] 1019 Marques, H., "pretty Easy privacy (pEp): Email Formats and 1020 Protocols", draft-marques-pep-email-02 (work in progress), 1021 October 2018. 1023 [I-D.marques-pep-handshake] 1024 Marques, H. and B. Hoeneisen, "pretty Easy privacy (pEp): 1025 Contact and Channel Authentication through Handshake", 1026 draft-marques-pep-handshake-03 (work in progress), July 1027 2019. 1029 [I-D.marques-pep-rating] 1030 Marques, H. and B. Hoeneisen, "pretty Easy privacy (pEp): 1031 Mapping of Privacy Rating", draft-marques-pep-rating-02 1032 (work in progress), July 2019. 1034 [ISOC.bnet] 1035 Simao, I., "Beyond the Net. 12 Innovative Projects 1036 Selected for Beyond the Net Funding. Implementing Privacy 1037 via Mass Encryption: Standardizing pretty Easy privacy's 1038 protocols", June 2017, . 1042 [OpenPGP] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R. 1043 Thayer, "OpenPGP Message Format", RFC 4880, 1044 DOI 10.17487/RFC4880, November 2007, 1045 . 1047 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 1048 Communication Layers", STD 3, RFC 1122, 1049 DOI 10.17487/RFC1122, October 1989, 1050 . 1052 [RFC7258] Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an 1053 Attack", BCP 188, RFC 7258, DOI 10.17487/RFC7258, May 1054 2014, . 1056 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1057 Code: The Implementation Status Section", BCP 205, 1058 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1059 . 1061 [RFC8280] ten Oever, N. and C. Cath, "Research into Human Rights 1062 Protocol Considerations", RFC 8280, DOI 10.17487/RFC8280, 1063 October 2017, . 1065 [SRC.enigmailpep] 1066 "Source code for Enigmail/pEp", July 2019, 1067 . 1069 [SRC.pepcore] 1070 "Core source code and reference implementation of pEp 1071 (engine and adapters)", July 2018, 1072 . 1074 [SRC.pepforandroid] 1075 "Source code for pEp for Android", July 2019, 1076 . 1078 [SRC.pepforios] 1079 "Source code for pEp for iOS", July 2019, 1080 . 1082 [SRC.pepforoutlook] 1083 "Source code for pEp for Outlook", July 2019, 1084 . 1086 Appendix A. Code Excerpts 1088 This section provides excerpts of the running code from the pEp 1089 reference implementation pEp engine (C99 programming language). 1091 A.1. pEp Identity 1093 How the pEp identity is defined in the data structure (cf. src/ 1094 pEpEngine.h): 1096 typedef struct _pEp_identity { 1097 char *address; // C string with address UTF-8 encoded 1098 char *fpr; // C string with fingerprint UTF-8 1099 // encoded 1100 char *user_id; // C string with user ID UTF-8 encoded 1101 char *username; // C string with user name UTF-8 1102 // encoded 1103 PEP_comm_type comm_type; // type of communication with this ID 1104 char lang[3]; // language of conversation 1105 // ISO 639-1 ALPHA-2, last byte is 0 1106 bool me; // if this is the local user 1107 // herself/himself 1108 identity_flags_t flags; // identity_flag1 | identity_flag2 1109 // | ... 1110 } pEp_identity; 1112 A.1.1. Corresponding SQL 1114 Relational table scheme excerpts (in SQL) used in current pEp 1115 implementations, held locally for every pEp installation in a SQLite 1116 database: 1118 CREATE TABLE person ( 1119 id text primary key, 1120 username text not null, 1121 main_key_id text 1122 references pgp_keypair (fpr) 1123 on delete set null, 1124 lang text, 1125 comment text, 1126 device_group text, 1127 is_pep_user integer default 0 1128 ); 1130 CREATE TABLE identity ( 1131 address text, 1132 user_id text 1133 references person (id) 1134 on delete cascade on update cascade, 1135 main_key_id text 1136 references pgp_keypair (fpr) 1137 on delete set null, 1138 comment text, 1139 flags integer default 0, 1140 is_own integer default 0, 1141 timestamp integer default (datetime('now')), 1142 primary key (address, user_id) 1143 ); 1145 CREATE TABLE pgp_keypair ( 1146 fpr text primary key, 1147 created integer, 1148 expires integer, 1149 comment text, 1150 flags integer default 0 1151 ); 1152 CREATE INDEX pgp_keypair_expires on pgp_keypair ( 1153 expires 1154 ); 1156 A.2. pEp Communication Type 1158 In the following, is an example for the rating of communication types 1159 as defined by a data structure (cf. src/pEpEngine.h [SRC.pepcore]): 1161 typedef enum _PEP_comm_type { 1162 PEP_ct_unknown = 0, 1164 // range 0x01 to 0x09: no encryption, 0x0a to 0x0e: 1165 // nothing reasonable 1166 PEP_ct_no_encryption = 0x01, // generic 1167 PEP_ct_no_encrypted_channel = 0x02, 1168 PEP_ct_key_not_found = 0x03, 1169 PEP_ct_key_expired = 0x04, 1170 PEP_ct_key_revoked = 0x05, 1171 PEP_ct_key_b0rken = 0x06, 1172 PEP_ct_my_key_not_included = 0x09, 1174 PEP_ct_security_by_obscurity = 0x0a, 1175 PEP_ct_b0rken_crypto = 0x0b, 1176 PEP_ct_key_too_short = 0x0c, 1178 PEP_ct_compromized = 0x0e, // known compromized connection 1179 PEP_ct_mistrusted = 0x0f, // known mistrusted key 1181 // range 0x10 to 0x3f: unconfirmed encryption 1183 PEP_ct_unconfirmed_encryption = 0x10, // generic 1184 PEP_ct_OpenPGP_weak_unconfirmed = 0x11, // RSA 1024 is weak 1186 PEP_ct_to_be_checked = 0x20, // generic 1187 PEP_ct_SMIME_unconfirmed = 0x21, 1188 PEP_ct_CMS_unconfirmed = 0x22, 1190 PEP_ct_strong_but_unconfirmed = 0x30, // generic 1191 PEP_ct_OpenPGP_unconfirmed = 0x38, // key at least 2048 bit 1192 // RSA or EC 1193 PEP_ct_OTR_unconfirmed = 0x3a, 1195 // range 0x40 to 0x7f: unconfirmed encryption and anonymization 1197 PEP_ct_unconfirmed_enc_anon = 0x40, // generic 1198 PEP_ct_pEp_unconfirmed = 0x7f, 1200 PEP_ct_confirmed = 0x80, // this bit decides if trust 1201 // is confirmed 1203 // range 0x81 to 0x8f: reserved 1204 // range 0x90 to 0xbf: confirmed encryption 1206 PEP_ct_confirmed_encryption = 0x90, // generic 1207 PEP_ct_OpenPGP_weak = 0x91, // RSA 1024 is weak (unused) 1209 PEP_ct_to_be_checked_confirmed = 0xa0, //generic 1210 PEP_ct_SMIME = 0xa1, 1211 PEP_ct_CMS = 0xa2, 1213 PEP_ct_strong_encryption = 0xb0, // generic 1214 PEP_ct_OpenPGP = 0xb8, // key at least 2048 bit RSA or EC 1215 PEP_ct_OTR = 0xba, 1217 // range 0xc0 to 0xff: confirmed encryption and anonymization 1219 PEP_ct_confirmed_enc_anon = 0xc0, // generic 1220 PEP_ct_pEp = 0xff 1221 } PEP_comm_type; 1223 A.3. Abstract Crypto API examples 1225 The following code excerpts are from the pEp Engine reference 1226 implementation, to be found in src/message_api.h. 1228 [[ Note: Just a selection; more functionality is available. ]] 1230 A.3.1. Encrypting a Message 1232 Cf. src/message_api.h [SRC.pepcore]: 1234 // encrypt_message() - encrypt message in memory 1235 // 1236 // parameters: 1237 // session (in) session handle 1238 // src (in) message to encrypt 1239 // extra (in) extra keys for encryption 1240 // dst (out) pointer to new encrypted message or NULL if 1241 // no encryption could take place 1242 // enc_format (in) encrypted format 1243 // flags (in) flags to set special encryption features 1244 // 1245 // return value: 1246 // PEP_STATUS_OK on success 1247 // PEP_KEY_HAS_AMBIG_NAME at least one of the recipient 1248 // keys has an ambiguous name 1249 // PEP_UNENCRYPTED no recipients with usable key, 1250 // message is left unencrypted, 1251 // and key is attached to it 1252 // 1253 // caveat: 1254 // the ownership of src remains with the caller 1255 // the ownership of dst goes to the caller 1256 DYNAMIC_API PEP_STATUS encrypt_message( 1257 PEP_SESSION session, 1258 message *src, 1259 stringlist_t *extra, 1260 message **dst, 1261 PEP_enc_format enc_format, 1262 PEP_encrypt_flags_t flags 1263 ); 1265 Cf. src/message_api.h [SRC.pepcore]: 1267 A.3.2. Decrypting a Message 1269 Cf. src/message_api.h [SRC.pepcore]: 1271 // decrypt_message() - decrypt message in memory 1272 // 1273 // parameters: 1274 // session (in) session handle 1275 // src (in) message to decrypt 1276 // dst (out) pointer to new decrypted message 1277 // or NULL on failure 1278 // keylist (out) stringlist with keyids 1279 // rating (out) rating for the message 1280 // flags (out) flags to signal special decryption features 1281 // 1282 // return value: 1283 // error status 1284 // or PEP_DECRYPTED if message decrypted but not verified 1285 // or PEP_CANNOT_REENCRYPT if message was decrypted (and 1286 // possibly verified) but a reencryption operation is 1287 // expected by the caller and failed 1288 // or PEP_STATUS_OK on success 1289 // 1290 // flag values: 1291 // in: 1292 // PEP_decrypt_flag_untrusted_server 1293 // used to signal that decrypt function should engage in 1294 // behaviour specified for when the server storing the 1295 // source is untrusted 1296 // out: 1297 // PEP_decrypt_flag_own_private_key 1298 // private key was imported for one of our addresses 1299 // (NOT trusted or set to be used - handshake/trust is 1300 // required for that) 1301 // PEP_decrypt_flag_src_modified 1302 // indicates that the src object has been modified. At 1303 // the moment, this is always as a direct result of the 1304 // behaviour driven by the input flags. This flag is the 1305 // ONLY value that should be relied upon to see if such 1306 // changes have taken place. 1307 // PEP_decrypt_flag_consume 1308 // used by sync 1309 // PEP_decrypt_flag_ignore 1310 // used by sync 1311 // 1312 // 1313 // caveat: 1314 // the ownership of src remains with the caller - however, the 1315 // contents might be modified (strings freed and allocated anew 1316 // or set to NULL, etc) intentionally; when this happens, 1317 // PEP_decrypt_flag_src_modified is set. 1318 // the ownership of dst goes to the caller 1319 // the ownership of keylist goes to the caller 1320 // if src is unencrypted this function returns PEP_UNENCRYPTED 1321 // and sets 1322 // dst to NULL 1323 DYNAMIC_API PEP_STATUS decrypt_message( 1324 PEP_SESSION session, 1325 message *src, 1326 message **dst, 1327 stringlist_t **keylist, 1328 PEP_rating *rating, 1329 PEP_decrypt_flags_t *flags 1331 ); 1333 A.3.3. Obtain Common Trustwords 1335 Cf. src/message_api.h [SRC.pepcore]: 1337 // get_trustwords() - get full trustwords string 1338 // for a *pair* of identities 1339 // 1340 // parameters: 1341 // session (in) session handle 1342 // id1 (in) identity of first party in communication 1343 // - fpr can't be NULL 1344 // id2 (in) identity of second party in communication 1345 // - fpr can't be NULL 1346 // lang (in) C string with ISO 639-1 language code 1347 // words (out) pointer to C string with all trustwords 1348 // UTF-8 encoded, separated by a blank each 1349 // NULL if language is not supported or 1350 // trustword wordlist is damaged or unavailable 1351 // wsize (out) length of full trustwords string 1352 // full (in) if true, generate ALL trustwords for these 1353 // identities. 1354 // else, generate a fixed-size subset. 1355 // (TODO: fixed-minimum-entropy subset 1356 // in next version) 1357 // 1358 // return value: 1359 // PEP_STATUS_OK trustwords retrieved 1360 // PEP_OUT_OF_MEMORY out of memory 1361 // PEP_TRUSTWORD_NOT_FOUND at least one trustword not found 1362 // 1363 // caveat: 1364 // the word pointer goes to the ownership of the caller 1365 // the caller is responsible to free() it 1366 // (on Windoze use pEp_free()) 1367 // 1368 DYNAMIC_API PEP_STATUS get_trustwords( 1369 PEP_SESSION session, const pEp_identity* id1, 1370 const pEp_identity* id2, const char* lang, 1371 char **words, size_t *wsize, bool full 1372 ); 1374 Appendix B. Document Changelog 1376 [[ RFC Editor: This section is to be removed before publication ]] 1378 o draft-birk-pep-05: 1380 * Change authors 1382 * Minor changes, especially in identity system 1384 o draft-birk-pep-04: 1386 * Fix internal reference 1388 * Add IANA Considerations section 1390 * Add other use case of Extra Keys 1392 * Add Claudio Luck as author 1394 * Incorporate review changes by Kelly Bristol and Nana 1395 Karlstetter 1397 o draft-birk-pep-03: 1399 * Major restructure of the document 1401 * Adapt authors to the actual authors and extend Acknowledgments 1402 section 1404 * Added several new sections, e.g., Key Reset, Trust Revoke, 1405 Trust Synchronization, Private Key Export / Import, Privacy 1406 Considerations (content yet mostly TODO) 1408 * Added reference to HRPC work / RFC8280 1410 + Added text and figure to better explain pEp's automated Key 1411 Exchange and Trust management (basic message flow) 1413 * Lots of improvement in text and editorial changes 1415 o draft-birk-pep-02: 1417 * Move (updated) code to Appendix 1419 * Add Changelog to Appendix 1421 * Add Open Issue section to Appendix 1423 * Fix description of what Extra Keys are 1425 * Fix Passive Mode description 1427 * Better explain pEp's identity system 1429 o draft-birk-pep-01: 1431 * Mostly editorial 1433 o draft-birk-pep-00: 1435 * Initial version 1437 Appendix C. Open Issues 1439 [[ RFC Editor: This section should be empty and is to be removed 1440 before publication ]] 1442 o Shorten Introduction and Abstract 1444 o References to RFC6973 (Privacy Considerations) 1446 o Add references to prior work, and what differs here - PEM (cf. 1447 RFC1421-1424) 1449 o Better explain Passive Mode 1451 o Better explain / illustrate pEp's identity system 1453 o Explain Concept of Key Mapping (e.g. to S/MIME, which is to be 1454 refined in pEp application docs auch as pEp email 1455 [I-D.marques-pep-email]) 1457 o Add more information to deal with organizational requirements 1459 o Add text to Key Reset (Section 4.3) as well as reference as soon 1460 as available 1462 o Add text to Trust Revoke (Section 5.4) as well as reference as 1463 soon as available 1465 o Add text to Trust Synchronization (Section 6.2) as well as 1466 reference as soon as available 1468 o Add text to Privacy Considerations (Section 10) 1470 o Scan for leftovers of email-specific stuff and move it to pEp 1471 email I-D [I-D.marques-pep-email], while replacing it herein with 1472 generic descriptions. 1474 Authors' Addresses 1476 Volker Birk 1477 pEp Foundation 1478 Oberer Graben 4 1479 CH-8400 Winterthur 1480 Switzerland 1482 Email: volker.birk@pep.foundation 1483 URI: https://pep.foundation/ 1485 Hernani Marques 1486 pEp Foundation 1487 Oberer Graben 4 1488 CH-8400 Winterthur 1489 Switzerland 1491 Email: hernani.marques@pep.foundation 1492 URI: https://pep.foundation/ 1494 Bernie Hoeneisen 1495 pEp Foundation 1496 Oberer Graben 4 1497 CH-8400 Winterthur 1498 Switzerland 1500 Email: bernie.hoeneisen@pep.foundation 1501 URI: https://pep.foundation/