idnits 2.17.1 draft-birk-pep-03.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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1222 has weird spacing: '... by the calle...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: If there is already a known public key from the sender of a message and it is still valid and not expired, new keys MUST not be used for future communication unless they are signed by the previous key (to avoid a MITM attack). Messages MUST always be encrypted with the receiving peer's oldest public key, as long as it is valid and not expired. -- The document date (March 07, 2019) is 1877 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 1038 ** 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-02 == Outdated reference: A later version (-05) exists of draft-marques-pep-handshake-01 == Outdated reference: A later version (-03) exists of draft-marques-pep-rating-00 Summary: 3 errors (**), 0 flaws (~~), 6 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 pEp Foundation 4 Intended status: Standards Track B. Hoeneisen 5 Expires: September 8, 2019 Ucom.ch 6 March 07, 2019 8 pretty Easy privacy (pEp): Privacy by Default 9 draft-birk-pep-03 11 Abstract 13 The pretty Easy privacy (pEp) protocols describe a set of conventions 14 for the automation of operations traditionally seen as barriers to 15 the use and deployment of secure end-to-end interpersonal messaging. 16 These include, but are not limited to, key management, key discovery, 17 and private key handling (including peer-to-peer synchronization of 18 private keys and other user data across devices). pEp also introduces 19 means to verify communication peers and proposes a trust-rating 20 system to denote secure types of communications and signal the 21 privacy level available on a per-user and per-message level. 22 Significantly, the pEp protocols build on already available security 23 formats and message transports (e.g., PGP/MIME), and are written with 24 the intent to be interoperable with already widely-deployed systems 25 in order to facilitate and ease adoption and implementation. This 26 document outlines the general design choices and principles of pEp. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on September 8, 2019. 45 Copyright Notice 47 Copyright (c) 2019 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.1. Relationship to other pEp documents . . . . . . . . . . . 5 64 2. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 3. Protocol's Core Design Principles . . . . . . . . . . . . . . 6 66 3.1. Privacy by Default . . . . . . . . . . . . . . . . . . . 6 67 3.2. Data Minimization . . . . . . . . . . . . . . . . . . . . 6 68 3.3. Interoperability . . . . . . . . . . . . . . . . . . . . 6 69 3.4. Peer-to-Peer (P2P) . . . . . . . . . . . . . . . . . . . 7 70 3.5. User Experience (UX) . . . . . . . . . . . . . . . . . . 7 71 4. Specific Elements in pEp . . . . . . . . . . . . . . . . . . 8 72 4.1. pEp identity system . . . . . . . . . . . . . . . . . . . 8 73 4.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 8 74 4.2.1. Key . . . . . . . . . . . . . . . . . . . . . . . . . 8 75 4.2.2. User . . . . . . . . . . . . . . . . . . . . . . . . 8 76 4.2.3. Identity . . . . . . . . . . . . . . . . . . . . . . 9 77 4.2.4. Address . . . . . . . . . . . . . . . . . . . . . . . 9 78 4.3. Example: Difference between pEp and OpenPGP . . . . . . . 9 79 5. Key Management . . . . . . . . . . . . . . . . . . . . . . . 10 80 5.1. Key Generation . . . . . . . . . . . . . . . . . . . . . 10 81 5.2. Private Keys . . . . . . . . . . . . . . . . . . . . . . 10 82 5.2.1. Storage . . . . . . . . . . . . . . . . . . . . . . . 10 83 5.2.2. Passphrase . . . . . . . . . . . . . . . . . . . . . 11 84 5.2.3. Private Key Export / Import . . . . . . . . . . . . . 11 85 5.3. Public Key Distribution . . . . . . . . . . . . . . . . . 11 86 5.4. Key Reset . . . . . . . . . . . . . . . . . . . . . . . . 12 87 6. Trust Management . . . . . . . . . . . . . . . . . . . . . . 12 88 6.1. Privacy Status . . . . . . . . . . . . . . . . . . . . . 15 89 6.2. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 15 90 6.3. Trust Rating . . . . . . . . . . . . . . . . . . . . . . 15 91 6.4. Trust Revoke . . . . . . . . . . . . . . . . . . . . . . 16 92 7. Synchronization . . . . . . . . . . . . . . . . . . . . . . . 16 93 7.1. Private Key Synchronization . . . . . . . . . . . . . . . 16 94 7.2. Trust Synchronization . . . . . . . . . . . . . . . . . . 16 95 8. Interoperability . . . . . . . . . . . . . . . . . . . . . . 16 96 9. Options in pEp . . . . . . . . . . . . . . . . . . . . . . . 16 97 9.1. Option "Passive Mode" . . . . . . . . . . . . . . . . . . 16 98 9.2. Option "Disable Protection" . . . . . . . . . . . . . . . 17 99 9.3. Option "Extra Keys" . . . . . . . . . . . . . . . . . . . 17 100 9.4. Option "Blacklist Keys" . . . . . . . . . . . . . . . . . 17 101 10. Security Considerations . . . . . . . . . . . . . . . . . . . 17 102 11. Privacy Considerations . . . . . . . . . . . . . . . . . . . 18 103 12. Implementation Status . . . . . . . . . . . . . . . . . . . . 18 104 12.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 18 105 12.2. Current software implementing pEp . . . . . . . . . . . 18 106 12.3. Reference implementation of pEp's core . . . . . . . . . 19 107 12.4. Abstract Crypto API examples . . . . . . . . . . . . . . 20 108 13. Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 109 14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21 110 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 111 15.1. Normative References . . . . . . . . . . . . . . . . . . 21 112 15.2. Informative References . . . . . . . . . . . . . . . . . 21 113 Appendix A. Code Excerpts . . . . . . . . . . . . . . . . . . . 23 114 A.1. pEp Identity . . . . . . . . . . . . . . . . . . . . . . 23 115 A.1.1. Corresponding SQL . . . . . . . . . . . . . . . . . . 24 116 A.2. pEp Communication Type . . . . . . . . . . . . . . . . . 25 117 A.3. Abstract Crypto API examples . . . . . . . . . . . . . . 26 118 A.3.1. Encrypting a Message . . . . . . . . . . . . . . . . 26 119 A.3.2. Decrypting a Message . . . . . . . . . . . . . . . . 27 120 A.3.3. Obtain Common Trustwords . . . . . . . . . . . . . . 29 121 Appendix B. Document Changelog . . . . . . . . . . . . . . . . . 29 122 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 30 123 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 125 1. Introduction 127 Secure and private communications are vital for many different 128 reasons, and there are particular properties that privacy-preserving 129 protocols need to fulfill in order to best serve users. In 130 particular, [RFC8280] has identified and documented important 131 principles such as data minimization, the end-to-end principle, and 132 interoperability as integral properties for access to the Internet 133 for human rights purposes. While (partial) implementations of these 134 concepts are already available, today's applications widely lack 135 privacy support that ordinary users can easily handle. The pretty 136 Easy privacy (pEp) protocols generally conform with the principles 137 outlined in [RFC8280] as a matter of course, and as such can be used 138 to facilitate the adoption and correct usage of secure and private 139 communications technology. 141 The pretty Easy privacy (pEp) protocols are propositions to the 142 Internet community to create software for peers to automatically 143 encrypt, anonymize (where possible), and verify their daily written 144 digital communications. This is achieved by building upon already 145 existing standards and tools and automating each step a user needs to 146 carry out in order to engage in secure end-to-end encrypted 147 communications. Significantly, the pEp protocols describe how do to 148 this without dependence on centralized infrastructures. 150 In particular, pEp proposes automatation of key management, key 151 discovery and synchronization of secret key material by an in-band 152 peer-to-peer approach. 154 To mitigate man-in-the-middle attacks (MITM) by an active adversary, 155 and as the only manual step users carry out in the course of the 156 protocols, the proposed Trustwords [I-D.birk-pep-trustwords] 157 mechanism uses natural language representations of two peers' 158 fingerprints for users to verify their trust in a paired 159 communication channel. 161 [[ Note: The pEp initiators learned from the CryptoParty movement, 162 from which the project emerged, that while step-by-step guides can be 163 helpful for some users to engage in secure end-to-end communications, 164 for the vast majority of users, it is both more effective and more 165 convenient to have these step-by-step procedures put into actual code 166 (as such, following a protocol) and thus automating the initial 167 configuration and whole usage of cryptographic tools.]] 169 The privacy-by-default principles that pEp introduces are in 170 accordance with the perspective outlined in [RFC7435], aiming to 171 provide opportunistic security in the sense of "some protection most 172 of the time". This is done, however, with the subtle but important 173 difference that when privacy is weighed against security, the choice 174 defaults to privacy. Therefore, data minimization is a primary goal 175 in pEp (e.g., hiding subject lines and headers unnecessary for email 176 transport inside the encrypted payload of a message). 178 The pEp propositions are focused on (but not limited to) written 179 digital communications and cover asynchronous (offline) types of 180 communications like email as well as synchronous (online) types such 181 as chat. 183 pEp's goal is to bridge different standardized and widely-used 184 communications channels such that users can reach communications 185 partners in the most privacy-enhancing way possible. 187 1.1. Relationship to other pEp documents 189 While this document describes the general concept of pEp, other 190 documents build on top of this. These documents define other parts 191 of the pEp environment as follows: 193 1. pEp enhanced applications (e.g., pEp Email 194 [I-D.marques-pep-email]). 196 2. Helper functions for interaction with peers (e.g., pEp Handshake 197 [I-D.marques-pep-handshake]) that assist the user with handling 198 and understanding cryptographic parts that he/she needs to be 199 aware of. 201 3. Helper functions for interactions between a user's own devices 202 (e.g., pEp Key Sync [E-D.birk-pep-keysync]) that assist the user 203 to run pEp applications on different devices (such as computer, 204 mobile phone or tables) at the same time. 206 In addition, there are documents that do not directly depend on this 207 one, but provide generic functions needed in pEp, e.g., IANA 208 Registration of Trustword Lists [I-D.birk-pep-trustwords]. 210 [[At this stage it is not yet clear to us how many of our 211 implementation details should be part of new RFCs and at which places 212 we can safely refer to already existing RFCs to make clear on which 213 RFCs we already rely.]] 215 2. Terms 217 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 218 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 219 document are to be interpreted as described in [RFC2119]. 221 o pEp Handshake: The process when Alice - e.g., in-person or via 222 phone - contacts Bob to verify Trustwords (or by fallback: 223 fingerprints) is called pEp Handshake. 224 [I-D.marques-pep-handshake] 226 o Trustwords: A scalar-to-word representation of 16-bit numbers (0 227 to 65535) to natural language words. When doing a Handshake, 228 peers are shown combined Trustwords of both public keys involved 229 to ease the comparison. [I-D.birk-pep-trustwords] 231 o Trust on First Use (TOFU): cf. [RFC7435] 233 o Man-in-the-middle attack (MITM): cf. [RFC4949] 235 3. Protocol's Core Design Principles 237 3.1. Privacy by Default 239 The pEp protocols are to intended specifically to ensure privacy. 240 There exist cases in the secure communications ecosystem, however, 241 where achieving privacy is in direct contradiction to security 242 though. For instance, in PGP's Web of Trust, relations between 243 people and trust levels are exposed to the public. Additionally, the 244 privacy of queries is not ensured in such a model when obtaining keys 245 from remote locations. Within the pEp protocols, when security and 246 privacy goals are not in conflict, then the protocols are designed to 247 maximize both security and privacy. However, where they contradict 248 each other, privacy goals are chosen as the default over security 249 considerations. However, in implementing these protocols, it is 250 always the case that users SHOULD have the choice to override the 251 default by corresponding options. 253 In pEp messaging (e.g., when using HTML) content SHALL NOT be 254 obtained from remote locations as this constitutes a privacy breach. 256 3.2. Data Minimization 258 Another important design goal is data minimization, which includes 259 data spareness and hiding all technically concealable information 260 when possible. 262 3.3. Interoperability 264 The pEp propositions seek to be interoperable with already-widespread 265 message formats and cryptographic protocols and implementations. 266 Seamless communication between users of software which implements pEp 267 and and users of other messaging tools for end-to-end encryption is a 268 design goal. 270 Therefore, pEp abides by the following guidelines: 272 o pEp is conservative (strict) in requirements for pEp 273 implementations and how they interact with pEp or other 274 (messaging) implementations. 276 o pEp is liberal in accepting input from non-pEp implementations 277 (e.g., it will not produce, but will support the decryption of, 278 PGP/INLINE formats). 280 o Where pEp requires divergence from an RFC for privacy reasons 281 (e.g., from OpenPGP propositions as defined in [RFC4880], options 282 SHOULD be implemented to empower the user to override pEp's 283 defaults. 285 3.4. Peer-to-Peer (P2P) 287 Messaging and verification processes in pEp are designed to work in a 288 peer-to-peer (P2P) manner, without the involvement of intermediaries. 290 This means there MUST NOT be any pEp-specific central services 291 whatsoever needed for pEp implementations, both in the case of 292 verification of peers and for the actual encryption. 294 However, implementers of pEp MAY provide options for interoperation 295 with providers of centralized infrastructures (e.g., to enable users 296 to communicate with their peers on platforms with vendor lock-in). 298 Trust provided by global Certificate Authorities (e.g., commercial 299 X.509 CAs) SHALL NOT be signaled as trustworthy (cf. 300 [I-D.marques-pep-rating]) to users of pEp (e.g., when interoperating 301 with peers using S/MIME) by default. 303 3.5. User Experience (UX) 305 Implementers of pEp MUST take special care not to confuse users with 306 technical terms, especially those of cryptography (e.g., "keys", 307 "certificates" or "fingerprints"), unless users explicitly ask for 308 such terms; i.e., advanced settings MAY be available, and in some 309 cases further options may even be required. However, those SHALL NOT 310 be unnecessarily exposed to users of pEp implementations at first 311 glance. 313 The authors believe widespread adoption of end-to-end cryptography is 314 much less of a problem if the users are not confronted with the need 315 to understand cryptography; that is to say, a central goal of pEp of 316 the pEp protocol is that users can just rely on the principles of 317 Privacy by Default. 319 As a consequence, this means that users must not wait for 320 cryptographic tasks (e.g., key generation or public key retrieval) to 321 finish before being able to have their respective message clients 322 ready to communicate. The end result of this is that pEp 323 implementers MUST ensure that the ability to draft, send and receive 324 messages is always preserved - even if that means a message is sent 325 out unencrypted, thus being in accordance with the Opportunistic 326 Security approach outlined in [RFC7435]. 328 In turn, pEp implementers MUST ensure that a discernible privacy 329 status is clearly visible to the user - on a per-contact as well as 330 per-message level - so that users easily understand which level of 331 privacy messages are about to be sent with or were received with, 332 respectively. 334 [[Note: We are aware of the fact that usually UX requirements are not 335 part of RFCs. However, in order to encourage massive adoption of 336 secure end-to-end encryption while at the same time avoiding putting 337 users at risk, we believe certain straightforward signaling 338 requirements for users to be a good idea, just as is currently done 339 for already-popular instant messaging services.]] 341 4. Specific Elements in pEp 343 4.1. pEp identity system 345 In pEp, users MUST have the ability to have multiple different 346 identities. 348 pEp users MUST have the option to choose different identities. This 349 allows an Internet user to decide how to reveal himself/herself to 350 the world and is an important element in order to achieve privacy. 352 These different identities MUST NOT be externally correlatable with 353 each other by default. On the other hand, combining different 354 identities when such information is known MUST be supported (alias 355 support). 357 4.2. Identifiers 359 4.2.1. Key 361 A key is an OpenPGP-compatible asymmetric key pair. Other formats 362 and temporary symmetrical keys can be generated by Key Mapping. 364 Keys in pEp are identified by the full fingerprint (fpr) of the 365 public key. 367 4.2.2. User 369 A user is a real world human being or a group of human beings. If it 370 is a single human being, it can be called person. 372 A user is identified by a user ID (user_id). The user_id SHOULD be a 373 UUID, it MAY be an arbitrary unique string. 375 The own user can have a user_id like all other users. If it doesn't, 376 then it has PEP_OWN_USERID "pEp_own_userId" as user_id. 378 A user can have a default key. (cf. Section 4.2.1) 380 4.2.3. Identity 382 An identity is a (possibly pseudonymous) representation of a user 383 encapsulating how this user appears in the network. 385 An identity is defined by the mapping of user_id to address. If no 386 user_id is known, it is guessed by mapping of username and address. 388 An identity can have a temporary user_id as a placeholder until a 389 real user_id is known. 391 An identity can have a default key. (cf. Section 4.2.1) 393 [[ Note: This is the reason why in current pEp implementations for 394 each (email) account a different key pair is created, which allows a 395 user to retain different identities. ]] 397 In Appendix A.1 you can find how a pEp identity is defined in the 398 reference implementation of the pEp Engine. 400 4.2.4. Address 402 An address is a network address, e.g., an SMTP address or another 403 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 4.3. Example: Difference between pEp and OpenPGP 412 +--------------------+--------------+-------------------------------+ 413 | pEp | OpenPGP | Comments | 414 +--------------------+--------------+-------------------------------+ 415 | user_id | (no concept) | ID for a person, i.e. a | 416 | | | contact | 417 | | | | 418 | username + address | uid | comparable only for email | 419 | | | | 420 | fpr | fingerprint | used as key ID in pEp | 421 | | | | 422 | (no concept) | Key ID | does not exist in pEp | 423 +--------------------+--------------+-------------------------------+ 425 5. Key Management 427 In order to achieve the goal of widespread adoption of secure 428 communications, key management in pEp MUST be automated. 430 5.1. Key Generation 432 A pEp implementation MUST ensure that cryptographic keys for every 433 identity configured are available. If a corresponding key pair for 434 the identity of a user is found and said identity fulfills the 435 requirements (e.g., for email, as set out in 436 [I-D.marques-pep-email]), said key pair MUST be reused. Otherwise a 437 new key pair MUST be generated. This may be carried out instantly 438 upon its configuration. 440 On devices with limited processing power (e.g., mobile devices) the 441 key generation may take more time than a user is willing to wait. If 442 this is the case, users SHOULD NOT be stopped from communicating, 443 i.e., the key generation process SHOULD be carried out in the 444 background. 446 5.2. Private Keys 448 5.2.1. Storage 450 Private keys in pEp implementations MUST always be held on the end 451 user's device(s): pEp implementers MUST NOT rely on private keys 452 stored in centralized remote locations. This applies even for key 453 storages where the private keys are protected with sufficiently long 454 passphrases. It is considered a violation of pEp's P2P design 455 principle to rely on centralized infrastructures (cf. Section 3.4). 456 This also applies for pEp implementations created for applications 457 not residing on a user's device (e.g., web-based MUAs). In such 458 cases, pEp implementations MUST be done in a way such that the 459 locally-held private key can neither be directly accessed nor leaked 460 to the outside world. 462 [[ Note: It is particularly important that browser add-ons 463 implementing pEp functionality do not obtain their cryptographic code 464 from a centralized (cloud) service, as this must be considered a 465 centralized attack vector allowing for backdoors, negatively 466 impacting privacy. ]] 468 Cf. Section 7.1 for a means to synchronize private keys among 469 different devices of the same network address in a secure manner. 471 5.2.2. Passphrase 473 Passphrases to protect a user's private key MUST be supported by pEp 474 implementations, but MUST NOT be enforced by default. That is, if a 475 pEp implementation finds a suitable (i.e., secure enough) 476 cryptographic setup, which uses passphrases, pEp implementations MUST 477 provide a way to unlock the key. However, if a new key pair is 478 generated for a given identity, no passphrase MUST be put in place. 479 The authors assume that the enforcement of secure (i.e., unique and 480 long enough) passphrases would massively reduce the number of pEp 481 users (by hassling them), while providing little to no additional 482 privacy for the common cases of passive monitoring being carried out 483 by corporations or state-level actors. 485 5.2.3. Private Key Export / Import 487 A private key can be exported from one device for import onto another 488 device. When pEp's Key Sync (cf. Section 7.1) is not available or 489 not desired to be used, this is largely a manual process. 491 5.3. Public Key Distribution 493 As the key is available (cf. Section 5.3) implementers of pEp are 494 REQUIRED to ensure that the identity's public key is attached to 495 every outgoing message. However, this MAY be omitted if the peer has 496 previously received a message encrypted with the public key of the 497 sender. 499 The sender's public key SHOULD be sent encrypted whenever possible, 500 i.e., when a public key of the receiving peer is available. If no 501 encryption key of the recipient is available, the sender's public key 502 MAY be sent unencrypted. In either case, this approach ensures that 503 messaging clients (e.g., MUAs that at least implement OpenPGP) do not 504 need to have pEp implemented to see a user's public key. Such peers 505 thus have the chance to (automatically) import the sender's public 506 key. 508 If there is already a known public key from the sender of a message 509 and it is still valid and not expired, new keys MUST not be used for 510 future communication unless they are signed by the previous key (to 511 avoid a MITM attack). Messages MUST always be encrypted with the 512 receiving peer's oldest public key, as long as it is valid and not 513 expired. 515 Implementers of pEp SHALL prevent the display of public keys attached 516 to messages (e.g, in email) to the user in order to prevent user 517 confusion by files they are potentially unaware of how to handle. 519 Metadata (e.g., email headers) MUST NOT be added to announce a user's 520 public key. This is considered unnecessary information leakage as it 521 may affect user privacy, which depends also on a country's data 522 retention laws. Furthermore, this affects interoperability to 523 existing users (e.g., in the OpenPGP field) that have no notion of 524 such header fields and thus lose the ability to import any such keys 525 distributed this way. It SHOULD, though, be supported to obtain 526 other users' public keys by extracting them from respective header 527 fields of received messages (in case such approaches get widespread). 529 Keyservers or generally intermediate approaches to obtain a peer's 530 public key SHALL NOT be used by default. On the other hand, the user 531 MAY be provided with the option to opt-in for remote locations to 532 obtain keys, considering the widespread adoption of such approaches 533 for key distribution. 535 Keys generated or obtained by pEp clients MUST NOT be uploaded to any 536 (intermediate) keystore locations without the user's explicit 537 consent. 539 5.4. Key Reset 541 [[ TODO: This section will explain how to deal with keys no longer 542 valid, e.g. if leaked ]] 544 6. Trust Management 546 The following example roughly describes a pEp scenario with a typical 547 initial message flow to demonstrate key exchange and basic trust 548 management: 550 1. Alice - knowing nothing of Bob - sends a message to Bob. As Alice 551 has no public key from Bob, this message is sent out unencrypted. 552 However, Alice's public key is automatically attached. 554 2. Bob can just reply to Alice and - as he received her public key - 555 his messaging client is now able to encrypt the message. At this 556 point the rating for Alice changes to "encrypted" in Bob's 557 messaging client, which (UX-wise) can be displayed using yellow 558 color (cf. Section 6.3). 560 3. Alice receives Bob's key. As of now Alice is also able to send 561 secure messages to Bob. The rating for Bob changes to "encrypted" 562 (with yellow color) in Alice's messaging client (cf. 563 Section 6.3). 565 4. If Alice and Bob want to prevent man-in-the-middle (MITM) 566 attacks, they can engage in a pEp Handshake comparing their so- 567 called Trustwords (cf. Section 6.2) and confirm this process if 568 those match. After doing so, their identity rating changes to 569 "encrypted and authenticated" (cf. Section 6.3), which (UX-wise) 570 can be displayed using a green color. 572 As color code changes for an identity, it is also applied to future 573 messages to/from this identity. 575 ----- ----- 576 | A | | B | 577 ----- ----- 578 | | 579 +------------------------+ +------------------------+ 580 | auto-generate key pair | | auto-generate key pair | 581 | (if no key yet) | | (if no key yet) | 582 +------------------------+ +------------------------+ 583 | | 584 +-----------------------+ +-----------------------+ 585 | Privacy Status for B: | | Privacy Status for A: | 586 | *Unencrypted* | | *Unencrypted* | 587 +-----------------------+ +-----------------------+ 588 | | 589 | A sends message to B (Public Key | 590 | attached) / optionally signed, but | 591 | NOT ENCRYPTED | 592 +------------------------------------------>| 593 | | 594 | +-----------------------+ 595 | | Privacy Status for A: | 596 | | *Encrypted* | 597 | +-----------------------+ 598 | | 599 | B sends message to A (Public Key | 600 | attached) / signed and ENCRYPTED | 601 |<------------------------------------------+ 602 | | 603 +-----------------------+ | 604 | Privacy Status for B: | | 605 | *Encrypted* | | 606 +-----------------------+ | 607 | | 608 | A and B sucessfully compare their | 609 | Trustwords over an alternative channel | 610 | (e.g., phone line) | 611 |<-- -- -- -- -- -- -- -- -- -- -- -- -- -->| 612 | | 613 +-----------------------+ +-----------------------+ 614 | Privacy Status for B: | | Privacy Status for A: | 615 | *Trusted* | | *Trusted* | 616 +-----------------------+ +-----------------------+ 617 | | 619 6.1. Privacy Status 621 For end-users, the most important component of pEp, which MUST be 622 made visible on a per-recipient and per-message level, is the Privacy 623 Status. 625 By colors, symbols and texts a user SHALL immediately understand how 626 private 628 o a communication channel with a given peer was or ought to be and 630 o a given message was or ought to be. 632 6.2. Handshake 634 To establishing trust between peers and to upgrade Privacy Status, 635 pEp defines a handshake, which is specified in 636 [I-D.marques-pep-handshake]. 638 In pEp, Trustwords [I-D.birk-pep-trustwords] are used for users to 639 compare the authenticity of peers in order to mitigate MITM attacks. 641 By default, Trustwords MUST be used to represent two peers' 642 fingerprints of their public keys in pEp implementations. 644 In order to retain compatibility with peers not using pEp 645 implementations (e.g., Mail User Agents (MUAs) with OpenPGP 646 implementations without Trustwords), it is REQUIRED that pEp 647 implementers give the user the choice to show both peers' 648 fingerprints instead of just their common Trustwords. 650 6.3. Trust Rating 652 pEp includes a Trust Rating system defining Rating and Color Codes to 653 express the Privacy Status of a peer or message 654 [I-D.marques-pep-rating]. The ratings are labeled, e.g., as 655 "Unencrypted", "Encrypted", "Trusted", "Under Attack", etc. The 656 Privacy Status in its most general form is expressed with traffic 657 lights semantics (and respective symbols and texts), whereas the 658 three colors yellow, green and red can be applied for any peer or 659 message - like this immediately indicating how secure and trustworthy 660 (and thus private) a communication was or ought to be considered. 662 The pEp Trust Rating system with all its states and respective 663 representations to be followed is outlined in 664 [I-D.marques-pep-rating]. 666 Note: An example for the rating of communication types, the 667 definition of the data structure by the pEp Engine reference 668 implementation is provided in Appendix A.2. 670 6.4. Trust Revoke 672 [[ TODO: This section will explain how to deal with the situation 673 when a peer can no longer be trusted, e.g., if a peer's device is 674 compromised. ]] 676 7. Synchronization 678 An important feature of pEp is to assist the user to run pEp 679 applications on different devices, such as computer, mobile phone or 680 tables, at the same time. Therefore state needs to be synchronized 681 among the different devices. 683 7.1. Private Key Synchronization 685 A decentralized proposition - the pEp Key Synchronization protocol. 686 [E-D.birk-pep-keysync] - defines how pEp users can distribute their 687 private keys among different devices in a secure and trusted manner: 688 this allows Internet users to read their messages across their 689 different devices, when sharing a common address (e.g., the same 690 email account). 692 7.2. Trust Synchronization 694 [[ TODO: This section will explain how trust and other related state 695 is synchronized among different devices in a secure manner. ]] 697 8. Interoperability 699 pEp aims to be interoperable with existing applications designed to 700 enable privacy, e.g., OpenPGP and S/MIME in email. 702 9. Options in pEp 704 In this section a non-exhaustive selection of options is provided. 706 9.1. Option "Passive Mode" 708 By default the sender attaches its public key to any outgoing message 709 (cf. Section 5.3). For situations where a sender wants to ensure 710 that it only attaches a public key to an Internet user which has a 711 pEp implementation, a Passive Mode MUST be available. 713 9.2. Option "Disable Protection" 715 Using this option, protection can be disabled generally or 716 selectively. Implementers of pEp MUST provide an option "Disable 717 Protection" to allow a user to disable encryption and signing for: 719 1. all communication 721 2. specific contacts 723 3. specific messages 725 The public key still attached, unless the option "Passive Mode" (cf. 726 Section 9.1) is activated at the same time. 728 9.3. Option "Extra Keys" 730 For internal environments there may be a need to centrally decrypt 731 persons' messages for archiving or other legal purposes (e.g., in the 732 contexts of public offices and enterprises) by authorized personnel. 733 Therefore, pEp implementers MAY provide an "Extra Keys" option where 734 a message gets encrypted with at least one additional public key. 735 The corresponding secret key(s) are intended to be held (safely and 736 securely), e.g., by CISO staff or other authorized personnel for such 737 an organization. 739 The Extra Keys feature MUST NOT be activated by default for any 740 network address and is intended to be an option only for 741 organizational identities and their corresponding network addresses 742 and accounts - not for addresses used for private purposes. That is, 743 the Extra Keys feature is a feature which SHOULD NOT apply to all 744 identities a user might posses, even if activated. 746 9.4. Option "Blacklist Keys" 748 An option "Blacklist Keys" MUST be provided for an advanced user to 749 be able to disable keys which the user does not want to be used 750 anymore for any new communications. However, the keys SHALL NOT be 751 deleted. It MUST still be possible to verify and decipher past 752 communications. 754 10. Security Considerations 756 By attaching the sender's public key to outgoing messages, Trust on 757 First Use (TOFU) is established. However, this is prone to MITM 758 attacks. Cryptographic key subversion is considered Pervasive 759 Monitoring (PM) according to [RFC7258]. Those attacks can be 760 mitigated, if the involved users compare their common Trustwords. 762 This possibility MUST be made easily accessible to pEp users in the 763 user interface implementation. If for compatibility reasons (e.g., 764 with OpenPGP users) no Trustwords can be used, then a comparatively 765 easy way to verify the respective public key fingerprints MUST be 766 implemented. 768 As the use of passphrases for private keys is not advised, devices 769 themselves SHOULD use encryption. 771 11. Privacy Considerations 773 [[ TODO ]] 775 12. Implementation Status 777 12.1. Introduction 779 This section records the status of known implementations of the 780 protocol defined by this specification at the time of posting of this 781 Internet-Draft, and is based on a proposal described in [RFC7942]. 782 The description of implementations in this section is intended to 783 assist the IETF in its decision processes in progressing drafts to 784 RFCs. Please note that the listing of any individual implementation 785 here does not imply endorsement by the IETF. Furthermore, no effort 786 has been spent to verify the information presented here that was 787 supplied by IETF contributors. This is not intended as, and must not 788 be construed to be, a catalog of available implementations or their 789 features. Readers are advised to note that other implementations may 790 exist. 792 According to [RFC7942], "[...] this will allow reviewers and working 793 groups to assign due consideration to documents that have the benefit 794 of running code, which may serve as evidence of valuable 795 experimentation and feedback that have made the implemented protocols 796 more mature. It is up to the individual working groups to use this 797 information as they see fit." 799 12.2. Current software implementing pEp 801 The following software implementing the pEp protocols (to varying 802 degrees) already exists: 804 o pEp for Outlook as add-on for Microsoft Outlook, release 805 [SRC.pepforoutlook] 807 o pEp for Android (based on a fork of the K9 MUA), release 808 [SRC.pepforandroid] 810 o Enigmail/pEp as add-on for Mozilla Thunderbird, release 811 [SRC.enigmailpep] 813 o pEp for iOS (implemented in a new MUA), beta [SRC.pepforios] 815 pEp for Android, iOS and Outlook are provided by pEp Security, a 816 commercial entity specializing in end-user software implementing pEp 817 while Enigmail/pEp is pursued as community project, supported by the 818 pEp Foundation. 820 All software is available as Free Software and published also in 821 source form. 823 12.3. Reference implementation of pEp's core 825 The pEp Foundation provides a reference implementation of pEp's core 826 principles and functionalities, which go beyond the documentation 827 status of this Internet-Draft. [SRC.pepcore] 829 pEp's reference implementation is composed of pEp Engine and pEp 830 Adapters (or bindings), alongside with some libraries which pEp 831 Engine relies on to function on certain platforms (like a NetPGP fork 832 we maintain for the iOS platform). 834 The pEp engine is a Free Software library encapsulating 835 implementations of: 837 o Key Management 839 Key Management in pEp engine is based on GnuPG key chains (NetPGP 840 on iOS). Keys are stored in an OpenPGP compatible format and can 841 be used for different crypto implementations. 843 o Trust Rating 845 pEp engine is sporting a two phase trust rating system. In phase 846 one there is a rating based on channel, crypto and key security 847 named "comm_types". In phase 2 these are mapped to user 848 representable values which have attached colors to present them in 849 traffic light semantics. 851 o Abstract Crypto API 853 The Abstract Crypto API is providing functions to encrypt and 854 decrypt data or full messages without requiring an application 855 programmer to understand the different formats and standards. 857 o Message Transports 858 pEp engine will support a growing list of Message Transports to 859 support any widespread text messaging system including email, SMS, 860 XMPP and many more. 862 pEp engine is written in C99 programming language. It is not meant 863 to be used in application code directly. Instead, pEp engine is 864 coming together with a list of software adapters for a variety of 865 programming languages and development environments, which are: 867 o pEp COM Server Adapter 869 o pEp JNI Adapter 871 o pEp JSON Adapter 873 o pEp ObjC (and Swift) Adapter 875 o pEp Python Adapter 877 o pEp Qt Adapter 879 12.4. Abstract Crypto API examples 881 A selection of code excerpts from the pEp Engine reference 882 implementation (encrypt message, decrypt message, and obtain 883 trustwords) can be found in Appendix A.3. 885 13. Notes 887 The pEp logo and "pretty Easy privacy" are registered trademarks 888 owned by the non-profit pEp Foundation based in Switzerland. 890 Primarily, we want to ensure the following: 892 o Software using the trademarks MUST be backdoor-free. 894 o Software using the trademarks MUST be accompanied by a serious 895 (detailed) code audit carried out by a reputable third-party, for 896 any proper release. 898 The pEp Foundation will help to support any community-run (non- 899 commercial) project with the latter, be it organizationally or 900 financially. 902 Through this, the foundation wants to make sure that software using 903 the pEp trademarks is as safe as possible from a security and privacy 904 point of view. 906 14. Acknowledgments 908 The authors would like to thank the following people who have 909 provided significant contributions to the development of this 910 document: Volker Birk, Krista Bennett, and S. Shelburn. 912 Furthermore, the authors would like to thank the following people who 913 who provided helpful comments and suggestions for this document: 914 Alexey Melnikov, Ben Campbell, Brian Trammell, Bron Gondwana, Daniel 915 Kahn Gillmor, Enrico Tomae, Eric Rescorla, Gabriele Lenzini, Hans- 916 Peter Dittler, Iraklis Symeonidis, Mirja Kuehlewind, Neal Walfield, 917 Pete Resnick, Russ Housley, and Stephen Farrel. 919 This work was initially created by pEp Foundation, and then reviewed 920 and extended with funding by the Internet Society's Beyond the Net 921 Programme on standardizing pEp. [ISOC.bnet] 923 15. References 925 15.1. Normative References 927 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 928 Requirement Levels", BCP 14, RFC 2119, 929 DOI 10.17487/RFC2119, March 1997, 930 . 932 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 933 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 934 . 936 [RFC7435] Dukhovni, V., "Opportunistic Security: Some Protection 937 Most of the Time", RFC 7435, DOI 10.17487/RFC7435, 938 December 2014, . 940 15.2. Informative References 942 [E-D.birk-pep-keysync] 943 Birk, V. and H. Marques, "pretty Easy privacy (pEp): Key 944 Synchronization Protocol", June 2018, 945 . 949 Early draft 951 [I-D.birk-pep-trustwords] 952 Birk, V., Marques, H., and B. Hoeneisen, "IANA 953 Registration of Trustword Lists: Guide, Template and IANA 954 Considerations", draft-birk-pep-trustwords-02 (work in 955 progress), June 2018. 957 [I-D.marques-pep-email] 958 Marques, H., "pretty Easy privacy (pEp): Email Formats and 959 Protocols", draft-marques-pep-email-02 (work in progress), 960 October 2018. 962 [I-D.marques-pep-handshake] 963 Marques, H. and B. Hoeneisen, "pretty Easy privacy (pEp): 964 Contact and Channel Authentication through Handshake", 965 draft-marques-pep-handshake-01 (work in progress), October 966 2018. 968 [I-D.marques-pep-rating] 969 Marques, H. and B. Hoeneisen, "pretty Easy privacy (pEp): 970 Mapping of Privacy Rating", draft-marques-pep-rating-00 971 (work in progress), July 2018. 973 [ISOC.bnet] 974 Simao, I., "Beyond the Net. 12 Innovative Projects 975 Selected for Beyond the Net Funding. Implementing Privacy 976 via Mass Encryption: Standardizing pretty Easy privacy's 977 protocols", June 2017, . 981 [RFC4880] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R. 982 Thayer, "OpenPGP Message Format", RFC 4880, 983 DOI 10.17487/RFC4880, November 2007, 984 . 986 [RFC7258] Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an 987 Attack", BCP 188, RFC 7258, DOI 10.17487/RFC7258, May 988 2014, . 990 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 991 Code: The Implementation Status Section", BCP 205, 992 RFC 7942, DOI 10.17487/RFC7942, July 2016, 993 . 995 [RFC8280] ten Oever, N. and C. Cath, "Research into Human Rights 996 Protocol Considerations", RFC 8280, DOI 10.17487/RFC8280, 997 October 2017, . 999 [SRC.enigmailpep] 1000 "Source code for Enigmail/pEp", July 2018, 1001 . 1003 [SRC.pepcore] 1004 "Core source code and reference implementation of pEp 1005 (engine and adapters)", July 2018, 1006 . 1008 [SRC.pepforandroid] 1009 "Source code for pEp for Android", July 2018, 1010 . 1012 [SRC.pepforios] 1013 "Source code for pEp for iOS", July 2018, 1014 . 1016 [SRC.pepforoutlook] 1017 "Source code for pEp for Outlook", July 2018, 1018 . 1020 Appendix A. Code Excerpts 1022 This section provides excerpts of the running code from the pEp 1023 reference implementation pEp engine (C99 programming language). 1025 A.1. pEp Identity 1027 How the pEp identity is defined in the data structure (cf. src/ 1028 pEpEngine.h): 1030 typedef struct _pEp_identity { 1031 char *address; // C string with address UTF-8 encoded 1032 char *fpr; // C string with fingerprint UTF-8 1033 // encoded 1034 char *user_id; // C string with user ID UTF-8 encoded 1035 char *username; // C string with user name UTF-8 1036 // encoded 1037 PEP_comm_type comm_type; // type of communication with this ID 1038 char lang[3]; // language of conversation 1039 // ISO 639-1 ALPHA-2, last byte is 0 1040 bool me; // if this is the local user 1041 // herself/himself 1042 identity_flags_t flags; // identity_flag1 | identity_flag2 1043 // | ... 1044 } pEp_identity; 1046 A.1.1. Corresponding SQL 1048 Relational table scheme excerpts (in SQL) used in current pEp 1049 implementations, held locally for every pEp installation in a SQLite 1050 database: 1052 CREATE TABLE person ( 1053 id text primary key, 1054 username text not null, 1055 main_key_id text 1056 references pgp_keypair (fpr) 1057 on delete set null, 1058 lang text, 1059 comment text, 1060 device_group text, 1061 is_pep_user integer default 0 1062 ); 1064 CREATE TABLE identity ( 1065 address text, 1066 user_id text 1067 references person (id) 1068 on delete cascade on update cascade, 1069 main_key_id text 1070 references pgp_keypair (fpr) 1071 on delete set null, 1072 comment text, 1073 flags integer default 0, 1074 is_own integer default 0, 1075 timestamp integer default (datetime('now')), 1076 primary key (address, user_id) 1077 ); 1079 CREATE TABLE pgp_keypair ( 1080 fpr text primary key, 1081 created integer, 1082 expires integer, 1083 comment text, 1084 flags integer default 0 1085 ); 1086 CREATE INDEX pgp_keypair_expires on pgp_keypair ( 1087 expires 1088 ); 1090 A.2. pEp Communication Type 1092 In the following, is an example for the rating of communication types 1093 as defined by a data structure (cf. src/pEpEngine.h [SRC.pepcore]): 1095 typedef enum _PEP_comm_type { 1096 PEP_ct_unknown = 0, 1098 // range 0x01 to 0x09: no encryption, 0x0a to 0x0e: 1099 // nothing reasonable 1101 PEP_ct_no_encryption = 0x01, // generic 1102 PEP_ct_no_encrypted_channel = 0x02, 1103 PEP_ct_key_not_found = 0x03, 1104 PEP_ct_key_expired = 0x04, 1105 PEP_ct_key_revoked = 0x05, 1106 PEP_ct_key_b0rken = 0x06, 1107 PEP_ct_my_key_not_included = 0x09, 1109 PEP_ct_security_by_obscurity = 0x0a, 1110 PEP_ct_b0rken_crypto = 0x0b, 1111 PEP_ct_key_too_short = 0x0c, 1113 PEP_ct_compromized = 0x0e, // known compromized connection 1114 PEP_ct_mistrusted = 0x0f, // known mistrusted key 1116 // range 0x10 to 0x3f: unconfirmed encryption 1118 PEP_ct_unconfirmed_encryption = 0x10, // generic 1119 PEP_ct_OpenPGP_weak_unconfirmed = 0x11, // RSA 1024 is weak 1121 PEP_ct_to_be_checked = 0x20, // generic 1122 PEP_ct_SMIME_unconfirmed = 0x21, 1123 PEP_ct_CMS_unconfirmed = 0x22, 1125 PEP_ct_strong_but_unconfirmed = 0x30, // generic 1126 PEP_ct_OpenPGP_unconfirmed = 0x38, // key at least 2048 bit 1127 // RSA or EC 1128 PEP_ct_OTR_unconfirmed = 0x3a, 1130 // range 0x40 to 0x7f: unconfirmed encryption and anonymization 1132 PEP_ct_unconfirmed_enc_anon = 0x40, // generic 1133 PEP_ct_pEp_unconfirmed = 0x7f, 1135 PEP_ct_confirmed = 0x80, // this bit decides if trust 1136 // is confirmed 1138 // range 0x81 to 0x8f: reserved 1139 // range 0x90 to 0xbf: confirmed encryption 1141 PEP_ct_confirmed_encryption = 0x90, // generic 1142 PEP_ct_OpenPGP_weak = 0x91, // RSA 1024 is weak (unused) 1144 PEP_ct_to_be_checked_confirmed = 0xa0, //generic 1145 PEP_ct_SMIME = 0xa1, 1146 PEP_ct_CMS = 0xa2, 1148 PEP_ct_strong_encryption = 0xb0, // generic 1149 PEP_ct_OpenPGP = 0xb8, // key at least 2048 bit RSA or EC 1150 PEP_ct_OTR = 0xba, 1152 // range 0xc0 to 0xff: confirmed encryption and anonymization 1154 PEP_ct_confirmed_enc_anon = 0xc0, // generic 1155 PEP_ct_pEp = 0xff 1156 } PEP_comm_type; 1158 A.3. Abstract Crypto API examples 1160 The following code excerpts are from the pEp Engine reference 1161 implementation, to be found in src/message_api.h. 1163 [[ Note: Just a selection; more functionality is available. ]] 1165 A.3.1. Encrypting a Message 1167 Cf. src/message_api.h [SRC.pepcore]: 1169 // encrypt_message() - encrypt message in memory 1170 // 1171 // parameters: 1172 // session (in) session handle 1173 // src (in) message to encrypt 1174 // extra (in) extra keys for encryption 1175 // dst (out) pointer to new encrypted message or NULL if 1176 // no encryption could take place 1177 // enc_format (in) encrypted format 1178 // flags (in) flags to set special encryption features 1179 // 1180 // return value: 1181 // PEP_STATUS_OK on success 1182 // PEP_KEY_HAS_AMBIG_NAME at least one of the recipient 1183 // keys has an ambiguous name 1184 // PEP_UNENCRYPTED no recipients with usable key, 1185 // message is left unencrypted, 1186 // and key is attached to it 1187 // 1188 // caveat: 1189 // the ownership of src remains with the caller 1190 // the ownership of dst goes to the caller 1191 DYNAMIC_API PEP_STATUS encrypt_message( 1192 PEP_SESSION session, 1193 message *src, 1194 stringlist_t *extra, 1195 message **dst, 1196 PEP_enc_format enc_format, 1197 PEP_encrypt_flags_t flags 1198 ); 1200 Cf. src/message_api.h [SRC.pepcore]: 1202 A.3.2. Decrypting a Message 1204 Cf. src/message_api.h [SRC.pepcore]: 1206 // decrypt_message() - decrypt message in memory 1207 // 1208 // parameters: 1209 // session (in) session handle 1210 // src (in) message to decrypt 1211 // dst (out) pointer to new decrypted message 1212 // or NULL on failure 1213 // keylist (out) stringlist with keyids 1214 // rating (out) rating for the message 1215 // flags (out) flags to signal special decryption features 1216 // 1217 // return value: 1218 // error status 1219 // or PEP_DECRYPTED if message decrypted but not verified 1220 // or PEP_CANNOT_REENCRYPT if message was decrypted (and 1221 // possibly verified) but a reencryption operation is 1222 // expected by the caller and failed 1223 // or PEP_STATUS_OK on success 1224 // 1225 // flag values: 1226 // in: 1227 // PEP_decrypt_flag_untrusted_server 1228 // used to signal that decrypt function should engage in 1229 // behaviour specified for when the server storing the 1230 // source is untrusted 1231 // out: 1232 // PEP_decrypt_flag_own_private_key 1233 // private key was imported for one of our addresses 1234 // (NOT trusted or set to be used - handshake/trust is 1235 // required for that) 1236 // PEP_decrypt_flag_src_modified 1237 // indicates that the src object has been modified. At 1238 // the moment, this is always as a direct result of the 1239 // behaviour driven by the input flags. This flag is the 1240 // ONLY value that should be relied upon to see if such 1241 // changes have taken place. 1242 // PEP_decrypt_flag_consume 1243 // used by sync 1244 // PEP_decrypt_flag_ignore 1245 // used by sync 1246 // 1247 // 1248 // caveat: 1249 // the ownership of src remains with the caller - however, the 1250 // contents might be modified (strings freed and allocated anew 1251 // or set to NULL, etc) intentionally; when this happens, 1252 // PEP_decrypt_flag_src_modified is set. 1253 // the ownership of dst goes to the caller 1254 // the ownership of keylist goes to the caller 1255 // if src is unencrypted this function returns PEP_UNENCRYPTED 1256 // and sets 1257 // dst to NULL 1258 DYNAMIC_API PEP_STATUS decrypt_message( 1259 PEP_SESSION session, 1260 message *src, 1261 message **dst, 1262 stringlist_t **keylist, 1263 PEP_rating *rating, 1264 PEP_decrypt_flags_t *flags 1266 ); 1268 A.3.3. Obtain Common Trustwords 1270 Cf. src/message_api.h [SRC.pepcore]: 1272 // get_trustwords() - get full trustwords string 1273 // for a *pair* of identities 1274 // 1275 // parameters: 1276 // session (in) session handle 1277 // id1 (in) identity of first party in communication 1278 // - fpr can't be NULL 1279 // id2 (in) identity of second party in communication 1280 // - fpr can't be NULL 1281 // lang (in) C string with ISO 639-1 language code 1282 // words (out) pointer to C string with all trustwords 1283 // UTF-8 encoded, separated by a blank each 1284 // NULL if language is not supported or 1285 // trustword wordlist is damaged or unavailable 1286 // wsize (out) length of full trustwords string 1287 // full (in) if true, generate ALL trustwords for these 1288 // identities. 1289 // else, generate a fixed-size subset. 1290 // (TODO: fixed-minimum-entropy subset 1291 // in next version) 1292 // 1293 // return value: 1294 // PEP_STATUS_OK trustwords retrieved 1295 // PEP_OUT_OF_MEMORY out of memory 1296 // PEP_TRUSTWORD_NOT_FOUND at least one trustword not found 1297 // 1298 // caveat: 1299 // the word pointer goes to the ownership of the caller 1300 // the caller is responsible to free() it 1301 // (on Windoze use pEp_free()) 1302 // 1303 DYNAMIC_API PEP_STATUS get_trustwords( 1304 PEP_SESSION session, const pEp_identity* id1, 1305 const pEp_identity* id2, const char* lang, 1306 char **words, size_t *wsize, bool full 1307 ); 1309 Appendix B. Document Changelog 1311 [[ RFC Editor: This section is to be removed before publication ]] 1313 o draft-birk-pep-03: 1315 * Major restructure of the document 1317 * Adapt authors to the actual authors and extend acknowledgement 1318 section 1320 * Added several new sections, e.g., Key Reset, Trust Revoke, 1321 Trust Synchronization, Private Key Export / Import, Privacy 1322 Considerations (content yet mostly TODO) 1324 * Added reference to HRPC work / RFC8280 1326 + Added text and figure to better explain pEp's automated Key 1327 Exchange and Trust management (basic message flow) 1329 * Lots of improvement in text and editorial changes 1331 o draft-birk-pep-02: 1333 * Move (updated) code to Appendix 1335 * Add Changelog to Appendix 1337 * Add Open Issue section to Appendix 1339 * Fix description of what Extra Keys are 1341 * Fix Passive Mode description 1343 * Better explain pEp's identity system 1345 o draft-birk-pep-01: 1347 * Mostly editorial 1349 o draft-birk-pep-00: 1351 * Initial version 1353 Appendix C. Open Issues 1355 [[ RFC Editor: This section should be empty and is to be removed 1356 before publication ]] 1358 o References to RFC6973 (Privacy Considerations) 1360 o Add references to prior work, and what differs here - PEM (cf. 1361 RFC1421-1424) 1363 o Better explain Passive Mode 1365 o Better explain / illustrate pEp's identity system 1367 o Explain Key Mapping (to S/MIME) 1369 o Add more information to deal with organizational requirements 1371 o Add text to Key Reset (Section 5.4) as well as reference as soon 1372 as available 1374 o Add text to Trust Revoke (Section 6.4) as well as reference as 1375 soon as available 1377 o Add text to Trust Synchronization (Section 7.2) as well as 1378 reference as soon as available 1380 o Add references to Private Key Export / Import (Section 5.2.3) as 1381 soon as reference available 1383 o Add text to Privacy Considerations (Section 11) 1385 Authors' Addresses 1387 Hernani Marques 1388 pEp Foundation 1389 Oberer Graben 4 1390 CH-8400 Winterthur 1391 Switzerland 1393 Email: hernani.marques@pep.foundation 1394 URI: https://pep.foundation/ 1396 Bernie Hoeneisen 1397 Ucom Standards Track Solutions GmbH 1398 CH-8046 Zuerich 1399 Switzerland 1401 Phone: +41 44 500 52 44 1402 Email: bernie@ietf.hoeneisen.ch (bernhard.hoeneisen AT ucom.ch) 1403 URI: https://ucom.ch/