idnits 2.17.1 draft-mccain-keylist-02.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 (October 13, 2018) is 1993 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 363 -- Looks like a reference, but probably isn't: '2' on line 365 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. McCain 3 Internet-Draft FLM 4 Intended status: Experimental M. Lee 5 Expires: April 16, 2019 TI 6 N. Welch 7 FLM 8 October 13, 2018 10 Distributing OpenPGP Keys with Signed Keylist Subscriptions 11 draft-mccain-keylist-02 13 Abstract 15 This document specifies a system by which an OpenPGP client may 16 subscribe to an organization's keylist to keep its internal keystore 17 up-to-date. Ensuring that all members of an organization have their 18 colleagues' most recent PGP public keys is critical to maintaining 19 operational security. Without the most recent keys and a source of 20 trust for those keys (as this document specifies), users must 21 manually update and sign each others keys -- a system that is 22 untenable in larger organizations. This document proposes a 23 experimental format for the keylist file as well as requirements for 24 clients who wish to implement this experimental keylist subscription 25 functionality. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on April 16, 2019. 44 Copyright Notice 46 Copyright (c) 2018 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (https://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 62 1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 3 63 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.3. Note to Readers . . . . . . . . . . . . . . . . . . . . . 3 65 2. Functions and Procedures . . . . . . . . . . . . . . . . . . 3 66 2.1. Subscribing to Keylists . . . . . . . . . . . . . . . . . 4 67 2.2. Periodic Updates . . . . . . . . . . . . . . . . . . . . 4 68 2.3. Cryptographic Verification of Keylists . . . . . . . . . 5 69 3. Data Element Formats . . . . . . . . . . . . . . . . . . . . 5 70 3.1. Keylist . . . . . . . . . . . . . . . . . . . . . . . . . 5 71 3.2. Signature . . . . . . . . . . . . . . . . . . . . . . . . 6 72 4. In Practice . . . . . . . . . . . . . . . . . . . . . . . . . 7 73 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 74 5.1. Security Benefits . . . . . . . . . . . . . . . . . . . . 7 75 5.2. Security Drawbacks . . . . . . . . . . . . . . . . . . . 7 76 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 77 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 78 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 79 7.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 8 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 82 1. Introduction 84 This document specifies a system by which clients may subscribe to 85 cryptographically signed keylists. This system allows for seamless 86 key rotation across entire organizations and enhances operational 87 security. To enable cross-client compatibility, this document 88 provides a experimental format for the keylist, its cryptographic 89 verification, and the method by which it is retreived by the client. 90 The user interface by which a client provides this functionality to 91 the user is out of scope, as is the process by which the client 92 retrieves public keys. Other non-security-related implementation 93 details are also out of scope. 95 1.1. Requirements Notation 97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 99 document are to be interpreted as described in [RFC2119] . 101 1.2. Terminology 103 This document uses the terms "OpenPGP", "public key", "private key", 104 "signature", and "fingerprint" as defined by OpenPGP Message Format 105 [RFC4880] . 107 The term "keylist" is defined as a list of OpenPGP public key 108 fingerprints and accessible via a URI. The exact format of this data 109 is specified in Section 3 . 111 An "authority key" is defined as the OpenPGP secret key used to sign 112 a particular keylist. Every keylist has a corresponding authority 113 key, and every authority key has at least one corresponding keylist. 114 A single authority key SHOULD NOT be used to sign multiple keylists. 116 To be "subscribed" to a keylist means that a program will retreive 117 that keylist on a regular interval. After retrieval, that program 118 will perform an update to an internal OpenPGP keystore. 120 A "client" is a program that allows the user to subscribe to 121 keylists. A client may be an OpenPGP client itself or a separate 122 program that interfaces with an OpenPGP client to update its 123 keystore. 125 1.3. Note to Readers 127 RFC Editor: please remove this section prior to publication. 129 Development of this Internet draft takes place on GitHub at Keylist- 130 RFC [1]. 132 A mailing list is available for discussion at Keylists mailing list 133 [2]. 135 2. Functions and Procedures 137 As new keys are created and other keys are revoked, it is critical 138 that all members of an organization have the most recent set of keys 139 available on their computers. Keylists enable organizations to 140 publish a directory of OpenPGP keys that clients can use to keep 141 their internal keystores up-to-date. 143 2.1. Subscribing to Keylists 145 A single client may subscribe to any number of keylists. When a 146 client first subscribes to a keylist, it SHOULD update or import 147 every key present in the keylist into its local keystore. Keylist 148 subscriptions SHOULD be persistent --that is, they should be 149 permanently stored by the client to enable future automatic updates. 151 To subscribe to a keylist, the client must be aware of the keylist 152 URI (see [RFC3986]), and the fingerprint of the authority key used to 153 sign the keylist. The protocol used to retrieve the keylist and its 154 signature SHOULD be HTTPS (see [RFC2818]), however other 155 implementation MAY be supported. A client implementing keylist 156 functionality MUST support the retrieval of keylists and signatures 157 over HTTPS. All other protocols are OPTIONAL. 159 A client MUST NOT employ a trust-on-first-use model for determining 160 the fingerprint of the authority key; it must be explicitly provided 161 by the user. 163 The process by which the client stores its keylist subscriptions is 164 out of scope, as is the means by which subscription functionality is 165 exposed to the end-user. 167 2.2. Periodic Updates 169 The primary purpose of keylists is to enable periodic updates of 170 OpenPGP clients' internal keystores. We RECOMMEND that clients 171 provide a default refresh interval of less than one day, however we 172 also RECOMMEND that clients allow the user to select this interval. 173 The exact time at which updates are performed is not critical. 175 To perform an update, the client MUST perform the following steps on 176 each keylist to which it is subscribed. The steps SHOULD be 177 performed in the given order. 179 1. Obtain a current copy of the keylist from its URI. 181 2. Obtain a current copy of the keylist's signature data from its 182 URI, which is included in the keylist data format specified in 183 Section 3. 185 3. Using the keylist and the keylist's signature, cryptographically 186 verify that the keylist was signed using the authority key. If 187 the signature does not verify, the client MUST abort the update 188 of this keylist and SHOULD alert the user. The client SHOULD NOT 189 abort the update of other keylists to which it is subscribed, 190 unless they too fail signature verification. 192 4. Validate the format of the keylist according to Section 3 . If 193 the keylist is in an invalid format, the client MUST abort the 194 update this keylist and SHOULD alert the user. 196 5. For each fingerprint listed in the keyfile, if a copy of the 197 associated public key is not present in the client's local 198 keystore, retrieve it from the keyserver specified by the keylist 199 (see Section 3) or, if the keylist specifies no keyserver, from 200 any keyserver. If the key is already present and not revoked, 201 refresh it from a keyserver. If it is present and revoked, do 202 nothing. 204 2.3. Cryptographic Verification of Keylists 206 To ensure authenticity of a keylist during an update, the client MUST 207 verify that the keylist's data matches its cryptographic signature, 208 and that the public key used to verify the signature matches the 209 authority key fingerprint given by the user. 211 For enhanced security, it is RECOMMENDED that keylist operators sign 212 each public key listed in their keylist with the authority private 213 key. This way, an organization can have an internal trust 214 relationship without requiring members of the organization to certify 215 each other's public keys. 217 3. Data Element Formats 219 The following are format specifications for the keylist file and its 220 signature file. 222 3.1. Keylist 224 The keylist MUST be a valid JavaScript Object Notation (JSON) Data 225 Interchange Format [RFC8259] object with specific keys and values, as 226 defined below. Note that unless otherwise specified, 'key' in this 227 section refers to JSON keys--not OpenPGP keys. 229 To encode metadata, the keylist MUST have a "metadata" root key with 230 an object as the value ("metadata object"). The metadata object MUST 231 contain a "signature_uri" key whose value is the URI string of the 232 keylist's signature file. All metadata keys apart from 233 "signature_uri" are OPTIONAL. 235 The metadata object MAY contain a "keyserver" key with the value of 236 the URI string of the keyserver from which the OpenPGP keys in the 237 keylist should be retrieved. 239 The metadata object MAY contain a "comment" key with the value of any 240 string. The metadata object MAY also contain other arbitrary key- 241 value pairs. 243 The keylist MUST have a "keys" key with an array as the value. This 244 array contains a list of OpenPGP key fingerprints and metadata about 245 them. Each item in the array MUST be an object. Each of these 246 objects MUST have a "fingerprint" key with the value of a string that 247 contains the full 40-character hexadecimal public key fingerprint, as 248 defined in OpenPGP Message Format [RFC4880] . Any number of space 249 characters (' ', U+0020) MAY be included at any location in the 250 fingerprint string. These objects MAY contain "name", "email", and 251 "comment" key-value pairs, as well as any other key-value pairs 252 relevant. 254 The following is an example of a valid keylist. 256 { 257 "metadata": { 258 "signature_uri": "https://www.example.com/keylist.json.asc" 259 "comment": "This is an example of a keylist file" 260 }, 261 "keys": [ 262 { 263 "fingerprint": "927F419D7EC82C2F149C1BD1403C2657CD994F73", 264 "name": "Micah Lee", 265 "email": "micah.lee@theintercept.com", 266 "comment": "Each key can have a comment" 267 }, 268 { 269 "fingerprint": "1326CB162C6921BF085F8459F3C78280DDBF52A1", 270 "name": "R. Miles McCain", 271 "email": "0@rmrm.io" 272 }, 273 { 274 "fingerprint": "E0BE0804CF04A65C1FC64CC4CAD802E066046C02", 275 "name": "Nat Welch", 276 "email": "nat.welch@firstlook.org" 277 } 278 ] 279 } 281 3.2. Signature 283 The signature file MUST be an ASCII-armored 'detached signature' of 284 the keylist file, as defined in OpenPGP Message Format [RFC4880] . 286 4. In Practice 288 GPG Sync, an open source program created by one of the authors, 289 implements this experimental standard. GPG Sync is used by First 290 Look Media and the Freedom of the Press Foundation to keep OpenPGP 291 keys in sync across their organizations, as well as to publish their 292 employee's OpenPGP keys to the world. These organizations 293 collectively employ more than 200 people and have used the system 294 described in this document successfully for multiple years. 296 GPG Sync's existing code can be found at 297 299 First Look Media's keylist file can be found at 300 302 5. Security Considerations 304 5.1. Security Benefits 306 The keylist subscription functionality defined in this document 307 provide a number of security benefits, including: 309 o The ability for new keys to be quickly distributed across an 310 organization. 312 o It removes the complexity of key distribution from end users, 313 allowing them to focus on the content of their communications 314 rather than on key management. 316 o The ability for an organization to prevent the spread of falsely 317 attributed keys by centralizing the public key discovery process 318 within their organization. 320 5.2. Security Drawbacks 322 There is a situation in which keylist subscriptions could pose a 323 potential security threat. If the both the authority key and the 324 keylist distribution system were to be compromised, it would be 325 possible for an attacker to distribute false keys. We believe, 326 however, that the security benefits of this system strongly outweigh 327 the drawbacks. 329 6. IANA Considerations 331 This document has no actions for IANA. 333 7. References 335 7.1. Normative References 337 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 338 Requirement Levels", BCP 14, RFC 2119, 339 DOI 10.17487/RFC2119, March 1997, 340 . 342 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 343 DOI 10.17487/RFC2818, May 2000, 344 . 346 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 347 Resource Identifier (URI): Generic Syntax", STD 66, 348 RFC 3986, DOI 10.17487/RFC3986, January 2005, 349 . 351 [RFC4880] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R. 352 Thayer, "OpenPGP Message Format", RFC 4880, 353 DOI 10.17487/RFC4880, November 2007, 354 . 356 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 357 Interchange Format", STD 90, RFC 8259, 358 DOI 10.17487/RFC8259, December 2017, 359 . 361 7.2. URIs 363 [1] https://github.com/firstlookmedia/keylist-rfc 365 [2] https://www.freelists.org/list/keylists 367 Authors' Addresses 369 R. Miles McCain 370 First Look Media 372 Email: ietf@sendmiles.email 373 URI: https://rmrm.io 375 Micah Lee 376 The Intercept 378 Email: micah.lee@theintercept.com 379 URI: https://micahflee.com/ 380 Nat Welch 381 First Look Media 383 Email: nat.welch@firstlook.media 384 URI: https://natwelch.com