├── .gitignore
├── Makefile
├── README.md
├── rfc.xml
└── submissions
    ├── draft-mccain-keylist-00.xml
    ├── draft-mccain-keylist-01.xml
    ├── draft-mccain-keylist-02.xml
    ├── draft-mccain-keylist-03.xml
    ├── draft-mccain-keylist-04.xml
    └── draft-mccain-keylist-05.xml


/.gitignore:
--------------------------------------------------------------------------------
1 | .DS_Store
2 | rfc.html
3 | 


--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
 1 | all: serve
 2 | 
 3 | html: rfc.xml
 4 | 	xml2rfc --html rfc.xml
 5 | 
 6 | serve: html
 7 | 	open http://0.0.0.0:8000/rfc.html
 8 | 	python3 -m http.server
 9 | 
10 | linux-serve: html
11 | 	xdg-open http://0.0.0.0:8000/rfc.html
12 | 	python3 -m http.server


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Keylist RFC
 2 | 
 3 | This repository contains the materials produced in the preparation of the RFC to standardize the keylist format and functionality provided by [GPG Sync](https://github.com/firstlookmedia/gpgsync).
 4 | 
 5 | ##### What's with the weird filenames?
 6 | The IETF specifies that independently submitted I-D (Internet-Drafts) should follow the filename format `draft-[first author's last name]-[document name]-[version]`. `rfc.xml` is where development takes place. When a new version of the I-D is submitted, a copy of the `.xml` file submitted at that time is copied to the `submissions` directory.
 7 | 
 8 | ## Quick Links
 9 | * [IETF Datatracker](https://datatracker.ietf.org/doc/draft-mccain-keylist/) (for reading the official copy of the document)
10 | * [Mailing list](https://www.freelists.org/list/keylists) (for discussion and development)
11 | 
12 | ## Development
13 | 
14 |  - edit `rfc.xml`
15 |  - `pip install xml2rfc`
16 |  - `make`
17 | 
18 | ## Relevant Documents
19 | 
20 | Non-RFC documents relevant to the preparation of this RFC are listed below.
21 | 
22 | * [The IETF Area List](https://www.ietf.org/topics/areas/)
23 | * [RFC Editorial Guidelines and Procedures](https://www.rfc-editor.org/policy.html#policy.auth)
24 | * [IETF Standards Process](https://www.ietf.org/standards/process/)
25 | 
26 | ## Relevant RFCs
27 | 
28 | RFCs that are potentially relevant to the preparation of this document are listed below. This list includes both RFC style guides and existing RFCs related to OpenPGP.
29 | 
30 | * [RFC7322](https://tools.ietf.org/html/rfc7322): RFC Style Guide
31 | * [RFC7997](https://tools.ietf.org/html/rfc7997): The Use of Non-ASCII Characters in RFCs
32 | * [RFC2026](https://tools.ietf.org/html/rfc2026): The Internet Standards Process (rev.3; note: errata exist)
33 | * [RFC4880](https://www.rfc-editor.org/rfc/rfc4880.txt): OpenPGP Message Format
34 | * [RFC2629](https://tools.ietf.org/html/rfc2629): Writing I-Ds and RFCs using XML
35 | 
36 | ## Updates
37 | * **August 6, 2018** — first draft published
38 | * **August 21, 2018** — mailing list created
39 | * **August 22, 2018** — second draft published
40 | * **October 13, 2018** — third draft published
41 | 
42 | ## TODO
43 | * [ ] Expand acronyms on first use
44 | * [x] List normative and informative references
45 | 


--------------------------------------------------------------------------------
/rfc.xml:
--------------------------------------------------------------------------------
  1 | <?xml version="1.0"?>
  2 | <?rfc toc="yes"?>
  3 | <?rfc symrefs="yes"?>
  4 | <?rfc sortrefs="yes"?>
  5 | <?rfc compact="yes"?>
  6 | <?rfc subcompact="no"?>
  7 | <!DOCTYPE rfc SYSTEM "rfc2629.dtd">
  8 | <rfc ipr="trust200902" docName="draft-mccain-keylist-05" category="std">
  9 | 	<!-- TODO: We should verify that 'trust200902' is the intellectual property
 10 | 	designation we want. ~MM -->
 11 | 	<!-- TODO: figure out which category this goes in. ~MM -->
 12 | 	<front>
 13 | 		<!-- Working title. We'll want something that more accurately frames the
 14 | 		system before we submit. It never also hurts to have a more catchy
 15 | 		title... -->
 16 | 		<title abbrev="OpenPGP Keylist Subscriptions">
 17 | 			Distributing OpenPGP Key Fingerprints with Signed Keylist Subscriptions
 18 | 		</title>
 19 | 		<author initials="M.M." surname="McCain" fullname="R. Miles McCain">
 20 | 			<organization abbrev="FLM">
 21 | 				First Look Media
 22 | 			</organization>
 23 | 			<address>
 24 | 				<email>
 25 | 					ietf@sendmiles.email
 26 | 				</email>
 27 | 				<uri>
 28 | 					https://rmrm.io
 29 | 				</uri>
 30 | 			</address>
 31 | 		</author>
 32 | 		<author initials="M.L." surname="Lee" fullname="Micah Lee">
 33 | 			<organization abbrev="TI">
 34 | 				The Intercept
 35 | 			</organization>
 36 | 			<address>
 37 | 				<email>
 38 | 					micah.lee@theintercept.com
 39 | 				</email>
 40 | 				<uri>
 41 | 					https://micahflee.com/
 42 | 				</uri>
 43 | 			</address>
 44 | 		</author>
 45 | 		<author initials="N.D.W." surname="Welch" fullname="Nat Welch">
 46 | 			<organization abbrev="Google">
 47 | 				Google
 48 | 			</organization>
 49 | 			<address>
 50 | 				<email>
 51 | 					nat@natwelch.com
 52 | 				</email>
 53 | 				<uri>
 54 | 					https://natwelch.com
 55 | 				</uri>
 56 | 			</address>
 57 | 		</author>
 58 | 		<date month="September" year="2019" day="2" />
 59 | 		<area>
 60 | 			Security
 61 | 		</area>
 62 | 		<keyword>
 63 | 			OpenPGP
 64 | 		</keyword>
 65 | 		<keyword>
 66 | 			GPGSync
 67 | 		</keyword>
 68 | 		<keyword>
 69 | 			GPG
 70 | 		</keyword>
 71 | 		<keyword>
 72 | 			Keylist
 73 | 		</keyword>
 74 | 		<abstract>
 75 | 			<t>
 76 | 				This document specifies a system by which an OpenPGP client may subscribe
 77 | 				to an organization's public keylist to keep its keystore up-to-date with
 78 | 				correct keys from the correct keyserver(s), even in cases where the keys correspond to multiple
 79 | 				(potentially uncontrolled) domains. Ensuring that all members or followers
 80 | 				of an organization have their colleagues' most recent PGP public keys is
 81 | 				critical to maintaining operational security. Without the most recent
 82 | 				keys' fingerprints and a source of trust for those keys (as this document
 83 | 				specifies), users must manually update and sign each others' keys -- a
 84 | 				system that is untenable in larger organizations. This document proposes a
 85 | 				experimental format for the keylist file as well as requirements for
 86 | 				clients who wish to implement this experimental keylist subscription
 87 | 				functionality.
 88 | 			</t>
 89 | 			<!-- We'll want to tighten this abstract up a bit... ~MM -->
 90 | 			<!-- ^ I did what I could. ~MM -->
 91 | 		</abstract>
 92 | 	</front>
 93 | 	<middle>
 94 | 		<section anchor="intro" title="Introduction">
 95 | 			<t>
 96 | 				 This document specifies a system by which clients may subscribe to
 97 | 				 cryptographically signed 'keylists' of public key fingerprints. The public
 98 | 				 keys do not necesssarily all correspond to a single domain. This system
 99 | 				 enhances operational security by allowing seamless key rotation across
100 | 				 entire organizations without centralized public key hosting. To enable
101 | 				 cross-client compatibility, this document provides a experimental format
102 | 				 for the keylist, its cryptographic verification, and the method by which it
103 | 				 is retreived by the client. The user interface by which a client provides
104 | 				 this functionality to the user is out of scope, as is the process by which
105 | 				 the client retrieves public keys. Other non-security-related implementation
106 | 				 details are also out of scope.
107 | 			</t>
108 | 			<section anchor="notation" title="Requirements Notation">
109 | 				<t>
110 | 					The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
111 | 					"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
112 | 					and "OPTIONAL" in this document are to be interpreted as
113 | 					described in
114 | 					<xref target="RFC2119" />
115 | 					.
116 | 				</t>
117 | 			</section>
118 | 			<section anchor="terminology" title="Terminology">
119 | 				<t>
120 | 					This document uses the terms "OpenPGP", "public key",
121 | 					"private key", "signature", and "fingerprint" as defined by
122 | 					OpenPGP Message Format
123 | 					<xref target="RFC4880" />
124 | 					(the fingerprint type SHOULD be V4).
125 | 					<!-- TODO: clarify the _type_ of fingerprints we use (ideally V4/SHA-160) -->
126 | 				</t>
127 | 				<!-- TODO: add unicode definitions. ~MM -->
128 | 				<!-- TODO: verify that all the previous terms are actually
129 | 				defined in RFC4880. ~MM -->
130 | 				<!-- TODO: does 'URI' and 'Internet' need a citation? Probably
131 | 				not, but we should check. ~MM -->
132 | 				<t>
133 | 					 The term "keylist" is defined as a list of OpenPGP public key fingerprints
134 | 					 accessible via a URI in the format specified in
135 | 					 <xref target="formats" />. Keylists SHOULD be treated as public
136 | 					 documents, however a system administrator MAY choose, for example, to
137 | 					 restrict access to a keylist to a specific subnet or private network.
138 | 				</t>
139 | 				<!-- TODO: I avoid using the word 'file' here as it has a
140 | 				nuanced meaning and really we're just talking about data
141 | 				accessible via a URI. Is there a term other than 'data' that is
142 | 				appropriate here? ~MM -->
143 | 				<!-- I think this is fine. ~NDW -->
144 | 				<t>
145 | 					An "authority key" is defined as the OpenPGP secret key used
146 | 					to sign a particular keylist. Every keylist has a
147 | 					corresponding authority key, and every authority key has at
148 | 					least one corresponding keylist. A single authority key
149 | 					SHOULD NOT be used to sign multiple keylists.
150 | 				</t>
151 | 				<!-- I'm not opposed to it, but why shouldn't the same authority
152 | 				key be used to sign multiple keylists? I think it'd be confusing
153 | 				in the UI in GPG Sync if you do this, because they keylist is
154 | 				displayed by the authority key's UID. But from a security
155 | 				standpoint, it should be probably be just as secure. ~ML -->
156 | 				<!-- I removed the reference to security. One potential
157 | 				consideration, though, is that this sentence is less about the
158 | 				spec and more about the end user. Perhaps we should just remove
159 | 				the reference all together because it doesn't fit into the
160 | 				implementation but rather the end user's habits? Could be a
161 | 				point of criticism. ~MM -->
162 | 				<t>
163 | 					To be "subscribed" to a keylist means that a program will
164 | 					retreive that keylist on a regular interval. After
165 | 					retrieval, that program will perform an update to an
166 | 					internal OpenPGP keystore.
167 | 				</t>
168 | 				<!-- TODO: This needs to be cleaned/tightened. ~MM -->
169 | 				<t>
170 | 					A "client" is a program that allows the user to subscribe to
171 | 					keylists. A client may be an OpenPGP client itself or a
172 | 					separate program that interfaces with an OpenPGP client to
173 | 					update its keystore.
174 | 				</t>
175 | 			</section>
176 | 			<section anchor="note-to-readers" title="Note to Readers">
177 | 				<t>RFC Editor: please remove this section prior to
178 | 				publication.</t>
179 | 				<t>Development of this Internet draft takes place on GitHub at
180 | 				<eref
181 | 				target="https://github.com/firstlookmedia/keylist-rfc">firstlookmedia/Keylist-RFC</eref>.
182 | 				</t>
183 | 				<t>We are still considering whether this Draft is better for the Experimental or
184 | 				Informational track. All feedback is appreciated.</t>
185 | 			</section>
186 | 		</section>
187 | 		<section anchor="functions" title="Functions and Procedures">
188 | 			<t>
189 | 				As new keys are created and other keys are revoked, it is
190 | 				critical that all members of an organization have the most
191 | 				recent set of keys available on their computers. Keylists enable
192 | 				organizations to publish a directory of OpenPGP keys that
193 | 				clients can use to keep their internal keystores up-to-date.
194 | 			</t>
195 | 			<section anchor="keylist-subscribe" title="Subscribing to Keylists">
196 | 				<t>
197 | 					A single client may subscribe to any number of keylists.
198 | 					When a client first subscribes to a keylist, it SHOULD
199 | 					update or import every key present in the keylist into its
200 | 					local keystore. Keylist subscriptions SHOULD be persistent
201 | 					-- that is, they should be permanently stored by the client
202 | 					to enable future automatic updates.
203 | 				</t>
204 | 				<t>
205 | 					To subscribe to a keylist, the client must be aware of the
206 | 					keylist URI (see <xref target="RFC3986" />), and the
207 | 					fingerprint of the authority key used to sign the
208 | 					keylist. The protocol used to retrieve the keylist and its
209 | 					signature SHOULD be HTTPS (see <xref target="RFC2818" />),
210 | 					however other implementation MAY be supported. A client
211 | 					implementing keylist functionality MUST support the
212 | 					retrieval of keylists and signatures over HTTPS. All other
213 | 					protocols are OPTIONAL.
214 | 				</t>
215 | 				<t>
216 | 					A client MUST NOT employ a trust-on-first-use (TOFU) model for
217 | 					determining the fingerprint of the authority public key; the
218 | 					authority public key fingerprint must be explicitly provided
219 | 					by the user.
220 | 				</t>
221 | 				<t>
222 | 					The process by which the client stores its keylist
223 | 					subscriptions is out of scope, as is the means by which
224 | 					subscription functionality is exposed to the end-user.
225 | 				</t>
226 | 				<t>
227 | 					The client MAY provide the option to perform all its network
228 | 					activity over a SOCKS5 proxy (see <xref target="RFC1928" />).
229 | 				</t>
230 | 			</section>
231 | 			<section anchor="keylist-update" title="Automatic Updates">
232 | 				<t>
233 | 					The primary purpose of keylists is to enable periodic
234 | 					updates of OpenPGP clients' internal keystores. We RECOMMEND
235 | 					that clients provide automatic 'background' update functionality;
236 | 					we also regonize that automatic background updates are not possible
237 | 					in every application (specifically cross-platform CLI tools).
238 | 				</t>
239 | 				<t>When automatic background updates are provided, we RECOMMEND
240 | 					that clients provide a default refresh interval of less than
241 | 					one day, however we also RECOMMEND that clients allow the
242 | 					user to select this interval. The exact time at which
243 | 					updates are performed is not critical.
244 | 				</t>
245 | 				<t>
246 | 					To perform an update, the client MUST perform the following
247 | 					steps on each keylist to which it is subscribed. The steps
248 | 					SHOULD be performed in the given order.
249 | 				</t>
250 | 				<t>
251 | 					<list style="numbers">
252 | 						<t>
253 | 							Obtain a current copy of the keylist from its URI. If a
254 | 							current copy (i.e. not from local cache) cannot be obtained,
255 | 							the client SHOULD abort the update for this keylist and notify
256 | 							the user. The client SHOULD continue the update for other keylists
257 | 							to which it is subscribed, notwithstanding also failing the criteria
258 | 							described in this section.
259 | 						</t>
260 | 						<t>
261 | 							Obtain a current copy of the keylist's signature
262 | 							data from its URI, which is included in the keylist data
263 | 							format specified in <xref target="formats" />. If a current copy
264 | 							cannot be obtained, the client SHOULD abort the update and notify
265 | 							the user. The client SHOULD continue the update for other keylists
266 | 							to which it is subscribed, notwithstanding also failing the criteria
267 | 							described in this section.
268 | 						</t>
269 | 						<!-- I say 'obtain' rather than retrieve because I want
270 | 						to leave open the possibility of a client checking to
271 | 						see if the hash of the file, for example, has changed,
272 | 						and only re-requesting if it has. 'Obtain' is also very
273 | 						ambiguous, though, so it may be to our advantage to use
274 | 						something more specific or explain this rationale
275 | 						outright. ~MM -->
276 | 						<!-- we should be verifying a checksum, and be explicit
277 | 						about it in this description. ~NDW -->
278 | 						<t>
279 | 							Using the keylist and the keylist's signature,
280 | 							cryptographically verify that the keylist was signed
281 | 							using the authority key. If the signature does not
282 | 							verify, the client MUST abort the update of this
283 | 							keylist and SHOULD alert the user. The client SHOULD
284 | 							NOT abort the update of other keylists to which it
285 | 							is subscribed, unless they too fail signature
286 | 							verification.
287 | 						</t>
288 | 						<t>
289 | 							Validate the format of the keylist according to
290 | 							<xref target="formats" />
291 | 							. If the keylist is in an invalid format, the client
292 | 							MUST abort the update this keylist and SHOULD alert
293 | 							the user. The client SHOULD continue the update for
294 | 							other keylists to which it is subscribed, notwithstanding
295 | 							also failing the criteria described in this section.
296 | 						</t>
297 | 						<t>
298 | 							For each fingerprint listed in the keyfile, if a
299 | 							copy of the associated public key is not present in
300 | 							the client's local keystore, retrieve it from the
301 | 							keyserver specified by either the key entry, the keylist (see
302 | 							<xref target="formats" />) or, if the keylist specifies
303 | 							no keyserver, from the user's default keyserver. If the public
304 | 							key cannot be found for a particular fingerprint, the client
305 | 							MUST NOT abort the entire update process; instead, it SHOULD
306 | 							notify the user that the key retrieval failed but otherwise
307 | 							merely skip updating the key and continue.
308 | 							If the key is already present and not revoked,
309 | 							refresh it from the keyserver determined in the same 
310 | 							manner as above. If it is present and revoked, do nothing
311 | 							for that particular key.
312 | 						</t>
313 | 						<!-- TODO: Is it overkill to establish some concept of a
314 | 						'linked keystore' as the keystore that the client
315 | 						interacts with and keeps updated? This is a potential
316 | 						ambiguity for machines with multiple keystores. ~MM -->
317 | 						<!-- That could be useful, but I'd leave that up to the
318 | 						client. Maybe add a recommendation that says something
319 | 						around letting users specify which keystore they want to
320 | 						sync to? It seems slightly out of scope as you are
321 | 						saying retrival and update is out of scope. ~NDW -->
322 | 						<!-- TODO: Should anything else be in this list? ~MM -->
323 | 					</list>
324 | 				</t>
325 | 			</section>
326 | 			<section anchor="keylist-crypto" title="Cryptographic Verification of Keylists">
327 | 				<t>
328 | 					To ensure authenticity of a keylist during an update, the
329 | 					client MUST verify that the keylist's data matches its
330 | 					cryptographic signature, and that the public key used to
331 | 					verify the signature matches the authority key fingerprint
332 | 					given by the user.
333 | 				</t>
334 | 				<t>
335 | 					For enhanced security, it is RECOMMENDED that keylist
336 | 					operators sign each public key listed in their keylist with
337 | 					the authority private key. This way, an organization can
338 | 					have an internal trust relationship without requiring
339 | 					members of the organization to certify each other's public
340 | 					keys.
341 | 				</t>
342 | 			</section>
343 | 		</section>
344 | 		<section anchor="formats" title="Data Element Formats">
345 | 			<t>
346 | 				The following are format specifications for the keylist file and
347 | 				its signature file.
348 | 			</t>
349 | 			<section anchor="keylist-format" title="Keylist">
350 | 				<t>
351 | 					The keylist MUST be a valid JavaScript Object Notation
352 | 					(JSON) Data Interchange Format
353 | 					<xref target="RFC8259" /> object with specific keys
354 | 					and values, as defined below. Note that unless otherwise specified,
355 | 					'key' in this section refers to JSON keys -- not OpenPGP keys.
356 | 				</t>
357 | 				<t>
358 | 					To encode metadata, the keylist MUST have a "metadata" root key
359 | 					with an object as the value ("metadata object").
360 | 					The metadata object MUST contain a "signature_uri" key whose value
361 | 					is the URI string of the keylist's signature file. All metadata keys
362 | 					apart from "signature_uri" are OPTIONAL.
363 | 				</t>
364 | 				<t>
365 | 					The metadata object MAY contain a "keyserver" key with the value of the
366 | 					URI string of a HKP keyserver from which the OpenPGP keys in the keylist
367 | 					should be retrieved. Each PGP key listed in the keylist MAY have a
368 | 					"keyserver" JSON key; if a PGP key in the keylist specifies a HKP keyserver that is
369 | 					different from the one described in the metadata object, the PGP key-specific
370 | 					keyserver should be used to retrieve that particular key (and not the key listed
371 | 					in the metadata object).
372 | 				</t>
373 | 				<t>
374 | 					The metadata object MAY contain a "comment" key with the
375 | 					value of any string. The metadata object MAY also contain other arbitrary
376 | 					key-value pairs.
377 | 				</t>
378 | 				<!-- TODO: Should we specify in more detail what a keyserver URI
379 | 				is, or even what a keyserver is? More details here:
380 | 				https://github.com/firstlookmedia/keylist-rfc/issues/8#issuecomment-427133308
381 | 				~ML -->
382 | 				<t>
383 | 					The keylist MUST have a "keys" key with an array as the value.
384 | 					This array contains a list of OpenPGP key fingerprints and
385 | 					metadata about them. Each item in the array MUST be an object.
386 | 					Each of these objects MUST have a "fingerprint" key with the
387 | 					value of a string that contains the full 40-character
388 | 					hexadecimal public key fingerprint, as defined in OpenPGP
389 | 					Message Format
390 | 					<xref target="RFC4880" />
391 | 					. Any number of space characters (' ', U+0020) MAY be included
392 | 					at any location in the fingerprint string. These objects MAY
393 | 					contain "name" (the name of the PGP key's owner), "email" 
394 | 					(an email of the PGP key's owner), "keyserver" (a HKP keyserver 
395 | 					from which the key should be retrieved), and "comment" key-value pairs,
396 | 					as well as any other key-value pairs.
397 | 					<!-- Maybe the edit here was a bit _too_ reductive. Let me know if you
398 | 					think I cut too much. The thinking is really that "name", "email", and
399 | 					"comment" keys are really just optional, so it makes sense to merge them
400 | 					into a single sentence, but I'm also completely open to reverting this
401 | 					change if you prefer the old phrasing! -->
402 | 				</t>
403 | 				<t>
404 | 					The following is an example of a valid keylist.
405 | 				</t>
406 | 				<figure>
407 | 					<artwork>
408 | {
409 |   "metadata": {
410 |     "signature_uri": "https://www.example.com/keylist.json.asc",
411 |     "comment": "This is an example of a keylist file"
412 |   },
413 |   "keys": [
414 |     {
415 |       "fingerprint": "927F419D7EC82C2F149C1BD1403C2657CD994F73",
416 |       "name": "Micah Lee",
417 |       "email": "micah.lee@theintercept.com",
418 |       "comment": "Each key can have a comment"
419 |     },
420 |     {
421 |       "fingerprint": "1326CB162C6921BF085F8459F3C78280DDBF52A1",
422 |       "name": "R. Miles McCain",
423 |       "email": "0@rmrm.io",
424 | 	  "keyserver": "https://keys.openpgp.org/"
425 |     },
426 |     {
427 |       "fingerprint": "E0BE0804CF04A65C1FC64CC4CAD802E066046C02",
428 |       "name": "Nat Welch",
429 |       "email": "nat.welch@firstlook.org"
430 |     }
431 |   ]
432 | }
433 | 					</artwork>
434 | 				</figure>
435 | 			</section>
436 | 			<section anchor="sigfile" title="Signature">
437 | 				<t>
438 | 					The signature file MUST be an ASCII-armored 'detached
439 | 					signature' of the keylist file, as defined in OpenPGP
440 | 					Message Format
441 | 					<xref target="RFC4880" />
442 | 					.
443 | 				</t>
444 | 			</section>
445 | 			<section anchor="wellknown" title="Well-Known URL">
446 | 				<t>
447 | 					Keylists SHOULD NOT be well-known resources <xref target="RFC4880" />.
448 | 					To subscribe to a keylist, the client must be aware not only of the keylist's
449 | 					location, but also of the fingerprint of the authority public key used to sign the keylist.
450 | 					Furthermore, because keylists can reference public keys from several different domains,
451 | 					the expected host of the well-known location for a keylist may not always be self-evident.
452 | 				</t>
453 | 			</section>
454 | 		</section>
455 | 		<section anchor="implementation" title="Implementation Status">
456 | 			<t>
457 | 				GPG Sync, an open source program created by one of the authors,
458 | 				implements this experimental standard. GPG Sync is used by First
459 | 				Look Media and the Freedom of the Press Foundation to keep
460 | 				OpenPGP keys in sync across their organizations, as well as to
461 | 				publish their employee's OpenPGP keys to the world. These
462 | 				organizations collectively employ more than 200 people and have
463 | 				used the system described in this document successfully for
464 | 				multiple years.
465 | 			</t>
466 | 			<t>
467 | 				GPG Sync's existing code can be found at
468 | 				&lt;https://github.com/firstlookmedia/gpgsync&gt;
469 | 			</t>
470 | 			<t>
471 | 				First Look Media's keylist file can be found at
472 | 				&lt;https://github.com/firstlookmedia/gpgsync-firstlook-fingerprints&gt;
473 | 			</t>
474 | 			<!-- TODO: clunky. We could clean this. ~MM -->
475 | 		</section>
476 | 		<section anchor="securitybenefits" title="Security Benefits">
477 | 			<t>
478 | 				The keylist subscription functionality defined in this
479 | 				document provides a number of security benefits, including:
480 | 			</t>
481 | 			<t>
482 | 				<list style="symbols">
483 | 					<t>
484 | 						The ability for new keys to be quickly distributed
485 | 						across an organization.
486 | 					</t>
487 | 					<t>
488 | 						Removing the complexity of key distribution from
489 | 						end users, allowing them to focus on the content of
490 | 						their communications rather than on key management.
491 | 					</t>
492 | 					<t>
493 | 						The ability for an organization to prevent the
494 | 						spread of falsely attributed keys by centralizing
495 | 						the public key discovery process within their
496 | 						organization without centralized public key hosting.
497 | 					</t>
498 | 					<!-- TODO: others? ~MM -->
499 | 				</list>
500 | 			</t>
501 | 		</section>
502 | 		<section anchor="comparison" title="Relation to Other Technologies">
503 | 			<section anchor="wkd" title="Web Key Directories">
504 | 				<t>
505 | 					Unlike Web Key Directories, keylists are not domain specific. A keylist
506 | 					might contain public key fingerprints for email addresses across several
507 | 					different domains. Moreover, keylists only provide references to public
508 | 					keys by way of fingerprints; Web Key Directories provide the public keys
509 | 					themselves.
510 | 				</t>
511 | 			</section>
512 | 			<section anchor="dns" title="OPENPGPKEY DNS Records">
513 | 				<t>
514 | 					 A keylist MAY reference public keys corresponding to email addresses
515 | 					 across several different domains. Because managing OPENPGPKEY DNS Records
516 | 					 <xref target="RFC7929" /> for a particular domain requires control of that
517 | 					 domain, the OPENPGPKEY DNS Record system is not suitable for cases in
518 | 					 which keys are strewn about several different domains, including ones
519 | 					 outside of the control of an organization's system adminitrators.
520 | 				</t>
521 | 			</section>
522 | 			<!-- We'll want to clean this up, but the messaging we'd like to convey is there. -->
523 | 		</section>
524 | 		<section anchor="securityconsiderations" title="Security Considerations">
525 | 				<t>
526 | 					There is a situation in which keylist subscriptions could
527 | 					pose a potential security threat. If both the authority
528 | 					key and the keylist distribution system were to be
529 | 					compromised, it would be possible for an attacker to
530 | 					distribute any key of their choosing to the subscribers of the
531 | 					keylist. The potential consequences of this attack are limited,
532 | 					however, because the attacker cannot remove or modify the keys
533 | 					already present on subscribers' systems.
534 | 				</t>
535 | 				<t>
536 | 					Some organizations may wish to keep their keylists private. While
537 | 					this may be achievable by serving keylists at URIs only accessible from
538 | 					specific subnets, keylists are designed to be public
539 | 					documents. As such, clients may leak the contents of keylists to
540 | 					keyservers -- this specification ensures to the best of its ability
541 | 					the integrity of keylists, but not the privacy of keylists.
542 | 				</t>
543 | 			<!-- TODO, see https://tools.ietf.org/html/bcp72 ~MM -->
544 | 		</section>
545 | 		<section anchor="ianaconsiderations" title="IANA Considerations">
546 | 			<t>
547 | 				This document has no actions for IANA.
548 | 			</t>
549 | 		</section>
550 | 	</middle>
551 | 	<back>
552 | 		<references title="Normative References">
553 | 			<?rfc include="reference.RFC.7929.xml"?>
554 | 			<?rfc include="reference.RFC.4880.xml"?>
555 | 			<?rfc include="reference.RFC.3986.xml"?>
556 | 			<?rfc include="reference.RFC.2119.xml"?>
557 | 			<?rfc include="reference.RFC.8259.xml"?>
558 | 			<?rfc include="reference.RFC.2818.xml"?>
559 | 			<?rfc include="reference.RFC.1928.xml"?>
560 | 		</references>
561 | 		<!--
562 | 		<references title="Informative References"> </references>
563 | 		-->
564 | 	</back>
565 | </rfc>
566 | 


--------------------------------------------------------------------------------
/submissions/draft-mccain-keylist-00.xml:
--------------------------------------------------------------------------------
  1 | <?xml version="1.0"?>
  2 | <?rfc toc="yes"?>
  3 | <?rfc symrefs="yes"?>
  4 | <?rfc sortrefs="yes"?>
  5 | <?rfc compact="yes"?>
  6 | <?rfc subcompact="no"?>
  7 | <!DOCTYPE rfc SYSTEM "rfc2629.dtd">
  8 | <rfc ipr="trust200902" docName="draft-mccain-keylist-00" category="exp">
  9 | 	<!-- TODO: We should verify that 'trust200902' is the intellectual property
 10 | 	designation we want. ~MM -->
 11 | 	<!-- TODO: figure out which category this goes in. ~MM -->
 12 | 	<front>
 13 | 		<!-- Working title. We'll want something that more accurately frames the
 14 | 		system before we submit. It never also hurts to have a more catchy
 15 | 		title... -->
 16 | 		<title abbrev="OpenPGP Keylist Subscriptions">
 17 | 			Distributing OpenPGP Keys with Signed Keylist Subscriptions
 18 | 		</title>
 19 | 		<author initials="M.M." surname="McCain" fullname="R. Miles McCain">
 20 | 			<organization abbrev="FLM">
 21 | 				First Look Media
 22 | 			</organization>
 23 | 			<address>
 24 | 				<email>
 25 | 					ietf@sendmiles.email
 26 | 				</email>
 27 | 				<uri>
 28 | 					https://rmrm.io
 29 | 				</uri>
 30 | 			</address>
 31 | 		</author>
 32 | 		<author initials="M.L." surname="Lee" fullname="Micah Lee">
 33 | 			<organization abbrev="TI">
 34 | 				The Intercept
 35 | 			</organization>
 36 | 			<address>
 37 | 				<email>
 38 | 					micah.lee@theintercept.com
 39 | 				</email>
 40 | 				<uri>
 41 | 					https://micahflee.com/
 42 | 				</uri>
 43 | 			</address>
 44 | 		</author>
 45 | 		<author initials="N.D.W." surname="Welch" fullname="Nat Welch">
 46 | 			<organization abbrev="FLM">
 47 | 				First Look Media
 48 | 			</organization>
 49 | 			<address>
 50 | 				<email>
 51 | 					nat.welch@firstlook.media
 52 | 				</email>
 53 | 				<uri>
 54 | 					https://natwelch.com
 55 | 				</uri>
 56 | 			</address>
 57 | 		</author>
 58 | 		<date month="August" year="2018" day="6" />
 59 | 		<area>
 60 | 			Security
 61 | 		</area>
 62 | 		<keyword>
 63 | 			OpenPGP
 64 | 		</keyword>
 65 | 		<keyword>
 66 | 			GPGSync
 67 | 		</keyword>
 68 | 		<keyword>
 69 | 			GPG
 70 | 		</keyword>
 71 | 		<keyword>
 72 | 			Keylist
 73 | 		</keyword>
 74 | 		<abstract>
 75 | 			<t>
 76 | 				This document specifies a system by which an OpenPGP client may
 77 | 				subscribe to an organization's keylist to keep its internal
 78 | 				keystore up-to-date. Ensuring that all members of an
 79 | 				organization have their colleagues' most recent PGP public keys
 80 | 				is critical to maintaining operational security. Without the
 81 | 				most recent keys and a source of trust for those keys (as this
 82 | 				document specifies), users must manually update and sign each
 83 | 				others keys -- a system that is untenable in larger
 84 | 				organizations. This document proposes a standard format for the
 85 | 				keylist file as well as requirements for clients who wish to
 86 | 				implement keylist subscription functionality.
 87 | 			</t>
 88 | 			<!-- We'll want to tighten this abstract up a bit... ~MM -->
 89 | 			<!-- ^ I did what I could. ~MM -->
 90 | 		</abstract>
 91 | 	</front>
 92 | 	<middle>
 93 | 		<section anchor="intro" title="Introduction">
 94 | 			<t>
 95 | 				This document specifies a system by which clients may subscribe
 96 | 				to cryptographically signed keylists. This system allows for
 97 | 				seamless key rotation across entire organizations and enhances
 98 | 				operational security. To enable cross-client compatibility, this
 99 | 				document provides a standard format for the keylist, its
100 | 				cryptographic verification, and the method by which it is
101 | 				retreived by the client. The user interface by which a client
102 | 				provides this functionality to the user is out of scope, as is
103 | 				the process by which the client retrieves public keys. Other
104 | 				non-security-related implementation details are also out of
105 | 				scope.
106 | 			</t>
107 | 			<section anchor="notation" title="Requirements Notation">
108 | 				<t>
109 | 					The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
110 | 					"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
111 | 					and "OPTIONAL" in this document are to be interpreted as
112 | 					described in
113 | 					<xref target="RFC2119" />
114 | 					.
115 | 				</t>
116 | 			</section>
117 | 			<section anchor="terminology" title="Terminology">
118 | 				<t>
119 | 					This document uses the terms "OpenPGP", "public key",
120 | 					"private key", "signature", and "fingerprint" as defined by
121 | 					OpenPGP Message Format
122 | 					<xref target="RFC4880" />
123 | 					.
124 | 				</t>
125 | 				<!-- TODO: add unicode definitions. ~MM -->
126 | 				<!-- TODO: verify that all the previous terms are actually
127 | 				defined in RFC4880. ~MM -->
128 | 				<!-- TODO: does 'URI' and 'Internet' need a citation? Probably
129 | 				not, but we should check. ~MM -->
130 | 				<t>
131 | 					The term "keylist" is defined as a list of OpenPGP public
132 | 					keys identified by their fingerprints and accessible via a
133 | 					URI. The exact format of this data is specified in
134 | 					<xref target="formats" />
135 | 					.
136 | 				</t>
137 | 				<!-- TODO: I avoid using the word 'file' here as it has a
138 | 				nuanced meaning and really we're just talking about data
139 | 				accessible via a URI. Is there a term other than 'data' that is
140 | 				appropriate here? ~MM -->
141 | 				<!-- I think this is fine. ~NDW -->
142 | 				<t>
143 | 					An "authority key" is defined as the OpenPGP secret key used
144 | 					to sign a particular keylist. Every keylist has a
145 | 					corresponding authority key, and every authority key has at
146 | 					least one corresponding keylist. A single authority key
147 | 					SHOULD NOT be used to sign multiple keylists.
148 | 				</t>
149 | 				<!-- I'm not opposed to it, but why shouldn't the same authority
150 | 				key be used to sign multiple keylists? I think it'd be confusing
151 | 				in the UI in GPG Sync if you do this, because they keylist is
152 | 				displayed by the authority key's UID. But from a security
153 | 				standpoint, it should be probably be just as secure. ~ML -->
154 | 				<!-- I removed the reference to security. One potential
155 | 				consideration, though, is that this sentence is less about the
156 | 				spec and more about the end user. Perhaps we should just remove
157 | 				the reference all together because it doesn't fit into the
158 | 				implementation but rather the end user's habits? Could be a
159 | 				point of criticism. ~MM -->
160 | 				<t>
161 | 					To be "subscribed" to a keylist means that a program will
162 | 					retreive that keylist on a regular interval. After
163 | 					retrieval, that program will perform an update to an
164 | 					internal OpenPGP keystore.
165 | 				</t>
166 | 				<!-- TODO: This needs to be cleaned/tightened. ~MM -->
167 | 				<t>
168 | 					A "client" is a program that allows the user to subscribe to
169 | 					keylists. A client may be an OpenPGP client itself or a
170 | 					separate program that interfaces with an OpenPGP client to
171 | 					update its keystore.
172 | 				</t>
173 | 			</section>
174 | 		</section>
175 | 		<section anchor="functions" title="Functions and Procedures">
176 | 			<t>
177 | 				As new keys are created and other keys are revoked, it is
178 | 				critical that all members of an organization have the most
179 | 				recent set of keys available on their computers. Keylists enable
180 | 				organizations to publish a directory of OpenPGP keys that
181 | 				clients can use to keep their internal keystores up-to-date.
182 | 			</t>
183 | 			<section anchor="keylist-subscribe" title="Subscribing to Keylists">
184 | 				<t>
185 | 					A single client may subscribe to any number of keylists.
186 | 					When a client first subscribes to a keylist, it SHOULD
187 | 					update or import every key present in the keylist into its
188 | 					local keystore. Keylist subscriptions SHOULD be persistent
189 | 					--that is, they should be permanently stored by the client
190 | 					to enable future automatic updates.
191 | 				</t>
192 | 				<t>
193 | 					To subscribe to a keylist, the client must be aware of the
194 | 					keylist URI (defined in
195 | 					<xref target="RFC3986" />
196 | 					), the keylist's signature URI, and the fingerprint of the
197 | 					authority key used to sign the keylist. The protocol used to
198 | 					retrieve thbe keylist and its signature SHOULD be HTTPS (see
199 | 					<xref target="RFC2818" />
200 | 					), however other implementation are possible. A client
201 | 					implementing keylist functionality MUST support the
202 | 					retrieval of keylists and signatures over HTTPS. All other
203 | 					protocols are OPTIONAL.
204 | 				</t>
205 | 				<t>
206 | 					A client MUST NOT employ a trust-on-first-use model for
207 | 					determining the fingerprint of the authority key; it must be
208 | 					explicitly provided by the user.
209 | 				</t>
210 | 				<t>
211 | 					The process by which the client stores its keylist
212 | 					subscriptions is out of scope, as is the means by which
213 | 					subscription functionality is exposed to the end-user.
214 | 				</t>
215 | 			</section>
216 | 			<section anchor="keylist-update" title="Periodic Updates">
217 | 				<t>
218 | 					The primary purpose of keylists is to enable periodic
219 | 					updates of OpenPGP clients' internal keystores. We RECOMMEND
220 | 					that clients provide a default refresh interval of less than
221 | 					one day, however we also RECOMMEND that clients allow the
222 | 					user to select this interval. The exact time at which
223 | 					updates are performed is not critical.
224 | 				</t>
225 | 				<t>
226 | 					To perform an update, the client MUST perform the following
227 | 					steps on each keylist to which it is subscribed. The steps
228 | 					SHOULD be performed in the given order.
229 | 				</t>
230 | 				<t>
231 | 					<list style="numbers">
232 | 						<t>
233 | 							Obtain a current copy of the keylist from its URI.
234 | 						</t>
235 | 						<t>
236 | 							Obtain a current copy of the keylist's signature
237 | 							data from its URI.
238 | 						</t>
239 | 						<!-- I say 'obtain' rather than retrieve because I want
240 | 						to leave open the possibility of a client checking to
241 | 						see if the hash of the file, for example, has changed,
242 | 						and only re-requesting if it has. 'Obtain' is also very
243 | 						ambiguous, though, so it may be to our advantage to use
244 | 						something more specific or explain this rationale
245 | 						outright. ~MM -->
246 | 						<!-- we should be verifying a checksum, and be explicit
247 | 						about it in this description. ~NDW -->
248 | 						<t>
249 | 							Using the keylist and the keylist's signature,
250 | 							cryptographically verify that the keylist was signed
251 | 							using the authority key. If the signature does not
252 | 							verify, the client MUST abort the update of this
253 | 							keylist and SHOULD alert the user. The client SHOULD
254 | 							NOT abort the update of other keylists to which it
255 | 							is subscribed, unless they too fail signature
256 | 							verification.
257 | 						</t>
258 | 						<t>
259 | 							Validate the format of the keylist according to
260 | 							<xref target="formats" />
261 | 							. If the keylist is in an invalid format, the client
262 | 							MUST abort the update this keylist and SHOULD alert
263 | 							the user.
264 | 						</t>
265 | 						<t>
266 | 							For each fingerprint listed in the keyfile, if a
267 | 							copy of the associated public key is not present in
268 | 							the client's local keystore, retrieve it from a
269 | 							keyserver. If it is already present and not revoked,
270 | 							refresh it from a keyserver. If it is present and
271 | 							revoked, ignore it. The method by which keys are
272 | 							retrieved and updated is out of scope.
273 | 						</t>
274 | 						<!-- TODO: Is it overkill to establish some concept of a
275 | 						'linked keystore' as the keystore that the client
276 | 						interacts with and keeps updated? This is a potential
277 | 						ambiguity for machines with multiple keystores. ~MM -->
278 | 						<!-- That could be useful, but I'd leave that up to the
279 | 						client. Maybe add a recommendation that says something
280 | 						around letting users specify which keystore they want to
281 | 						sync to? It seems slightly out of scope as you are
282 | 						saying retrival and update is out of scope. ~NDW -->
283 | 						<!-- TODO: Should anything else be in this list? ~MM -->
284 | 					</list>
285 | 				</t>
286 | 			</section>
287 | 			<section anchor="keylist-crypto" title="Cryptographic Verification
288 | 			of Keylists">
289 | 				<t>
290 | 					To ensure authenticity of a keylist during an update, the
291 | 					client MUST verify that the keylist's data matches its
292 | 					cryptographic signature, and that the public key used to
293 | 					verify the signature matches the authority key fingerprint
294 | 					given by the user.
295 | 				</t>
296 | 				<t>
297 | 					For enhanced security, it is RECOMMENDED that keylist
298 | 					operators sign each public key listed in their keylist with
299 | 					the authority private key. This way, an organization can
300 | 					have an internal trust relationship without requiring
301 | 					members of the organization to certify each other's public
302 | 					keys.
303 | 				</t>
304 | 			</section>
305 | 		</section>
306 | 		<section anchor="formats" title="Data Element Formats">
307 | 			<t>
308 | 				The following are definitions of the data types we will be
309 | 				creating to support this new feature set.
310 | 			</t>
311 | 			<section anchor="terms" title="Keylist">
312 | 				<t>
313 | 					The keylist MUST be encoded in UTF-8
314 | 					<xref target="RFC3629" />
315 | 					. Each line MUST begin either with a comment, a public key
316 | 					fingerprint, or whitespace. A comment is defined as a string
317 | 					of characters between a hash symbol (#, U+0023) and a
318 | 					newline or an end of file (EOF). The keylist SHOULD end with
319 | 					a newline. The fingerprint MUST be the full 40-character
320 | 					hexadecimal public key fingerprint, as defined in OpenPGP
321 | 					Message Format
322 | 					<xref target="RFC4880" />
323 | 					. Space characters (' ', U+0020) MAY be included anywhere in
324 | 					the fingerprint. Lines SHOULD NOT exceed 128 characters in
325 | 					length.
326 | 				</t>
327 | 				<t>
328 | 					It is RECOMMENDED that keylist maintainers describe each key
329 | 					using a comment, for example:
330 | 				</t>
331 | 				<figure>
332 | 					<artwork>1326 CB16 ... DDBF 52A1 # Miles' Key</artwork>
333 | 				</figure>
334 | 				<!-- TODO: there must be better notation for this... ~MM -->
335 | 				<!-- In v3, there is <sourcecode> ~NDW -->
336 | 				<!-- TODO: I'm actually ambivalent about this recommendation. I
337 | 				think fingerprints without spaces are just as good - in the end,
338 | 				the point of the keylist is to be machine readable more than
339 | 				human readable anyway. ~ML -->
340 | 				<!-- ^ I was mostly referring to my use of the `<t>` tag for
341 | 				example notation. :) ~MM -->
342 | 				<t>
343 | 					To extract the public key fingerprints from a keylist, a
344 | 					client SHOULD perform the following steps, in order:
345 | 				</t>
346 | 				<t>
347 | 					<list style="numbers">
348 | 						<t>
349 | 							Strip the keylist of all comments, as defined above,
350 | 							including the preceding hash symbol but excluding
351 | 							the trailing newline.
352 | 						</t>
353 | 						<t>
354 | 							Strip the keylist of all non-breaking whitespace.
355 | 						</t>
356 | 					</list>
357 | 				</t>
358 | 				<t>
359 | 					Performing these steps will result in one public key
360 | 					fingerprint per line.
361 | 				</t>
362 | 				<!-- TODO: find the way to properly define unicode ~MM -->
363 | 				<!-- TODO: call it a file? Don't call it a file? What is the
364 | 				best path? It's an internet resource. ~MM -->
365 | 				<!-- I say let's keep the wording you have and show it to
366 | 				others, and see their thoughts on calling it a "file". ~ML -->
367 | 				<!-- TODO: adopt 'nonbreaking whitespace'/a citation from the
368 | 				Unicode RFC. ~MM -->
369 | 				<!-- TODO: ^ ask if the above is necessary, and if so, figure
370 | 				out how to do it. ~MM -->
371 | 			</section>
372 | 			<section anchor="sigfile" title="Signature">
373 | 				<t>
374 | 					The signature file MUST be an ASCII-armored 'detached
375 | 					signature' of the keylist file, as defined in OpenPGP
376 | 					Message Format
377 | 					<xref target="RFC4880" />
378 | 					.
379 | 				</t>
380 | 				<!-- TODO: Should we specify ASCII armored or not? At the
381 | 				moment, GPG Sync doesn't ASCII-armor the signature file, and
382 | 				it's a .sig, however I see no probably with using an
383 | 				ASCII-armored .asc file instead (and of course, I don't think
384 | 				there's any reason to require specific file extensions. It's
385 | 				just a URI after all, and this way you can choose to host the
386 | 				keylist and sig in, for example, github gists.) ~ML -->
387 | 				<!-- RESOLVED; I added language that specified ascii-armored.
388 | 				For all the reasons you specify, I think this is the best
389 | 				option. ~MM -->
390 | 			</section>
391 | 		</section>
392 | 		<section anchor="inpractice" title="In Practice">
393 | 			<t>
394 | 				GPG Sync, an open source program created by one of the authors,
395 | 				implements this experimental standard. GPG Sync is used by First
396 | 				Look Media and the Freedom of the Press Foundation to keep
397 | 				OpenPGP keys in sync across their organizations, as well as to
398 | 				publish their employee's OpenPGP keys to the world. These
399 | 				organizations collectively employ more than 200 people and have
400 | 				used the system described in this document successfully for
401 | 				multiple years.
402 | 			</t>
403 | 			<t>
404 | 				GPG Sync's existing code can be found at
405 | 				&lt;https://github.com/firstlookmedia/gpgsync&gt;
406 | 			</t>
407 | 			<t>
408 | 				First Look Media's keylist file can be found at
409 | 				&lt;https://github.com/firstlookmedia/gpgsync-firstlook-fingerprints&gt;
410 | 			</t>
411 | 			<!-- TODO: clunky. We could clean this. ~MM -->
412 | 		</section>
413 | 		<section anchor="securityconsiderations" title="Security Considerations">
414 | 			<section anchor="securitybenefits" title="Security Benefits">
415 | 				<t>
416 | 					The keylist subscription functionality defined in this
417 | 					document provide a number of security benefits, including:
418 | 				</t>
419 | 				<t>
420 | 					<list style="symbols">
421 | 						<t>
422 | 							The ability for new keys to be quickly distributed
423 | 							across an organization.
424 | 						</t>
425 | 						<t>
426 | 							It removes the complexity of key distribution from
427 | 							end users, allowing them to focus on the content of
428 | 							their communications rather than on key management.
429 | 						</t>
430 | 						<t>
431 | 							The ability for an organization to prevent the
432 | 							spread of falsely attributed keys by centralizing
433 | 							the public key discovery process within their
434 | 							organization.
435 | 						</t>
436 | 						<!-- TODO: others? ~MM -->
437 | 					</list>
438 | 				</t>
439 | 			</section>
440 | 			<section anchor="securitydrawbacks" title="Security Drawbacks">
441 | 				<t>
442 | 					There is a situation in which keylist subscriptions could
443 | 					pose a potential security threat. If the authority key and
444 | 					the keylist distribution system were to both be compromised,
445 | 					it would be possible for an attacker to distribute false
446 | 					keys. We believe, however, that the security benefits of
447 | 					this system strongly outweigh the drawbacks.
448 | 				</t>
449 | 				<t>
450 | 					If the client does not perform an update regularly, there is
451 | 					the possibility that keys will be just as outdated as they
452 | 					would be without a keylist subscription.
453 | 				</t>
454 | 			</section>
455 | 			<!-- TODO, see https://tools.ietf.org/html/bcp72 ~MM -->
456 | 		</section>
457 | 		<section anchor="ianaconsiderations" title="IANA Considerations">
458 | 			<t>
459 | 				This document has no actions for IANA.
460 | 			</t>
461 | 		</section>
462 | 	</middle>
463 | 	<back>
464 | 		<references title="Normative References">
465 | 			<?rfc include="reference.RFC.4880.xml"?>
466 | 			<?rfc include="reference.RFC.3986.xml"?>
467 | 			<?rfc include="reference.RFC.2119.xml"?>
468 | 			<?rfc include="reference.RFC.3629.xml"?>
469 | 			<?rfc include="reference.RFC.2818.xml"?>
470 | 		</references>
471 | 		<!--
472 | 		<references title="Informative References"> </references>
473 | 		-->
474 | 	</back>
475 | </rfc>
476 | 


--------------------------------------------------------------------------------
/submissions/draft-mccain-keylist-01.xml:
--------------------------------------------------------------------------------
  1 | <?xml version="1.0"?>
  2 | <?rfc toc="yes"?>
  3 | <?rfc symrefs="yes"?>
  4 | <?rfc sortrefs="yes"?>
  5 | <?rfc compact="yes"?>
  6 | <?rfc subcompact="no"?>
  7 | <!DOCTYPE rfc SYSTEM "rfc2629.dtd">
  8 | <rfc ipr="trust200902" docName="draft-mccain-keylist-01" category="exp">
  9 | 	<!-- TODO: We should verify that 'trust200902' is the intellectual property
 10 | 	designation we want. ~MM -->
 11 | 	<!-- TODO: figure out which category this goes in. ~MM -->
 12 | 	<front>
 13 | 		<!-- Working title. We'll want something that more accurately frames the
 14 | 		system before we submit. It never also hurts to have a more catchy
 15 | 		title... -->
 16 | 		<title abbrev="OpenPGP Keylist Subscriptions">
 17 | 			Distributing OpenPGP Keys with Signed Keylist Subscriptions
 18 | 		</title>
 19 | 		<author initials="M.M." surname="McCain" fullname="R. Miles McCain">
 20 | 			<organization abbrev="FLM">
 21 | 				First Look Media
 22 | 			</organization>
 23 | 			<address>
 24 | 				<email>
 25 | 					ietf@sendmiles.email
 26 | 				</email>
 27 | 				<uri>
 28 | 					https://rmrm.io
 29 | 				</uri>
 30 | 			</address>
 31 | 		</author>
 32 | 		<author initials="M.L." surname="Lee" fullname="Micah Lee">
 33 | 			<organization abbrev="TI">
 34 | 				The Intercept
 35 | 			</organization>
 36 | 			<address>
 37 | 				<email>
 38 | 					micah.lee@theintercept.com
 39 | 				</email>
 40 | 				<uri>
 41 | 					https://micahflee.com/
 42 | 				</uri>
 43 | 			</address>
 44 | 		</author>
 45 | 		<author initials="N.D.W." surname="Welch" fullname="Nat Welch">
 46 | 			<organization abbrev="FLM">
 47 | 				First Look Media
 48 | 			</organization>
 49 | 			<address>
 50 | 				<email>
 51 | 					nat.welch@firstlook.media
 52 | 				</email>
 53 | 				<uri>
 54 | 					https://natwelch.com
 55 | 				</uri>
 56 | 			</address>
 57 | 		</author>
 58 | 		<date month="August" year="2018" day="21" />
 59 | 		<area>
 60 | 			Security
 61 | 		</area>
 62 | 		<keyword>
 63 | 			OpenPGP
 64 | 		</keyword>
 65 | 		<keyword>
 66 | 			GPGSync
 67 | 		</keyword>
 68 | 		<keyword>
 69 | 			GPG
 70 | 		</keyword>
 71 | 		<keyword>
 72 | 			Keylist
 73 | 		</keyword>
 74 | 		<abstract>
 75 | 			<t>
 76 | 				This document specifies a system by which an OpenPGP client may
 77 | 				subscribe to an organization's keylist to keep its internal
 78 | 				keystore up-to-date. Ensuring that all members of an
 79 | 				organization have their colleagues' most recent PGP public keys
 80 | 				is critical to maintaining operational security. Without the
 81 | 				most recent keys and a source of trust for those keys (as this
 82 | 				document specifies), users must manually update and sign each
 83 | 				others keys -- a system that is untenable in larger
 84 | 				organizations. This document proposes a experimental format for
 85 | 				the keylist file as well as requirements for clients who wish to
 86 | 				implement this experimental keylist subscription functionality.
 87 | 			</t>
 88 | 			<!-- We'll want to tighten this abstract up a bit... ~MM -->
 89 | 			<!-- ^ I did what I could. ~MM -->
 90 | 		</abstract>
 91 | 	</front>
 92 | 	<middle>
 93 | 		<section anchor="intro" title="Introduction">
 94 | 			<t>
 95 | 				This document specifies a system by which clients may subscribe
 96 | 				to cryptographically signed keylists. This system allows for
 97 | 				seamless key rotation across entire organizations and enhances
 98 | 				operational security. To enable cross-client compatibility, this
 99 | 				document provides a experimental format for the keylist, its
100 | 				cryptographic verification, and the method by which it is
101 | 				retreived by the client. The user interface by which a client
102 | 				provides this functionality to the user is out of scope, as is
103 | 				the process by which the client retrieves public keys. Other
104 | 				non-security-related implementation details are also out of
105 | 				scope.
106 | 			</t>
107 | 			<section anchor="notation" title="Requirements Notation">
108 | 				<t>
109 | 					The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
110 | 					"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
111 | 					and "OPTIONAL" in this document are to be interpreted as
112 | 					described in
113 | 					<xref target="RFC2119" />
114 | 					.
115 | 				</t>
116 | 			</section>
117 | 			<section anchor="terminology" title="Terminology">
118 | 				<t>
119 | 					This document uses the terms "OpenPGP", "public key",
120 | 					"private key", "signature", and "fingerprint" as defined by
121 | 					OpenPGP Message Format
122 | 					<xref target="RFC4880" />
123 | 					.
124 | 				</t>
125 | 				<!-- TODO: add unicode definitions. ~MM -->
126 | 				<!-- TODO: verify that all the previous terms are actually
127 | 				defined in RFC4880. ~MM -->
128 | 				<!-- TODO: does 'URI' and 'Internet' need a citation? Probably
129 | 				not, but we should check. ~MM -->
130 | 				<t>
131 | 					The term "keylist" is defined as a list of OpenPGP public
132 | 					keys identified by their fingerprints and accessible via a
133 | 					URI. The exact format of this data is specified in
134 | 					<xref target="formats" />
135 | 					.
136 | 				</t>
137 | 				<!-- TODO: I avoid using the word 'file' here as it has a
138 | 				nuanced meaning and really we're just talking about data
139 | 				accessible via a URI. Is there a term other than 'data' that is
140 | 				appropriate here? ~MM -->
141 | 				<!-- I think this is fine. ~NDW -->
142 | 				<t>
143 | 					An "authority key" is defined as the OpenPGP secret key used
144 | 					to sign a particular keylist. Every keylist has a
145 | 					corresponding authority key, and every authority key has at
146 | 					least one corresponding keylist. A single authority key
147 | 					SHOULD NOT be used to sign multiple keylists.
148 | 				</t>
149 | 				<!-- I'm not opposed to it, but why shouldn't the same authority
150 | 				key be used to sign multiple keylists? I think it'd be confusing
151 | 				in the UI in GPG Sync if you do this, because they keylist is
152 | 				displayed by the authority key's UID. But from a security
153 | 				standpoint, it should be probably be just as secure. ~ML -->
154 | 				<!-- I removed the reference to security. One potential
155 | 				consideration, though, is that this sentence is less about the
156 | 				spec and more about the end user. Perhaps we should just remove
157 | 				the reference all together because it doesn't fit into the
158 | 				implementation but rather the end user's habits? Could be a
159 | 				point of criticism. ~MM -->
160 | 				<t>
161 | 					To be "subscribed" to a keylist means that a program will
162 | 					retreive that keylist on a regular interval. After
163 | 					retrieval, that program will perform an update to an
164 | 					internal OpenPGP keystore.
165 | 				</t>
166 | 				<!-- TODO: This needs to be cleaned/tightened. ~MM -->
167 | 				<t>
168 | 					A "client" is a program that allows the user to subscribe to
169 | 					keylists. A client may be an OpenPGP client itself or a
170 | 					separate program that interfaces with an OpenPGP client to
171 | 					update its keystore.
172 | 				</t>
173 | 			</section>
174 | 			<section anchor="note-to-readers" title="Note to Readers">
175 | 				<t>RFC Editor: please remove this section prior to
176 | 				publication.</t>
177 | 				<t>Development of this Internet draft takes place on GitHub at
178 | 				<eref 
179 | 				target="https://github.com/firstlookmedia/keylist-rfc">Keylist-RFC</eref>.
180 | 				</t>
181 | 				<t>A mailing list is available for discussion at <eref
182 | 				target="https://www.freelists.org/list/keylists">Keylists
183 | 				mailing list</eref>.</t>
184 | 			</section>
185 | 		</section>
186 | 		<section anchor="functions" title="Functions and Procedures">
187 | 			<t>
188 | 				As new keys are created and other keys are revoked, it is
189 | 				critical that all members of an organization have the most
190 | 				recent set of keys available on their computers. Keylists enable
191 | 				organizations to publish a directory of OpenPGP keys that
192 | 				clients can use to keep their internal keystores up-to-date.
193 | 			</t>
194 | 			<section anchor="keylist-subscribe" title="Subscribing to Keylists">
195 | 				<t>
196 | 					A single client may subscribe to any number of keylists.
197 | 					When a client first subscribes to a keylist, it SHOULD
198 | 					update or import every key present in the keylist into its
199 | 					local keystore. Keylist subscriptions SHOULD be persistent
200 | 					--that is, they should be permanently stored by the client
201 | 					to enable future automatic updates.
202 | 				</t>
203 | 				<t>
204 | 					To subscribe to a keylist, the client must be aware of the
205 | 					keylist URI (defined in
206 | 					<xref target="RFC3986" />
207 | 					), the keylist's signature URI, and the fingerprint of the
208 | 					authority key used to sign the keylist. The protocol used to
209 | 					retrieve thbe keylist and its signature SHOULD be HTTPS (see
210 | 					<xref target="RFC2818" />
211 | 					), however other implementation are possible. A client
212 | 					implementing keylist functionality MUST support the
213 | 					retrieval of keylists and signatures over HTTPS. All other
214 | 					protocols are OPTIONAL.
215 | 				</t>
216 | 				<t>
217 | 					A client MUST NOT employ a trust-on-first-use model for
218 | 					determining the fingerprint of the authority key; it must be
219 | 					explicitly provided by the user.
220 | 				</t>
221 | 				<t>
222 | 					The process by which the client stores its keylist
223 | 					subscriptions is out of scope, as is the means by which
224 | 					subscription functionality is exposed to the end-user.
225 | 				</t>
226 | 			</section>
227 | 			<section anchor="keylist-update" title="Periodic Updates">
228 | 				<t>
229 | 					The primary purpose of keylists is to enable periodic
230 | 					updates of OpenPGP clients' internal keystores. We RECOMMEND
231 | 					that clients provide a default refresh interval of less than
232 | 					one day, however we also RECOMMEND that clients allow the
233 | 					user to select this interval. The exact time at which
234 | 					updates are performed is not critical.
235 | 				</t>
236 | 				<t>
237 | 					To perform an update, the client MUST perform the following
238 | 					steps on each keylist to which it is subscribed. The steps
239 | 					SHOULD be performed in the given order.
240 | 				</t>
241 | 				<t>
242 | 					<list style="numbers">
243 | 						<t>
244 | 							Obtain a current copy of the keylist from its URI.
245 | 						</t>
246 | 						<t>
247 | 							Obtain a current copy of the keylist's signature
248 | 							data from its URI.
249 | 						</t>
250 | 						<!-- I say 'obtain' rather than retrieve because I want
251 | 						to leave open the possibility of a client checking to
252 | 						see if the hash of the file, for example, has changed,
253 | 						and only re-requesting if it has. 'Obtain' is also very
254 | 						ambiguous, though, so it may be to our advantage to use
255 | 						something more specific or explain this rationale
256 | 						outright. ~MM -->
257 | 						<!-- we should be verifying a checksum, and be explicit
258 | 						about it in this description. ~NDW -->
259 | 						<t>
260 | 							Using the keylist and the keylist's signature,
261 | 							cryptographically verify that the keylist was signed
262 | 							using the authority key. If the signature does not
263 | 							verify, the client MUST abort the update of this
264 | 							keylist and SHOULD alert the user. The client SHOULD
265 | 							NOT abort the update of other keylists to which it
266 | 							is subscribed, unless they too fail signature
267 | 							verification.
268 | 						</t>
269 | 						<t>
270 | 							Validate the format of the keylist according to
271 | 							<xref target="formats" />
272 | 							. If the keylist is in an invalid format, the client
273 | 							MUST abort the update this keylist and SHOULD alert
274 | 							the user.
275 | 						</t>
276 | 						<t>
277 | 							For each fingerprint listed in the keyfile, if a
278 | 							copy of the associated public key is not present in
279 | 							the client's local keystore, retrieve it from a
280 | 							keyserver. If it is already present and not revoked,
281 | 							refresh it from a keyserver. If it is present and
282 | 							revoked, ignore it. The method by which keys are
283 | 							retrieved and updated is out of scope.
284 | 						</t>
285 | 						<!-- TODO: Is it overkill to establish some concept of a
286 | 						'linked keystore' as the keystore that the client
287 | 						interacts with and keeps updated? This is a potential
288 | 						ambiguity for machines with multiple keystores. ~MM -->
289 | 						<!-- That could be useful, but I'd leave that up to the
290 | 						client. Maybe add a recommendation that says something
291 | 						around letting users specify which keystore they want to
292 | 						sync to? It seems slightly out of scope as you are
293 | 						saying retrival and update is out of scope. ~NDW -->
294 | 						<!-- TODO: Should anything else be in this list? ~MM -->
295 | 					</list>
296 | 				</t>
297 | 			</section>
298 | 			<section anchor="keylist-crypto" title="Cryptographic Verification
299 | 			of Keylists">
300 | 				<t>
301 | 					To ensure authenticity of a keylist during an update, the
302 | 					client MUST verify that the keylist's data matches its
303 | 					cryptographic signature, and that the public key used to
304 | 					verify the signature matches the authority key fingerprint
305 | 					given by the user.
306 | 				</t>
307 | 				<t>
308 | 					For enhanced security, it is RECOMMENDED that keylist
309 | 					operators sign each public key listed in their keylist with
310 | 					the authority private key. This way, an organization can
311 | 					have an internal trust relationship without requiring
312 | 					members of the organization to certify each other's public
313 | 					keys.
314 | 				</t>
315 | 			</section>
316 | 		</section>
317 | 		<section anchor="formats" title="Data Element Formats">
318 | 			<t>
319 | 				The following are definitions of the data types we will be
320 | 				creating to support this new feature set.
321 | 			</t>
322 | 			<section anchor="terms" title="Keylist">
323 | 				<t>
324 | 					The keylist MUST be encoded in UTF-8
325 | 					<xref target="RFC3629" />
326 | 					. Each line MUST begin either with a comment, a public key
327 | 					fingerprint, or whitespace. A comment is defined as a string
328 | 					of characters between a hash symbol (#, U+0023) and a
329 | 					newline or an end of file (EOF). The keylist SHOULD end with
330 | 					a newline. The fingerprint MUST be the full 40-character
331 | 					hexadecimal public key fingerprint, as defined in OpenPGP
332 | 					Message Format
333 | 					<xref target="RFC4880" />
334 | 					. Space characters (' ', U+0020) MAY be included anywhere in
335 | 					the fingerprint. Lines SHOULD NOT exceed 128 characters in
336 | 					length.
337 | 				</t>
338 | 				<t>
339 | 					It is RECOMMENDED that keylist maintainers describe each key
340 | 					using a comment, for example:
341 | 				</t>
342 | 				<figure>
343 | 					<artwork>1326 CB16 ... DDBF 52A1 # Miles' Key</artwork>
344 | 				</figure>
345 | 				<!-- TODO: there must be better notation for this... ~MM -->
346 | 				<!-- In v3, there is <sourcecode> ~NDW -->
347 | 				<!-- TODO: I'm actually ambivalent about this recommendation. I
348 | 				think fingerprints without spaces are just as good - in the end,
349 | 				the point of the keylist is to be machine readable more than
350 | 				human readable anyway. ~ML -->
351 | 				<!-- ^ I was mostly referring to my use of the `<t>` tag for
352 | 				example notation. :) ~MM -->
353 | 				<t>
354 | 					To extract the public key fingerprints from a keylist, a
355 | 					client SHOULD perform the following steps, in order:
356 | 				</t>
357 | 				<t>
358 | 					<list style="numbers">
359 | 						<t>
360 | 							Strip the keylist of all comments, as defined above,
361 | 							including the preceding hash symbol but excluding
362 | 							the trailing newline.
363 | 						</t>
364 | 						<t>
365 | 							Strip the keylist of all non-breaking whitespace.
366 | 						</t>
367 | 					</list>
368 | 				</t>
369 | 				<t>
370 | 					Performing these steps will result in one public key
371 | 					fingerprint per line.
372 | 				</t>
373 | 				<!-- TODO: find the way to properly define unicode ~MM -->
374 | 				<!-- TODO: call it a file? Don't call it a file? What is the
375 | 				best path? It's an internet resource. ~MM -->
376 | 				<!-- I say let's keep the wording you have and show it to
377 | 				others, and see their thoughts on calling it a "file". ~ML -->
378 | 				<!-- TODO: adopt 'nonbreaking whitespace'/a citation from the
379 | 				Unicode RFC. ~MM -->
380 | 				<!-- TODO: ^ ask if the above is necessary, and if so, figure
381 | 				out how to do it. ~MM -->
382 | 			</section>
383 | 			<section anchor="sigfile" title="Signature">
384 | 				<t>
385 | 					The signature file MUST be an ASCII-armored 'detached
386 | 					signature' of the keylist file, as defined in OpenPGP
387 | 					Message Format
388 | 					<xref target="RFC4880" />
389 | 					.
390 | 				</t>
391 | 				<!-- TODO: Should we specify ASCII armored or not? At the
392 | 				moment, GPG Sync doesn't ASCII-armor the signature file, and
393 | 				it's a .sig, however I see no probably with using an
394 | 				ASCII-armored .asc file instead (and of course, I don't think
395 | 				there's any reason to require specific file extensions. It's
396 | 				just a URI after all, and this way you can choose to host the
397 | 				keylist and sig in, for example, github gists.) ~ML -->
398 | 				<!-- RESOLVED; I added language that specified ascii-armored.
399 | 				For all the reasons you specify, I think this is the best
400 | 				option. ~MM -->
401 | 			</section>
402 | 		</section>
403 | 		<section anchor="inpractice" title="In Practice">
404 | 			<t>
405 | 				GPG Sync, an open source program created by one of the authors,
406 | 				implements this experimental standard. GPG Sync is used by First
407 | 				Look Media and the Freedom of the Press Foundation to keep
408 | 				OpenPGP keys in sync across their organizations, as well as to
409 | 				publish their employee's OpenPGP keys to the world. These
410 | 				organizations collectively employ more than 200 people and have
411 | 				used the system described in this document successfully for
412 | 				multiple years.
413 | 			</t>
414 | 			<t>
415 | 				GPG Sync's existing code can be found at
416 | 				&lt;https://github.com/firstlookmedia/gpgsync&gt;
417 | 			</t>
418 | 			<t>
419 | 				First Look Media's keylist file can be found at
420 | 				&lt;https://github.com/firstlookmedia/gpgsync-firstlook-fingerprints&gt;
421 | 			</t>
422 | 			<!-- TODO: clunky. We could clean this. ~MM -->
423 | 		</section>
424 | 		<section anchor="securityconsiderations" title="Security Considerations">
425 | 			<section anchor="securitybenefits" title="Security Benefits">
426 | 				<t>
427 | 					The keylist subscription functionality defined in this
428 | 					document provide a number of security benefits, including:
429 | 				</t>
430 | 				<t>
431 | 					<list style="symbols">
432 | 						<t>
433 | 							The ability for new keys to be quickly distributed
434 | 							across an organization.
435 | 						</t>
436 | 						<t>
437 | 							It removes the complexity of key distribution from
438 | 							end users, allowing them to focus on the content of
439 | 							their communications rather than on key management.
440 | 						</t>
441 | 						<t>
442 | 							The ability for an organization to prevent the
443 | 							spread of falsely attributed keys by centralizing
444 | 							the public key discovery process within their
445 | 							organization.
446 | 						</t>
447 | 						<!-- TODO: others? ~MM -->
448 | 					</list>
449 | 				</t>
450 | 			</section>
451 | 			<section anchor="securitydrawbacks" title="Security Drawbacks">
452 | 				<t>
453 | 					There is a situation in which keylist subscriptions could
454 | 					pose a potential security threat. If the both the authority
455 | 					key and the keylist distribution system were to be
456 | 					compromised, it would be possible for an attacker to
457 | 					distribute false keys. We believe, however, that the
458 | 					security benefits of this system strongly outweigh the
459 | 					drawbacks.
460 | 				</t>
461 | 			</section>
462 | 			<!-- TODO, see https://tools.ietf.org/html/bcp72 ~MM -->
463 | 		</section>
464 | 		<section anchor="ianaconsiderations" title="IANA Considerations">
465 | 			<t>
466 | 				This document has no actions for IANA.
467 | 			</t>
468 | 		</section>
469 | 	</middle>
470 | 	<back>
471 | 		<references title="Normative References">
472 | 			<?rfc include="reference.RFC.4880.xml"?>
473 | 			<?rfc include="reference.RFC.3986.xml"?>
474 | 			<?rfc include="reference.RFC.2119.xml"?>
475 | 			<?rfc include="reference.RFC.3629.xml"?>
476 | 			<?rfc include="reference.RFC.2818.xml"?>
477 | 		</references>
478 | 		<!--
479 | 		<references title="Informative References"> </references>
480 | 		-->
481 | 	</back>
482 | </rfc>
483 | 


--------------------------------------------------------------------------------
/submissions/draft-mccain-keylist-02.xml:
--------------------------------------------------------------------------------
  1 | <?xml version="1.0"?>
  2 | <?rfc toc="yes"?>
  3 | <?rfc symrefs="yes"?>
  4 | <?rfc sortrefs="yes"?>
  5 | <?rfc compact="yes"?>
  6 | <?rfc subcompact="no"?>
  7 | <!DOCTYPE rfc SYSTEM "rfc2629.dtd">
  8 | <rfc ipr="trust200902" docName="draft-mccain-keylist-02" category="exp">
  9 | 	<!-- TODO: We should verify that 'trust200902' is the intellectual property
 10 | 	designation we want. ~MM -->
 11 | 	<!-- TODO: figure out which category this goes in. ~MM -->
 12 | 	<front>
 13 | 		<!-- Working title. We'll want something that more accurately frames the
 14 | 		system before we submit. It never also hurts to have a more catchy
 15 | 		title... -->
 16 | 		<title abbrev="OpenPGP Keylist Subscriptions">
 17 | 			Distributing OpenPGP Keys with Signed Keylist Subscriptions
 18 | 		</title>
 19 | 		<author initials="M.M." surname="McCain" fullname="R. Miles McCain">
 20 | 			<organization abbrev="FLM">
 21 | 				First Look Media
 22 | 			</organization>
 23 | 			<address>
 24 | 				<email>
 25 | 					ietf@sendmiles.email
 26 | 				</email>
 27 | 				<uri>
 28 | 					https://rmrm.io
 29 | 				</uri>
 30 | 			</address>
 31 | 		</author>
 32 | 		<author initials="M.L." surname="Lee" fullname="Micah Lee">
 33 | 			<organization abbrev="TI">
 34 | 				The Intercept
 35 | 			</organization>
 36 | 			<address>
 37 | 				<email>
 38 | 					micah.lee@theintercept.com
 39 | 				</email>
 40 | 				<uri>
 41 | 					https://micahflee.com/
 42 | 				</uri>
 43 | 			</address>
 44 | 		</author>
 45 | 		<author initials="N.D.W." surname="Welch" fullname="Nat Welch">
 46 | 			<organization abbrev="FLM">
 47 | 				First Look Media
 48 | 			</organization>
 49 | 			<address>
 50 | 				<email>
 51 | 					nat.welch@firstlook.media
 52 | 				</email>
 53 | 				<uri>
 54 | 					https://natwelch.com
 55 | 				</uri>
 56 | 			</address>
 57 | 		</author>
 58 | 		<date month="October" year="2018" day="13" />
 59 | 		<area>
 60 | 			Security
 61 | 		</area>
 62 | 		<keyword>
 63 | 			OpenPGP
 64 | 		</keyword>
 65 | 		<keyword>
 66 | 			GPGSync
 67 | 		</keyword>
 68 | 		<keyword>
 69 | 			GPG
 70 | 		</keyword>
 71 | 		<keyword>
 72 | 			Keylist
 73 | 		</keyword>
 74 | 		<abstract>
 75 | 			<t>
 76 | 				This document specifies a system by which an OpenPGP client may
 77 | 				subscribe to an organization's keylist to keep its internal
 78 | 				keystore up-to-date. Ensuring that all members of an
 79 | 				organization have their colleagues' most recent PGP public keys
 80 | 				is critical to maintaining operational security. Without the
 81 | 				most recent keys and a source of trust for those keys (as this
 82 | 				document specifies), users must manually update and sign each
 83 | 				others keys -- a system that is untenable in larger
 84 | 				organizations. This document proposes a experimental format for
 85 | 				the keylist file as well as requirements for clients who wish to
 86 | 				implement this experimental keylist subscription functionality.
 87 | 			</t>
 88 | 			<!-- We'll want to tighten this abstract up a bit... ~MM -->
 89 | 			<!-- ^ I did what I could. ~MM -->
 90 | 		</abstract>
 91 | 	</front>
 92 | 	<middle>
 93 | 		<section anchor="intro" title="Introduction">
 94 | 			<t>
 95 | 				This document specifies a system by which clients may subscribe
 96 | 				to cryptographically signed keylists. This system allows for
 97 | 				seamless key rotation across entire organizations and enhances
 98 | 				operational security. To enable cross-client compatibility, this
 99 | 				document provides a experimental format for the keylist, its
100 | 				cryptographic verification, and the method by which it is
101 | 				retreived by the client. The user interface by which a client
102 | 				provides this functionality to the user is out of scope, as is
103 | 				the process by which the client retrieves public keys. Other
104 | 				non-security-related implementation details are also out of
105 | 				scope.
106 | 			</t>
107 | 			<section anchor="notation" title="Requirements Notation">
108 | 				<t>
109 | 					The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
110 | 					"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
111 | 					and "OPTIONAL" in this document are to be interpreted as
112 | 					described in
113 | 					<xref target="RFC2119" />
114 | 					.
115 | 				</t>
116 | 			</section>
117 | 			<section anchor="terminology" title="Terminology">
118 | 				<t>
119 | 					This document uses the terms "OpenPGP", "public key",
120 | 					"private key", "signature", and "fingerprint" as defined by
121 | 					OpenPGP Message Format
122 | 					<xref target="RFC4880" />
123 | 					.
124 | 				</t>
125 | 				<!-- TODO: add unicode definitions. ~MM -->
126 | 				<!-- TODO: verify that all the previous terms are actually
127 | 				defined in RFC4880. ~MM -->
128 | 				<!-- TODO: does 'URI' and 'Internet' need a citation? Probably
129 | 				not, but we should check. ~MM -->
130 | 				<t>
131 | 					The term "keylist" is defined as a list of OpenPGP public
132 | 					key fingerprints and accessible via a URI. The exact format
133 | 					of this data is specified in
134 | 					<xref target="formats" />
135 | 					.
136 | 				</t>
137 | 				<!-- TODO: I avoid using the word 'file' here as it has a
138 | 				nuanced meaning and really we're just talking about data
139 | 				accessible via a URI. Is there a term other than 'data' that is
140 | 				appropriate here? ~MM -->
141 | 				<!-- I think this is fine. ~NDW -->
142 | 				<t>
143 | 					An "authority key" is defined as the OpenPGP secret key used
144 | 					to sign a particular keylist. Every keylist has a
145 | 					corresponding authority key, and every authority key has at
146 | 					least one corresponding keylist. A single authority key
147 | 					SHOULD NOT be used to sign multiple keylists.
148 | 				</t>
149 | 				<!-- I'm not opposed to it, but why shouldn't the same authority
150 | 				key be used to sign multiple keylists? I think it'd be confusing
151 | 				in the UI in GPG Sync if you do this, because they keylist is
152 | 				displayed by the authority key's UID. But from a security
153 | 				standpoint, it should be probably be just as secure. ~ML -->
154 | 				<!-- I removed the reference to security. One potential
155 | 				consideration, though, is that this sentence is less about the
156 | 				spec and more about the end user. Perhaps we should just remove
157 | 				the reference all together because it doesn't fit into the
158 | 				implementation but rather the end user's habits? Could be a
159 | 				point of criticism. ~MM -->
160 | 				<t>
161 | 					To be "subscribed" to a keylist means that a program will
162 | 					retreive that keylist on a regular interval. After
163 | 					retrieval, that program will perform an update to an
164 | 					internal OpenPGP keystore.
165 | 				</t>
166 | 				<!-- TODO: This needs to be cleaned/tightened. ~MM -->
167 | 				<t>
168 | 					A "client" is a program that allows the user to subscribe to
169 | 					keylists. A client may be an OpenPGP client itself or a
170 | 					separate program that interfaces with an OpenPGP client to
171 | 					update its keystore.
172 | 				</t>
173 | 			</section>
174 | 			<section anchor="note-to-readers" title="Note to Readers">
175 | 				<t>RFC Editor: please remove this section prior to
176 | 				publication.</t>
177 | 				<t>Development of this Internet draft takes place on GitHub at
178 | 				<eref
179 | 				target="https://github.com/firstlookmedia/keylist-rfc">Keylist-RFC</eref>.
180 | 				</t>
181 | 				<t>A mailing list is available for discussion at <eref
182 | 				target="https://www.freelists.org/list/keylists">Keylists
183 | 				mailing list</eref>.</t>
184 | 			</section>
185 | 		</section>
186 | 		<section anchor="functions" title="Functions and Procedures">
187 | 			<t>
188 | 				As new keys are created and other keys are revoked, it is
189 | 				critical that all members of an organization have the most
190 | 				recent set of keys available on their computers. Keylists enable
191 | 				organizations to publish a directory of OpenPGP keys that
192 | 				clients can use to keep their internal keystores up-to-date.
193 | 			</t>
194 | 			<section anchor="keylist-subscribe" title="Subscribing to Keylists">
195 | 				<t>
196 | 					A single client may subscribe to any number of keylists.
197 | 					When a client first subscribes to a keylist, it SHOULD
198 | 					update or import every key present in the keylist into its
199 | 					local keystore. Keylist subscriptions SHOULD be persistent
200 | 					--that is, they should be permanently stored by the client
201 | 					to enable future automatic updates.
202 | 				</t>
203 | 				<t>
204 | 					To subscribe to a keylist, the client must be aware of the
205 | 					keylist URI (see <xref target="RFC3986" />), and the 
206 | 					fingerprint of the authority key used to sign the
207 | 					keylist. The protocol used to retrieve the keylist and its
208 | 					signature SHOULD be HTTPS (see <xref target="RFC2818" />),
209 | 					however other implementation MAY be supported. A client
210 | 					implementing keylist functionality MUST support the
211 | 					retrieval of keylists and signatures over HTTPS. All other
212 | 					protocols are OPTIONAL.
213 | 				</t>
214 | 				<t>
215 | 					A client MUST NOT employ a trust-on-first-use model for
216 | 					determining the fingerprint of the authority key; it must be
217 | 					explicitly provided by the user.
218 | 				</t>
219 | 				<t>
220 | 					The process by which the client stores its keylist
221 | 					subscriptions is out of scope, as is the means by which
222 | 					subscription functionality is exposed to the end-user.
223 | 				</t>
224 | 			</section>
225 | 			<section anchor="keylist-update" title="Periodic Updates">
226 | 				<t>
227 | 					The primary purpose of keylists is to enable periodic
228 | 					updates of OpenPGP clients' internal keystores. We RECOMMEND
229 | 					that clients provide a default refresh interval of less than
230 | 					one day, however we also RECOMMEND that clients allow the
231 | 					user to select this interval. The exact time at which
232 | 					updates are performed is not critical.
233 | 				</t>
234 | 				<t>
235 | 					To perform an update, the client MUST perform the following
236 | 					steps on each keylist to which it is subscribed. The steps
237 | 					SHOULD be performed in the given order.
238 | 				</t>
239 | 				<t>
240 | 					<list style="numbers">
241 | 						<t>
242 | 							Obtain a current copy of the keylist from its URI.
243 | 						</t>
244 | 						<t>
245 | 							Obtain a current copy of the keylist's signature
246 | 							data from its URI, which is included in the keylist data
247 | 							format specified in <xref target="formats" />.
248 | 						</t>
249 | 						<!-- I say 'obtain' rather than retrieve because I want
250 | 						to leave open the possibility of a client checking to
251 | 						see if the hash of the file, for example, has changed,
252 | 						and only re-requesting if it has. 'Obtain' is also very
253 | 						ambiguous, though, so it may be to our advantage to use
254 | 						something more specific or explain this rationale
255 | 						outright. ~MM -->
256 | 						<!-- we should be verifying a checksum, and be explicit
257 | 						about it in this description. ~NDW -->
258 | 						<t>
259 | 							Using the keylist and the keylist's signature,
260 | 							cryptographically verify that the keylist was signed
261 | 							using the authority key. If the signature does not
262 | 							verify, the client MUST abort the update of this
263 | 							keylist and SHOULD alert the user. The client SHOULD
264 | 							NOT abort the update of other keylists to which it
265 | 							is subscribed, unless they too fail signature
266 | 							verification.
267 | 						</t>
268 | 						<t>
269 | 							Validate the format of the keylist according to
270 | 							<xref target="formats" />
271 | 							. If the keylist is in an invalid format, the client
272 | 							MUST abort the update this keylist and SHOULD alert
273 | 							the user.
274 | 						</t>
275 | 						<t>
276 | 							For each fingerprint listed in the keyfile, if a
277 | 							copy of the associated public key is not present in
278 | 							the client's local keystore, retrieve it from the
279 | 							keyserver specified by the keylist (see 
280 | 							<xref target="formats" />) or, if the keylist specifies
281 | 							no keyserver, from any keyserver.
282 | 							If the key is already present and not revoked,
283 | 							refresh it from a keyserver. If it is present and
284 | 							revoked, do nothing.
285 | 						</t>
286 | 						<!-- TODO: Is it overkill to establish some concept of a
287 | 						'linked keystore' as the keystore that the client
288 | 						interacts with and keeps updated? This is a potential
289 | 						ambiguity for machines with multiple keystores. ~MM -->
290 | 						<!-- That could be useful, but I'd leave that up to the
291 | 						client. Maybe add a recommendation that says something
292 | 						around letting users specify which keystore they want to
293 | 						sync to? It seems slightly out of scope as you are
294 | 						saying retrival and update is out of scope. ~NDW -->
295 | 						<!-- TODO: Should anything else be in this list? ~MM -->
296 | 					</list>
297 | 				</t>
298 | 			</section>
299 | 			<section anchor="keylist-crypto" title="Cryptographic Verification of Keylists">
300 | 				<t>
301 | 					To ensure authenticity of a keylist during an update, the
302 | 					client MUST verify that the keylist's data matches its
303 | 					cryptographic signature, and that the public key used to
304 | 					verify the signature matches the authority key fingerprint
305 | 					given by the user.
306 | 				</t>
307 | 				<t>
308 | 					For enhanced security, it is RECOMMENDED that keylist
309 | 					operators sign each public key listed in their keylist with
310 | 					the authority private key. This way, an organization can
311 | 					have an internal trust relationship without requiring
312 | 					members of the organization to certify each other's public
313 | 					keys.
314 | 				</t>
315 | 			</section>
316 | 		</section>
317 | 		<section anchor="formats" title="Data Element Formats">
318 | 			<t>
319 | 				The following are format specifications for the keylist file and
320 | 				its signature file.
321 | 			</t>
322 | 			<section anchor="keylist-format" title="Keylist">
323 | 				<t>
324 | 					The keylist MUST be a valid JavaScript Object Notation
325 | 					(JSON) Data Interchange Format
326 | 					<xref target="RFC8259" /> object with specific keys
327 | 					and values, as defined below. Note that unless otherwise specified,
328 | 					'key' in this section refers to JSON keys--not OpenPGP keys.
329 | 				</t>
330 | 				<t>
331 | 					To encode metadata, the keylist MUST have a "metadata" root key
332 | 					with an object as the value ("metadata object").
333 | 					The metadata object MUST contain a "signature_uri" key whose value
334 | 					is the URI string of the keylist's signature file. All metadata keys 
335 | 					apart from "signature_uri" are OPTIONAL.
336 | 				</t>
337 | 				<t>
338 | 					The metadata object MAY contain a "keyserver" key with the value of the
339 | 					URI string of the keyserver from which the OpenPGP keys in the keylist
340 | 					should be retrieved.
341 | 				</t>
342 | 				<t>
343 | 					The metadata object MAY contain a "comment" key with the
344 | 					value of any string. The metadata object MAY also contain other arbitrary
345 | 					key-value pairs.
346 | 				</t>
347 | 				<!-- TODO: Should we specify in more detail what a keyserver URI
348 | 				is, or even what a keyserver is? More details here:
349 | 				https://github.com/firstlookmedia/keylist-rfc/issues/8#issuecomment-427133308
350 | 				~ML -->
351 | 				<t>
352 | 					The keylist MUST have a "keys" key with an array as the value.
353 | 					This array contains a list of OpenPGP key fingerprints and
354 | 					metadata about them. Each item in the array MUST be an object.
355 | 					Each of these objects MUST have a "fingerprint" key with the
356 | 					value of a string that contains the full 40-character
357 | 					hexadecimal public key fingerprint, as defined in OpenPGP
358 | 					Message Format
359 | 					<xref target="RFC4880" />
360 | 					. Any number of space characters (' ', U+0020) MAY be included
361 | 					at any location in the fingerprint string. These objects MAY 
362 | 					contain "name", "email", and "comment" key-value pairs, as well
363 | 					as any other key-value pairs relevant.
364 | 					<!-- Maybe the edit here was a bit _too_ reductive. Let me know if you
365 | 					think I cut too much. The thinking is really that "name", "email", and
366 | 					"comment" keys are really just optional, so it makes sense to merge them
367 | 					into a single sentence, but I'm also completely open to reverting this
368 | 					change if you prefer the old phrasing! -->
369 | 				</t>
370 | 				<t>
371 | 					The following is an example of a valid keylist.
372 | 				</t>
373 | 				<figure>
374 | 					<artwork>
375 | {
376 |   "metadata": {
377 |     "signature_uri": "https://www.example.com/keylist.json.asc"
378 |     "comment": "This is an example of a keylist file"
379 |   },
380 |   "keys": [
381 |     {
382 |       "fingerprint": "927F419D7EC82C2F149C1BD1403C2657CD994F73",
383 |       "name": "Micah Lee",
384 |       "email": "micah.lee@theintercept.com",
385 |       "comment": "Each key can have a comment"
386 |     },
387 |     {
388 |       "fingerprint": "1326CB162C6921BF085F8459F3C78280DDBF52A1",
389 |       "name": "R. Miles McCain",
390 |       "email": "0@rmrm.io"
391 |     },
392 |     {
393 |       "fingerprint": "E0BE0804CF04A65C1FC64CC4CAD802E066046C02",
394 |       "name": "Nat Welch",
395 |       "email": "nat.welch@firstlook.org"
396 |     }
397 |   ]
398 | }
399 | 					</artwork>
400 | 				</figure>
401 | 			</section>
402 | 			<section anchor="sigfile" title="Signature">
403 | 				<t>
404 | 					The signature file MUST be an ASCII-armored 'detached
405 | 					signature' of the keylist file, as defined in OpenPGP
406 | 					Message Format
407 | 					<xref target="RFC4880" />
408 | 					.
409 | 				</t>
410 | 			</section>
411 | 		</section>
412 | 		<section anchor="inpractice" title="In Practice">
413 | 			<t>
414 | 				GPG Sync, an open source program created by one of the authors,
415 | 				implements this experimental standard. GPG Sync is used by First
416 | 				Look Media and the Freedom of the Press Foundation to keep
417 | 				OpenPGP keys in sync across their organizations, as well as to
418 | 				publish their employee's OpenPGP keys to the world. These
419 | 				organizations collectively employ more than 200 people and have
420 | 				used the system described in this document successfully for
421 | 				multiple years.
422 | 			</t>
423 | 			<t>
424 | 				GPG Sync's existing code can be found at
425 | 				&lt;https://github.com/firstlookmedia/gpgsync&gt;
426 | 			</t>
427 | 			<t>
428 | 				First Look Media's keylist file can be found at
429 | 				&lt;https://github.com/firstlookmedia/gpgsync-firstlook-fingerprints&gt;
430 | 			</t>
431 | 			<!-- TODO: clunky. We could clean this. ~MM -->
432 | 		</section>
433 | 		<section anchor="securityconsiderations" title="Security Considerations">
434 | 			<section anchor="securitybenefits" title="Security Benefits">
435 | 				<t>
436 | 					The keylist subscription functionality defined in this
437 | 					document provide a number of security benefits, including:
438 | 				</t>
439 | 				<t>
440 | 					<list style="symbols">
441 | 						<t>
442 | 							The ability for new keys to be quickly distributed
443 | 							across an organization.
444 | 						</t>
445 | 						<t>
446 | 							It removes the complexity of key distribution from
447 | 							end users, allowing them to focus on the content of
448 | 							their communications rather than on key management.
449 | 						</t>
450 | 						<t>
451 | 							The ability for an organization to prevent the
452 | 							spread of falsely attributed keys by centralizing
453 | 							the public key discovery process within their
454 | 							organization.
455 | 						</t>
456 | 						<!-- TODO: others? ~MM -->
457 | 					</list>
458 | 				</t>
459 | 			</section>
460 | 			<section anchor="securitydrawbacks" title="Security Drawbacks">
461 | 				<t>
462 | 					There is a situation in which keylist subscriptions could
463 | 					pose a potential security threat. If the both the authority
464 | 					key and the keylist distribution system were to be
465 | 					compromised, it would be possible for an attacker to
466 | 					distribute false keys. We believe, however, that the
467 | 					security benefits of this system strongly outweigh the
468 | 					drawbacks.
469 | 				</t>
470 | 			</section>
471 | 			<!-- TODO, see https://tools.ietf.org/html/bcp72 ~MM -->
472 | 		</section>
473 | 		<section anchor="ianaconsiderations" title="IANA Considerations">
474 | 			<t>
475 | 				This document has no actions for IANA.
476 | 			</t>
477 | 		</section>
478 | 	</middle>
479 | 	<back>
480 | 		<references title="Normative References">
481 | 			<?rfc include="reference.RFC.4880.xml"?>
482 | 			<?rfc include="reference.RFC.3986.xml"?>
483 | 			<?rfc include="reference.RFC.2119.xml"?>
484 | 			<?rfc include="reference.RFC.8259.xml"?>
485 | 			<?rfc include="reference.RFC.2818.xml"?>
486 | 		</references>
487 | 		<!--
488 | 		<references title="Informative References"> </references>
489 | 		-->
490 | 	</back>
491 | </rfc>
492 | 


--------------------------------------------------------------------------------
/submissions/draft-mccain-keylist-03.xml:
--------------------------------------------------------------------------------
  1 | <?xml version="1.0"?>
  2 | <?rfc toc="yes"?>
  3 | <?rfc symrefs="yes"?>
  4 | <?rfc sortrefs="yes"?>
  5 | <?rfc compact="yes"?>
  6 | <?rfc subcompact="no"?>
  7 | <!DOCTYPE rfc SYSTEM "rfc2629.dtd">
  8 | <rfc ipr="trust200902" docName="draft-mccain-keylist-03" category="std">
  9 | 	<!-- TODO: We should verify that 'trust200902' is the intellectual property
 10 | 	designation we want. ~MM -->
 11 | 	<!-- TODO: figure out which category this goes in. ~MM -->
 12 | 	<front>
 13 | 		<!-- Working title. We'll want something that more accurately frames the
 14 | 		system before we submit. It never also hurts to have a more catchy
 15 | 		title... -->
 16 | 		<title abbrev="OpenPGP Keylist Subscriptions">
 17 | 			Distributing OpenPGP Keys with Signed Keylist Subscriptions
 18 | 		</title>
 19 | 		<author initials="M.M." surname="McCain" fullname="R. Miles McCain">
 20 | 			<organization abbrev="FLM">
 21 | 				First Look Media
 22 | 			</organization>
 23 | 			<address>
 24 | 				<email>
 25 | 					ietf@sendmiles.email
 26 | 				</email>
 27 | 				<uri>
 28 | 					https://rmrm.io
 29 | 				</uri>
 30 | 			</address>
 31 | 		</author>
 32 | 		<author initials="M.L." surname="Lee" fullname="Micah Lee">
 33 | 			<organization abbrev="TI">
 34 | 				The Intercept
 35 | 			</organization>
 36 | 			<address>
 37 | 				<email>
 38 | 					micah.lee@theintercept.com
 39 | 				</email>
 40 | 				<uri>
 41 | 					https://micahflee.com/
 42 | 				</uri>
 43 | 			</address>
 44 | 		</author>
 45 | 		<author initials="N.D.W." surname="Welch" fullname="Nat Welch">
 46 | 			<organization abbrev="Google">
 47 | 				Google
 48 | 			</organization>
 49 | 			<address>
 50 | 				<email>
 51 | 					nat@natwelch.com
 52 | 				</email>
 53 | 				<uri>
 54 | 					https://natwelch.com
 55 | 				</uri>
 56 | 			</address>
 57 | 		</author>
 58 | 		<date month="February" year="2019" day="12" />
 59 | 		<area>
 60 | 			Security
 61 | 		</area>
 62 | 		<keyword>
 63 | 			OpenPGP
 64 | 		</keyword>
 65 | 		<keyword>
 66 | 			GPGSync
 67 | 		</keyword>
 68 | 		<keyword>
 69 | 			GPG
 70 | 		</keyword>
 71 | 		<keyword>
 72 | 			Keylist
 73 | 		</keyword>
 74 | 		<abstract>
 75 | 			<t>
 76 | 				This document specifies a system by which an OpenPGP client may
 77 | 				subscribe to an organization's keylist to keep its internal
 78 | 				keystore up-to-date. Ensuring that all members of an
 79 | 				organization have their colleagues' most recent PGP public keys
 80 | 				is critical to maintaining operational security. Without the
 81 | 				most recent keys and a source of trust for those keys (as this
 82 | 				document specifies), users must manually update and sign each
 83 | 				others keys -- a system that is untenable in larger
 84 | 				organizations. This document proposes a experimental format for
 85 | 				the keylist file as well as requirements for clients who wish to
 86 | 				implement this experimental keylist subscription functionality.
 87 | 			</t>
 88 | 			<!-- We'll want to tighten this abstract up a bit... ~MM -->
 89 | 			<!-- ^ I did what I could. ~MM -->
 90 | 		</abstract>
 91 | 	</front>
 92 | 	<middle>
 93 | 		<section anchor="intro" title="Introduction">
 94 | 			<t>
 95 | 				This document specifies a system by which clients may subscribe
 96 | 				to cryptographically signed keylists. This system allows for
 97 | 				seamless key rotation across entire organizations and enhances
 98 | 				operational security. To enable cross-client compatibility, this
 99 | 				document provides a experimental format for the keylist, its
100 | 				cryptographic verification, and the method by which it is
101 | 				retreived by the client. The user interface by which a client
102 | 				provides this functionality to the user is out of scope, as is
103 | 				the process by which the client retrieves public keys. Other
104 | 				non-security-related implementation details are also out of
105 | 				scope.
106 | 			</t>
107 | 			<section anchor="notation" title="Requirements Notation">
108 | 				<t>
109 | 					The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
110 | 					"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
111 | 					and "OPTIONAL" in this document are to be interpreted as
112 | 					described in
113 | 					<xref target="RFC2119" />
114 | 					.
115 | 				</t>
116 | 			</section>
117 | 			<section anchor="terminology" title="Terminology">
118 | 				<t>
119 | 					This document uses the terms "OpenPGP", "public key",
120 | 					"private key", "signature", and "fingerprint" as defined by
121 | 					OpenPGP Message Format
122 | 					<xref target="RFC4880" />
123 | 					.
124 | 				</t>
125 | 				<!-- TODO: add unicode definitions. ~MM -->
126 | 				<!-- TODO: verify that all the previous terms are actually
127 | 				defined in RFC4880. ~MM -->
128 | 				<!-- TODO: does 'URI' and 'Internet' need a citation? Probably
129 | 				not, but we should check. ~MM -->
130 | 				<t>
131 | 					The term "keylist" is defined as a list of OpenPGP public
132 | 					key fingerprints and accessible via a URI. The exact format
133 | 					of this data is specified in
134 | 					<xref target="formats" />
135 | 					.
136 | 				</t>
137 | 				<!-- TODO: I avoid using the word 'file' here as it has a
138 | 				nuanced meaning and really we're just talking about data
139 | 				accessible via a URI. Is there a term other than 'data' that is
140 | 				appropriate here? ~MM -->
141 | 				<!-- I think this is fine. ~NDW -->
142 | 				<t>
143 | 					An "authority key" is defined as the OpenPGP secret key used
144 | 					to sign a particular keylist. Every keylist has a
145 | 					corresponding authority key, and every authority key has at
146 | 					least one corresponding keylist. A single authority key
147 | 					SHOULD NOT be used to sign multiple keylists.
148 | 				</t>
149 | 				<!-- I'm not opposed to it, but why shouldn't the same authority
150 | 				key be used to sign multiple keylists? I think it'd be confusing
151 | 				in the UI in GPG Sync if you do this, because they keylist is
152 | 				displayed by the authority key's UID. But from a security
153 | 				standpoint, it should be probably be just as secure. ~ML -->
154 | 				<!-- I removed the reference to security. One potential
155 | 				consideration, though, is that this sentence is less about the
156 | 				spec and more about the end user. Perhaps we should just remove
157 | 				the reference all together because it doesn't fit into the
158 | 				implementation but rather the end user's habits? Could be a
159 | 				point of criticism. ~MM -->
160 | 				<t>
161 | 					To be "subscribed" to a keylist means that a program will
162 | 					retreive that keylist on a regular interval. After
163 | 					retrieval, that program will perform an update to an
164 | 					internal OpenPGP keystore.
165 | 				</t>
166 | 				<!-- TODO: This needs to be cleaned/tightened. ~MM -->
167 | 				<t>
168 | 					A "client" is a program that allows the user to subscribe to
169 | 					keylists. A client may be an OpenPGP client itself or a
170 | 					separate program that interfaces with an OpenPGP client to
171 | 					update its keystore.
172 | 				</t>
173 | 			</section>
174 | 			<section anchor="note-to-readers" title="Note to Readers">
175 | 				<t>RFC Editor: please remove this section prior to
176 | 				publication.</t>
177 | 				<t>Development of this Internet draft takes place on GitHub at
178 | 				<eref
179 | 				target="https://github.com/firstlookmedia/keylist-rfc">Keylist-RFC</eref>.
180 | 				</t>
181 | 				<t>A mailing list is available for discussion at <eref
182 | 				target="https://www.freelists.org/list/keylists">Keylists
183 | 				mailing list</eref>.</t>
184 | 			</section>
185 | 		</section>
186 | 		<section anchor="functions" title="Functions and Procedures">
187 | 			<t>
188 | 				As new keys are created and other keys are revoked, it is
189 | 				critical that all members of an organization have the most
190 | 				recent set of keys available on their computers. Keylists enable
191 | 				organizations to publish a directory of OpenPGP keys that
192 | 				clients can use to keep their internal keystores up-to-date.
193 | 			</t>
194 | 			<section anchor="keylist-subscribe" title="Subscribing to Keylists">
195 | 				<t>
196 | 					A single client may subscribe to any number of keylists.
197 | 					When a client first subscribes to a keylist, it SHOULD
198 | 					update or import every key present in the keylist into its
199 | 					local keystore. Keylist subscriptions SHOULD be persistent
200 | 					-- that is, they should be permanently stored by the client
201 | 					to enable future automatic updates.
202 | 				</t>
203 | 				<t>
204 | 					To subscribe to a keylist, the client must be aware of the
205 | 					keylist URI (see <xref target="RFC3986" />), and the
206 | 					fingerprint of the authority key used to sign the
207 | 					keylist. The protocol used to retrieve the keylist and its
208 | 					signature SHOULD be HTTPS (see <xref target="RFC2818" />),
209 | 					however other implementation MAY be supported. A client
210 | 					implementing keylist functionality MUST support the
211 | 					retrieval of keylists and signatures over HTTPS. All other
212 | 					protocols are OPTIONAL.
213 | 				</t>
214 | 				<t>
215 | 					A client MUST NOT employ a trust-on-first-use (TOFU) model for
216 | 					determining the fingerprint of the authority key; it must be
217 | 					explicitly provided by the user.
218 | 				</t>
219 | 				<t>
220 | 					The process by which the client stores its keylist
221 | 					subscriptions is out of scope, as is the means by which
222 | 					subscription functionality is exposed to the end-user.
223 | 				</t>
224 | 			</section>
225 | 			<section anchor="keylist-update" title="Automatic Updates">
226 | 				<t>
227 | 					The primary purpose of keylists is to enable periodic
228 | 					updates of OpenPGP clients' internal keystores. We RECOMMEND
229 | 					that clients provide automatic 'background' update functionality;
230 | 					we also regonize that automatic background updates are not possible
231 | 					in every application (specifically cross-platform CLI tools).
232 | 				</t>
233 | 				<t>When automatic background updates are provided, we RECOMMEND
234 | 					that clients provide a default refresh interval of less than
235 | 					one day, however we also RECOMMEND that clients allow the
236 | 					user to select this interval. The exact time at which
237 | 					updates are performed is not critical.
238 | 				</t>
239 | 				<t>
240 | 					To perform an update, the client MUST perform the following
241 | 					steps on each keylist to which it is subscribed. The steps
242 | 					SHOULD be performed in the given order.
243 | 				</t>
244 | 				<t>
245 | 					<list style="numbers">
246 | 						<t>
247 | 							Obtain a current copy of the keylist from its URI.
248 | 						</t>
249 | 						<t>
250 | 							Obtain a current copy of the keylist's signature
251 | 							data from its URI, which is included in the keylist data
252 | 							format specified in <xref target="formats" />.
253 | 						</t>
254 | 						<!-- I say 'obtain' rather than retrieve because I want
255 | 						to leave open the possibility of a client checking to
256 | 						see if the hash of the file, for example, has changed,
257 | 						and only re-requesting if it has. 'Obtain' is also very
258 | 						ambiguous, though, so it may be to our advantage to use
259 | 						something more specific or explain this rationale
260 | 						outright. ~MM -->
261 | 						<!-- we should be verifying a checksum, and be explicit
262 | 						about it in this description. ~NDW -->
263 | 						<t>
264 | 							Using the keylist and the keylist's signature,
265 | 							cryptographically verify that the keylist was signed
266 | 							using the authority key. If the signature does not
267 | 							verify, the client MUST abort the update of this
268 | 							keylist and SHOULD alert the user. The client SHOULD
269 | 							NOT abort the update of other keylists to which it
270 | 							is subscribed, unless they too fail signature
271 | 							verification.
272 | 						</t>
273 | 						<t>
274 | 							Validate the format of the keylist according to
275 | 							<xref target="formats" />
276 | 							. If the keylist is in an invalid format, the client
277 | 							MUST abort the update this keylist and SHOULD alert
278 | 							the user.
279 | 						</t>
280 | 						<t>
281 | 							For each fingerprint listed in the keyfile, if a
282 | 							copy of the associated public key is not present in
283 | 							the client's local keystore, retrieve it from the
284 | 							keyserver specified by the keylist (see
285 | 							<xref target="formats" />) or, if the keylist specifies
286 | 							no keyserver, from any keyserver.
287 | 							If the key is already present and not revoked,
288 | 							refresh it from a keyserver. If it is present and
289 | 							revoked, do nothing.
290 | 						</t>
291 | 						<!-- TODO: Is it overkill to establish some concept of a
292 | 						'linked keystore' as the keystore that the client
293 | 						interacts with and keeps updated? This is a potential
294 | 						ambiguity for machines with multiple keystores. ~MM -->
295 | 						<!-- That could be useful, but I'd leave that up to the
296 | 						client. Maybe add a recommendation that says something
297 | 						around letting users specify which keystore they want to
298 | 						sync to? It seems slightly out of scope as you are
299 | 						saying retrival and update is out of scope. ~NDW -->
300 | 						<!-- TODO: Should anything else be in this list? ~MM -->
301 | 					</list>
302 | 				</t>
303 | 			</section>
304 | 			<section anchor="keylist-crypto" title="Cryptographic Verification of Keylists">
305 | 				<t>
306 | 					To ensure authenticity of a keylist during an update, the
307 | 					client MUST verify that the keylist's data matches its
308 | 					cryptographic signature, and that the public key used to
309 | 					verify the signature matches the authority key fingerprint
310 | 					given by the user.
311 | 				</t>
312 | 				<t>
313 | 					For enhanced security, it is RECOMMENDED that keylist
314 | 					operators sign each public key listed in their keylist with
315 | 					the authority private key. This way, an organization can
316 | 					have an internal trust relationship without requiring
317 | 					members of the organization to certify each other's public
318 | 					keys.
319 | 				</t>
320 | 			</section>
321 | 		</section>
322 | 		<section anchor="formats" title="Data Element Formats">
323 | 			<t>
324 | 				The following are format specifications for the keylist file and
325 | 				its signature file.
326 | 			</t>
327 | 			<section anchor="keylist-format" title="Keylist">
328 | 				<t>
329 | 					The keylist MUST be a valid JavaScript Object Notation
330 | 					(JSON) Data Interchange Format
331 | 					<xref target="RFC8259" /> object with specific keys
332 | 					and values, as defined below. Note that unless otherwise specified,
333 | 					'key' in this section refers to JSON keys -- not OpenPGP keys.
334 | 				</t>
335 | 				<t>
336 | 					To encode metadata, the keylist MUST have a "metadata" root key
337 | 					with an object as the value ("metadata object").
338 | 					The metadata object MUST contain a "signature_uri" key whose value
339 | 					is the URI string of the keylist's signature file. All metadata keys
340 | 					apart from "signature_uri" are OPTIONAL.
341 | 				</t>
342 | 				<t>
343 | 					The metadata object MAY contain a "keyserver" key with the value of the
344 | 					URI string of the keyserver from which the OpenPGP keys in the keylist
345 | 					should be retrieved.
346 | 				</t>
347 | 				<t>
348 | 					The metadata object MAY contain a "comment" key with the
349 | 					value of any string. The metadata object MAY also contain other arbitrary
350 | 					key-value pairs.
351 | 				</t>
352 | 				<!-- TODO: Should we specify in more detail what a keyserver URI
353 | 				is, or even what a keyserver is? More details here:
354 | 				https://github.com/firstlookmedia/keylist-rfc/issues/8#issuecomment-427133308
355 | 				~ML -->
356 | 				<t>
357 | 					The keylist MUST have a "keys" key with an array as the value.
358 | 					This array contains a list of OpenPGP key fingerprints and
359 | 					metadata about them. Each item in the array MUST be an object.
360 | 					Each of these objects MUST have a "fingerprint" key with the
361 | 					value of a string that contains the full 40-character
362 | 					hexadecimal public key fingerprint, as defined in OpenPGP
363 | 					Message Format
364 | 					<xref target="RFC4880" />
365 | 					. Any number of space characters (' ', U+0020) MAY be included
366 | 					at any location in the fingerprint string. These objects MAY
367 | 					contain "name", "email", and "comment" key-value pairs, as well
368 | 					as any other key-value pairs relevant.
369 | 					<!-- Maybe the edit here was a bit _too_ reductive. Let me know if you
370 | 					think I cut too much. The thinking is really that "name", "email", and
371 | 					"comment" keys are really just optional, so it makes sense to merge them
372 | 					into a single sentence, but I'm also completely open to reverting this
373 | 					change if you prefer the old phrasing! -->
374 | 				</t>
375 | 				<t>
376 | 					The following is an example of a valid keylist.
377 | 				</t>
378 | 				<figure>
379 | 					<artwork>
380 | {
381 |   "metadata": {
382 |     "signature_uri": "https://www.example.com/keylist.json.asc",
383 |     "comment": "This is an example of a keylist file"
384 |   },
385 |   "keys": [
386 |     {
387 |       "fingerprint": "927F419D7EC82C2F149C1BD1403C2657CD994F73",
388 |       "name": "Micah Lee",
389 |       "email": "micah.lee@theintercept.com",
390 |       "comment": "Each key can have a comment"
391 |     },
392 |     {
393 |       "fingerprint": "1326CB162C6921BF085F8459F3C78280DDBF52A1",
394 |       "name": "R. Miles McCain",
395 |       "email": "0@rmrm.io"
396 |     },
397 |     {
398 |       "fingerprint": "E0BE0804CF04A65C1FC64CC4CAD802E066046C02",
399 |       "name": "Nat Welch",
400 |       "email": "nat.welch@firstlook.org"
401 |     }
402 |   ]
403 | }
404 | 					</artwork>
405 | 				</figure>
406 | 			</section>
407 | 			<section anchor="sigfile" title="Signature">
408 | 				<t>
409 | 					The signature file MUST be an ASCII-armored 'detached
410 | 					signature' of the keylist file, as defined in OpenPGP
411 | 					Message Format
412 | 					<xref target="RFC4880" />
413 | 					.
414 | 				</t>
415 | 			</section>
416 | 		</section>
417 | 		<section anchor="inpractice" title="In Practice">
418 | 			<t>
419 | 				GPG Sync, an open source program created by one of the authors,
420 | 				implements this experimental standard. GPG Sync is used by First
421 | 				Look Media and the Freedom of the Press Foundation to keep
422 | 				OpenPGP keys in sync across their organizations, as well as to
423 | 				publish their employee's OpenPGP keys to the world. These
424 | 				organizations collectively employ more than 200 people and have
425 | 				used the system described in this document successfully for
426 | 				multiple years.
427 | 			</t>
428 | 			<t>
429 | 				GPG Sync's existing code can be found at
430 | 				&lt;https://github.com/firstlookmedia/gpgsync&gt;
431 | 			</t>
432 | 			<t>
433 | 				First Look Media's keylist file can be found at
434 | 				&lt;https://github.com/firstlookmedia/gpgsync-firstlook-fingerprints&gt;
435 | 			</t>
436 | 			<!-- TODO: clunky. We could clean this. ~MM -->
437 | 		</section>
438 | 		<section anchor="securityconsiderations" title="Security Considerations">
439 | 			<section anchor="securitybenefits" title="Security Benefits">
440 | 				<t>
441 | 					The keylist subscription functionality defined in this
442 | 					document provide a number of security benefits, including:
443 | 				</t>
444 | 				<t>
445 | 					<list style="symbols">
446 | 						<t>
447 | 							The ability for new keys to be quickly distributed
448 | 							across an organization.
449 | 						</t>
450 | 						<t>
451 | 							It removes the complexity of key distribution from
452 | 							end users, allowing them to focus on the content of
453 | 							their communications rather than on key management.
454 | 						</t>
455 | 						<t>
456 | 							The ability for an organization to prevent the
457 | 							spread of falsely attributed keys by centralizing
458 | 							the public key discovery process within their
459 | 							organization.
460 | 						</t>
461 | 						<!-- TODO: others? ~MM -->
462 | 					</list>
463 | 				</t>
464 | 			</section>
465 | 			<section anchor="securitydrawbacks" title="Security Drawbacks">
466 | 				<t>
467 | 					There is a situation in which keylist subscriptions could
468 | 					pose a potential security threat. If the both the authority
469 | 					key and the keylist distribution system were to be
470 | 					compromised, it would be possible for an attacker to
471 | 					distribute any key of their choosing to the subscribers of the
472 | 					keylist. The potential consequences of this attack are limited,
473 | 					however, because the attacker cannot remove or modify the keys
474 | 					already present on subscribers' systems.
475 | 				</t>
476 | 			</section>
477 | 			<!-- TODO, see https://tools.ietf.org/html/bcp72 ~MM -->
478 | 		</section>
479 | 		<section anchor="ianaconsiderations" title="IANA Considerations">
480 | 			<t>
481 | 				This document has no actions for IANA.
482 | 			</t>
483 | 		</section>
484 | 	</middle>
485 | 	<back>
486 | 		<references title="Normative References">
487 | 			<?rfc include="reference.RFC.4880.xml"?>
488 | 			<?rfc include="reference.RFC.3986.xml"?>
489 | 			<?rfc include="reference.RFC.2119.xml"?>
490 | 			<?rfc include="reference.RFC.8259.xml"?>
491 | 			<?rfc include="reference.RFC.2818.xml"?>
492 | 		</references>
493 | 		<!--
494 | 		<references title="Informative References"> </references>
495 | 		-->
496 | 	</back>
497 | </rfc>
498 | 


--------------------------------------------------------------------------------
/submissions/draft-mccain-keylist-04.xml:
--------------------------------------------------------------------------------
  1 | <?xml version="1.0"?>
  2 | <?rfc toc="yes"?>
  3 | <?rfc symrefs="yes"?>
  4 | <?rfc sortrefs="yes"?>
  5 | <?rfc compact="yes"?>
  6 | <?rfc subcompact="no"?>
  7 | <!DOCTYPE rfc SYSTEM "rfc2629.dtd">
  8 | <rfc ipr="trust200902" docName="draft-mccain-keylist-04" category="std">
  9 | 	<!-- TODO: We should verify that 'trust200902' is the intellectual property
 10 | 	designation we want. ~MM -->
 11 | 	<!-- TODO: figure out which category this goes in. ~MM -->
 12 | 	<front>
 13 | 		<!-- Working title. We'll want something that more accurately frames the
 14 | 		system before we submit. It never also hurts to have a more catchy
 15 | 		title... -->
 16 | 		<title abbrev="OpenPGP Keylist Subscriptions">
 17 | 			Distributing OpenPGP Key Fingerprints with Signed Keylist Subscriptions
 18 | 		</title>
 19 | 		<author initials="M.M." surname="McCain" fullname="R. Miles McCain">
 20 | 			<organization abbrev="FLM">
 21 | 				First Look Media
 22 | 			</organization>
 23 | 			<address>
 24 | 				<email>
 25 | 					ietf@sendmiles.email
 26 | 				</email>
 27 | 				<uri>
 28 | 					https://rmrm.io
 29 | 				</uri>
 30 | 			</address>
 31 | 		</author>
 32 | 		<author initials="M.L." surname="Lee" fullname="Micah Lee">
 33 | 			<organization abbrev="TI">
 34 | 				The Intercept
 35 | 			</organization>
 36 | 			<address>
 37 | 				<email>
 38 | 					micah.lee@theintercept.com
 39 | 				</email>
 40 | 				<uri>
 41 | 					https://micahflee.com/
 42 | 				</uri>
 43 | 			</address>
 44 | 		</author>
 45 | 		<author initials="N.D.W." surname="Welch" fullname="Nat Welch">
 46 | 			<organization abbrev="Google">
 47 | 				Google
 48 | 			</organization>
 49 | 			<address>
 50 | 				<email>
 51 | 					nat@natwelch.com
 52 | 				</email>
 53 | 				<uri>
 54 | 					https://natwelch.com
 55 | 				</uri>
 56 | 			</address>
 57 | 		</author>
 58 | 		<date month="March" year="2019" day="6" />
 59 | 		<area>
 60 | 			Security
 61 | 		</area>
 62 | 		<keyword>
 63 | 			OpenPGP
 64 | 		</keyword>
 65 | 		<keyword>
 66 | 			GPGSync
 67 | 		</keyword>
 68 | 		<keyword>
 69 | 			GPG
 70 | 		</keyword>
 71 | 		<keyword>
 72 | 			Keylist
 73 | 		</keyword>
 74 | 		<abstract>
 75 | 			<t>
 76 | 				This document specifies a system by which an OpenPGP client may subscribe
 77 | 				to an organization's public keylist to keep its keystore up-to-date with
 78 | 				correct keys, even in cases where the keys correspond to multiple
 79 | 				(potentially uncontrolled) domains. Ensuring that all members or followers
 80 | 				of an organization have their colleagues' most recent PGP public keys is
 81 | 				critical to maintaining operational security. Without the most recent
 82 | 				keys' fingerprints and a source of trust for those keys (as this document
 83 | 				specifies), users must manually update and sign each others' keys -- a
 84 | 				system that is untenable in larger organizations. This document proposes a
 85 | 				experimental format for the keylist file as well as requirements for
 86 | 				clients who wish to implement this experimental keylist subscription
 87 | 				functionality.
 88 | 			</t>
 89 | 			<!-- We'll want to tighten this abstract up a bit... ~MM -->
 90 | 			<!-- ^ I did what I could. ~MM -->
 91 | 		</abstract>
 92 | 	</front>
 93 | 	<middle>
 94 | 		<section anchor="intro" title="Introduction">
 95 | 			<t>
 96 | 				 This document specifies a system by which clients may subscribe to
 97 | 				 cryptographically signed 'keylists' of public key fingerprints. The public
 98 | 				 keys do not necesssarily all correspond to a single domain. This system
 99 | 				 enhances operational security by allowing seamless key rotation across
100 | 				 entire organizations without centralized public key hosting. To enable
101 | 				 cross-client compatibility, this document provides a experimental format
102 | 				 for the keylist, its cryptographic verification, and the method by which it
103 | 				 is retreived by the client. The user interface by which a client provides
104 | 				 this functionality to the user is out of scope, as is the process by which
105 | 				 the client retrieves public keys. Other non-security-related implementation
106 | 				 details are also out of scope.
107 | 			</t>
108 | 			<section anchor="notation" title="Requirements Notation">
109 | 				<t>
110 | 					The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
111 | 					"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
112 | 					and "OPTIONAL" in this document are to be interpreted as
113 | 					described in
114 | 					<xref target="RFC2119" />
115 | 					.
116 | 				</t>
117 | 			</section>
118 | 			<section anchor="terminology" title="Terminology">
119 | 				<t>
120 | 					This document uses the terms "OpenPGP", "public key",
121 | 					"private key", "signature", and "fingerprint" as defined by
122 | 					OpenPGP Message Format
123 | 					<xref target="RFC4880" />
124 | 					.
125 | 					<!-- TODO: clarify the _type_ of fingerprints we use (ideally V4/SHA-160) -->
126 | 				</t>
127 | 				<!-- TODO: add unicode definitions. ~MM -->
128 | 				<!-- TODO: verify that all the previous terms are actually
129 | 				defined in RFC4880. ~MM -->
130 | 				<!-- TODO: does 'URI' and 'Internet' need a citation? Probably
131 | 				not, but we should check. ~MM -->
132 | 				<t>
133 | 					 The term "keylist" is defined as a list of OpenPGP public key fingerprints
134 | 					 and accessible via a URI. The exact format of this data is specified in
135 | 					 <xref target="formats" />. Keylists SHOULD be treated as public
136 | 					 documents; although a system administrator MAY choose, for example, to
137 | 					 restrict access to a keylist to a specific subnet.
138 | 				</t>
139 | 				<!-- TODO: I avoid using the word 'file' here as it has a
140 | 				nuanced meaning and really we're just talking about data
141 | 				accessible via a URI. Is there a term other than 'data' that is
142 | 				appropriate here? ~MM -->
143 | 				<!-- I think this is fine. ~NDW -->
144 | 				<t>
145 | 					An "authority key" is defined as the OpenPGP secret key used
146 | 					to sign a particular keylist. Every keylist has a
147 | 					corresponding authority key, and every authority key has at
148 | 					least one corresponding keylist. A single authority key
149 | 					SHOULD NOT be used to sign multiple keylists.
150 | 				</t>
151 | 				<!-- I'm not opposed to it, but why shouldn't the same authority
152 | 				key be used to sign multiple keylists? I think it'd be confusing
153 | 				in the UI in GPG Sync if you do this, because they keylist is
154 | 				displayed by the authority key's UID. But from a security
155 | 				standpoint, it should be probably be just as secure. ~ML -->
156 | 				<!-- I removed the reference to security. One potential
157 | 				consideration, though, is that this sentence is less about the
158 | 				spec and more about the end user. Perhaps we should just remove
159 | 				the reference all together because it doesn't fit into the
160 | 				implementation but rather the end user's habits? Could be a
161 | 				point of criticism. ~MM -->
162 | 				<t>
163 | 					To be "subscribed" to a keylist means that a program will
164 | 					retreive that keylist on a regular interval. After
165 | 					retrieval, that program will perform an update to an
166 | 					internal OpenPGP keystore.
167 | 				</t>
168 | 				<!-- TODO: This needs to be cleaned/tightened. ~MM -->
169 | 				<t>
170 | 					A "client" is a program that allows the user to subscribe to
171 | 					keylists. A client may be an OpenPGP client itself or a
172 | 					separate program that interfaces with an OpenPGP client to
173 | 					update its keystore.
174 | 				</t>
175 | 			</section>
176 | 			<section anchor="note-to-readers" title="Note to Readers">
177 | 				<t>RFC Editor: please remove this section prior to
178 | 				publication.</t>
179 | 				<t>Development of this Internet draft takes place on GitHub at
180 | 				<eref
181 | 				target="https://github.com/firstlookmedia/keylist-rfc">firstlookmedia/Keylist-RFC</eref>.
182 | 				</t>
183 | 				<t>We are still considering whether this Draft is better for the Experimental or
184 | 				Informational track.</t>
185 | 			</section>
186 | 		</section>
187 | 		<section anchor="functions" title="Functions and Procedures">
188 | 			<t>
189 | 				As new keys are created and other keys are revoked, it is
190 | 				critical that all members of an organization have the most
191 | 				recent set of keys available on their computers. Keylists enable
192 | 				organizations to publish a directory of OpenPGP keys that
193 | 				clients can use to keep their internal keystores up-to-date.
194 | 			</t>
195 | 			<section anchor="keylist-subscribe" title="Subscribing to Keylists">
196 | 				<t>
197 | 					A single client may subscribe to any number of keylists.
198 | 					When a client first subscribes to a keylist, it SHOULD
199 | 					update or import every key present in the keylist into its
200 | 					local keystore. Keylist subscriptions SHOULD be persistent
201 | 					-- that is, they should be permanently stored by the client
202 | 					to enable future automatic updates.
203 | 				</t>
204 | 				<t>
205 | 					To subscribe to a keylist, the client must be aware of the
206 | 					keylist URI (see <xref target="RFC3986" />), and the
207 | 					fingerprint of the authority key used to sign the
208 | 					keylist. The protocol used to retrieve the keylist and its
209 | 					signature SHOULD be HTTPS (see <xref target="RFC2818" />),
210 | 					however other implementation MAY be supported. A client
211 | 					implementing keylist functionality MUST support the
212 | 					retrieval of keylists and signatures over HTTPS. All other
213 | 					protocols are OPTIONAL.
214 | 				</t>
215 | 				<t>
216 | 					A client MUST NOT employ a trust-on-first-use (TOFU) model for
217 | 					determining the fingerprint of the authority public key; the
218 | 					authority public key fingerprint must be explicitly provided
219 | 					by the user.
220 | 				</t>
221 | 				<t>
222 | 					The process by which the client stores its keylist
223 | 					subscriptions is out of scope, as is the means by which
224 | 					subscription functionality is exposed to the end-user.
225 | 				</t>
226 | 				<t>
227 | 					The client MAY provide the option to perform all its network
228 | 					activity over a SOCKS5 proxy (see <xref target="RFC1928" />).
229 | 				</t>
230 | 			</section>
231 | 			<section anchor="keylist-update" title="Automatic Updates">
232 | 				<t>
233 | 					The primary purpose of keylists is to enable periodic
234 | 					updates of OpenPGP clients' internal keystores. We RECOMMEND
235 | 					that clients provide automatic 'background' update functionality;
236 | 					we also regonize that automatic background updates are not possible
237 | 					in every application (specifically cross-platform CLI tools).
238 | 				</t>
239 | 				<t>When automatic background updates are provided, we RECOMMEND
240 | 					that clients provide a default refresh interval of less than
241 | 					one day, however we also RECOMMEND that clients allow the
242 | 					user to select this interval. The exact time at which
243 | 					updates are performed is not critical.
244 | 				</t>
245 | 				<t>
246 | 					To perform an update, the client MUST perform the following
247 | 					steps on each keylist to which it is subscribed. The steps
248 | 					SHOULD be performed in the given order.
249 | 				</t>
250 | 				<t>
251 | 					<list style="numbers">
252 | 						<t>
253 | 							Obtain a current copy of the keylist from its URI.
254 | 						</t>
255 | 						<t>
256 | 							Obtain a current copy of the keylist's signature
257 | 							data from its URI, which is included in the keylist data
258 | 							format specified in <xref target="formats" />.
259 | 						</t>
260 | 						<!-- I say 'obtain' rather than retrieve because I want
261 | 						to leave open the possibility of a client checking to
262 | 						see if the hash of the file, for example, has changed,
263 | 						and only re-requesting if it has. 'Obtain' is also very
264 | 						ambiguous, though, so it may be to our advantage to use
265 | 						something more specific or explain this rationale
266 | 						outright. ~MM -->
267 | 						<!-- we should be verifying a checksum, and be explicit
268 | 						about it in this description. ~NDW -->
269 | 						<t>
270 | 							Using the keylist and the keylist's signature,
271 | 							cryptographically verify that the keylist was signed
272 | 							using the authority key. If the signature does not
273 | 							verify, the client MUST abort the update of this
274 | 							keylist and SHOULD alert the user. The client SHOULD
275 | 							NOT abort the update of other keylists to which it
276 | 							is subscribed, unless they too fail signature
277 | 							verification.
278 | 						</t>
279 | 						<t>
280 | 							Validate the format of the keylist according to
281 | 							<xref target="formats" />
282 | 							. If the keylist is in an invalid format, the client
283 | 							MUST abort the update this keylist and SHOULD alert
284 | 							the user.
285 | 						</t>
286 | 						<t>
287 | 							For each fingerprint listed in the keyfile, if a
288 | 							copy of the associated public key is not present in
289 | 							the client's local keystore, retrieve it from the
290 | 							keyserver specified by the keylist (see
291 | 							<xref target="formats" />) or, if the keylist specifies
292 | 							no keyserver, from any keyserver.
293 | 							If the key is already present and not revoked,
294 | 							refresh it from a keyserver. If it is present and
295 | 							revoked, do nothing.
296 | 						</t>
297 | 						<!-- TODO: Is it overkill to establish some concept of a
298 | 						'linked keystore' as the keystore that the client
299 | 						interacts with and keeps updated? This is a potential
300 | 						ambiguity for machines with multiple keystores. ~MM -->
301 | 						<!-- That could be useful, but I'd leave that up to the
302 | 						client. Maybe add a recommendation that says something
303 | 						around letting users specify which keystore they want to
304 | 						sync to? It seems slightly out of scope as you are
305 | 						saying retrival and update is out of scope. ~NDW -->
306 | 						<!-- TODO: Should anything else be in this list? ~MM -->
307 | 					</list>
308 | 				</t>
309 | 			</section>
310 | 			<section anchor="keylist-crypto" title="Cryptographic Verification of Keylists">
311 | 				<t>
312 | 					To ensure authenticity of a keylist during an update, the
313 | 					client MUST verify that the keylist's data matches its
314 | 					cryptographic signature, and that the public key used to
315 | 					verify the signature matches the authority key fingerprint
316 | 					given by the user.
317 | 				</t>
318 | 				<t>
319 | 					For enhanced security, it is RECOMMENDED that keylist
320 | 					operators sign each public key listed in their keylist with
321 | 					the authority private key. This way, an organization can
322 | 					have an internal trust relationship without requiring
323 | 					members of the organization to certify each other's public
324 | 					keys.
325 | 				</t>
326 | 			</section>
327 | 		</section>
328 | 		<section anchor="formats" title="Data Element Formats">
329 | 			<t>
330 | 				The following are format specifications for the keylist file and
331 | 				its signature file.
332 | 			</t>
333 | 			<section anchor="keylist-format" title="Keylist">
334 | 				<t>
335 | 					The keylist MUST be a valid JavaScript Object Notation
336 | 					(JSON) Data Interchange Format
337 | 					<xref target="RFC8259" /> object with specific keys
338 | 					and values, as defined below. Note that unless otherwise specified,
339 | 					'key' in this section refers to JSON keys -- not OpenPGP keys.
340 | 				</t>
341 | 				<t>
342 | 					To encode metadata, the keylist MUST have a "metadata" root key
343 | 					with an object as the value ("metadata object").
344 | 					The metadata object MUST contain a "signature_uri" key whose value
345 | 					is the URI string of the keylist's signature file. All metadata keys
346 | 					apart from "signature_uri" are OPTIONAL.
347 | 				</t>
348 | 				<t>
349 | 					The metadata object MAY contain a "keyserver" key with the value of the
350 | 					URI string of the keyserver from which the OpenPGP keys in the keylist
351 | 					should be retrieved.
352 | 				</t>
353 | 				<t>
354 | 					The metadata object MAY contain a "comment" key with the
355 | 					value of any string. The metadata object MAY also contain other arbitrary
356 | 					key-value pairs.
357 | 				</t>
358 | 				<!-- TODO: Should we specify in more detail what a keyserver URI
359 | 				is, or even what a keyserver is? More details here:
360 | 				https://github.com/firstlookmedia/keylist-rfc/issues/8#issuecomment-427133308
361 | 				~ML -->
362 | 				<t>
363 | 					The keylist MUST have a "keys" key with an array as the value.
364 | 					This array contains a list of OpenPGP key fingerprints and
365 | 					metadata about them. Each item in the array MUST be an object.
366 | 					Each of these objects MUST have a "fingerprint" key with the
367 | 					value of a string that contains the full 40-character
368 | 					hexadecimal public key fingerprint, as defined in OpenPGP
369 | 					Message Format
370 | 					<xref target="RFC4880" />
371 | 					. Any number of space characters (' ', U+0020) MAY be included
372 | 					at any location in the fingerprint string. These objects MAY
373 | 					contain "name", "email", and "comment" key-value pairs, as well
374 | 					as any other key-value pairs relevant.
375 | 					<!-- Maybe the edit here was a bit _too_ reductive. Let me know if you
376 | 					think I cut too much. The thinking is really that "name", "email", and
377 | 					"comment" keys are really just optional, so it makes sense to merge them
378 | 					into a single sentence, but I'm also completely open to reverting this
379 | 					change if you prefer the old phrasing! -->
380 | 				</t>
381 | 				<t>
382 | 					The following is an example of a valid keylist.
383 | 				</t>
384 | 				<figure>
385 | 					<artwork>
386 | {
387 |   "metadata": {
388 |     "signature_uri": "https://www.example.com/keylist.json.asc",
389 |     "comment": "This is an example of a keylist file"
390 |   },
391 |   "keys": [
392 |     {
393 |       "fingerprint": "927F419D7EC82C2F149C1BD1403C2657CD994F73",
394 |       "name": "Micah Lee",
395 |       "email": "micah.lee@theintercept.com",
396 |       "comment": "Each key can have a comment"
397 |     },
398 |     {
399 |       "fingerprint": "1326CB162C6921BF085F8459F3C78280DDBF52A1",
400 |       "name": "R. Miles McCain",
401 |       "email": "0@rmrm.io"
402 |     },
403 |     {
404 |       "fingerprint": "E0BE0804CF04A65C1FC64CC4CAD802E066046C02",
405 |       "name": "Nat Welch",
406 |       "email": "nat.welch@firstlook.org"
407 |     }
408 |   ]
409 | }
410 | 					</artwork>
411 | 				</figure>
412 | 			</section>
413 | 			<section anchor="sigfile" title="Signature">
414 | 				<t>
415 | 					The signature file MUST be an ASCII-armored 'detached
416 | 					signature' of the keylist file, as defined in OpenPGP
417 | 					Message Format
418 | 					<xref target="RFC4880" />
419 | 					.
420 | 				</t>
421 | 			</section>
422 | 			<section anchor="wellknown" title="Well-Known URL">
423 | 				<t>
424 | 					Keylists SHOULD NOT be well-known resources <xref target="RFC4880" />.
425 | 					To subscribe to a keylist, the client must be aware not only of the keylist's
426 | 					location, but also of the fingerprint of the authority public key used to sign the keylist.
427 | 					Furthermore, because keylists can reference public keys from several different domains,
428 | 					the host of the well-known location for a keylist may not always be clear.
429 | 				</t>
430 | 			</section>
431 | 		</section>
432 | 		<section anchor="implementation" title="Implementation Status">
433 | 			<t>
434 | 				GPG Sync, an open source program created by one of the authors,
435 | 				implements this experimental standard. GPG Sync is used by First
436 | 				Look Media and the Freedom of the Press Foundation to keep
437 | 				OpenPGP keys in sync across their organizations, as well as to
438 | 				publish their employee's OpenPGP keys to the world. These
439 | 				organizations collectively employ more than 200 people and have
440 | 				used the system described in this document successfully for
441 | 				multiple years.
442 | 			</t>
443 | 			<t>
444 | 				GPG Sync's existing code can be found at
445 | 				&lt;https://github.com/firstlookmedia/gpgsync&gt;
446 | 			</t>
447 | 			<t>
448 | 				First Look Media's keylist file can be found at
449 | 				&lt;https://github.com/firstlookmedia/gpgsync-firstlook-fingerprints&gt;
450 | 			</t>
451 | 			<!-- TODO: clunky. We could clean this. ~MM -->
452 | 		</section>
453 | 		<section anchor="securitybenefits" title="Security Benefits">
454 | 			<t>
455 | 				The keylist subscription functionality defined in this
456 | 				document provides a number of security benefits, including:
457 | 			</t>
458 | 			<t>
459 | 				<list style="symbols">
460 | 					<t>
461 | 						The ability for new keys to be quickly distributed
462 | 						across an organization.
463 | 					</t>
464 | 					<t>
465 | 						Removing the complexity of key distribution from
466 | 						end users, allowing them to focus on the content of
467 | 						their communications rather than on key management.
468 | 					</t>
469 | 					<t>
470 | 						The ability for an organization to prevent the
471 | 						spread of falsely attributed keys by centralizing
472 | 						the public key discovery process within their
473 | 						organization without centralized public key hosting.
474 | 					</t>
475 | 					<!-- TODO: others? ~MM -->
476 | 				</list>
477 | 			</t>
478 | 		</section>
479 | 		<section anchor="comparison" title="Relation to Other Technologies">
480 | 			<section anchor="wkd" title="Web Key Directories">
481 | 				<t>
482 | 					Unlike Web Key Directories, keylists are not domain specific. A keylist
483 | 					might contain public key fingerprints for email addresses across several
484 | 					different domains. Moreover, keylists only provide references to public
485 | 					keys by way of fingerprints; Web Key Directories provide the public keys
486 | 					themselves.
487 | 				</t>
488 | 			</section>
489 | 			<section anchor="dns" title="OPENPGPKEY DNS Records">
490 | 				<t>
491 | 					 A keylist MAY reference public keys corresponding to email addresses
492 | 					 across several different domains. Because managing OPENPGPKEY DNS Records
493 | 					 <xref target="RFC7929" /> for a particular domain requires control of that
494 | 					 domain, the OPENPGPKEY DNS Record system is not suitable for cases in
495 | 					 which keys are strewn about several different domains, including ones
496 | 					 outside of the control of an organization's system adminitrators.
497 | 				</t>
498 | 			</section>
499 | 			<!-- We'll want to clean this up, but the messaging we'd like to convey is there. -->
500 | 		</section>
501 | 		<section anchor="securityconsiderations" title="Security Considerations">
502 | 				<t>
503 | 					There is a situation in which keylist subscriptions could
504 | 					pose a potential security threat. If both the authority
505 | 					key and the keylist distribution system were to be
506 | 					compromised, it would be possible for an attacker to
507 | 					distribute any key of their choosing to the subscribers of the
508 | 					keylist. The potential consequences of this attack are limited,
509 | 					however, because the attacker cannot remove or modify the keys
510 | 					already present on subscribers' systems.
511 | 				</t>
512 | 				<t>
513 | 					Some organizations may wish to keep their keylists private. While
514 | 					this may be achievable by serving keylists at URIs only accessible from
515 | 					specific subnets, keylists are designed to be public
516 | 					documents. As such, clients may leak the contents of keylists to
517 | 					keyservers -- this specification ensures to the best of its ability
518 | 					the integrity of keylists, but not the privacy of keylists.
519 | 				</t>
520 | 			<!-- TODO, see https://tools.ietf.org/html/bcp72 ~MM -->
521 | 		</section>
522 | 		<section anchor="ianaconsiderations" title="IANA Considerations">
523 | 			<t>
524 | 				This document has no actions for IANA.
525 | 			</t>
526 | 		</section>
527 | 	</middle>
528 | 	<back>
529 | 		<references title="Normative References">
530 | 			<?rfc include="reference.RFC.7929.xml"?>
531 | 			<?rfc include="reference.RFC.4880.xml"?>
532 | 			<?rfc include="reference.RFC.3986.xml"?>
533 | 			<?rfc include="reference.RFC.2119.xml"?>
534 | 			<?rfc include="reference.RFC.8259.xml"?>
535 | 			<?rfc include="reference.RFC.2818.xml"?>
536 | 			<?rfc include="reference.RFC.1928.xml"?>
537 | 		</references>
538 | 		<!--
539 | 		<references title="Informative References"> </references>
540 | 		-->
541 | 	</back>
542 | </rfc>
543 | 


--------------------------------------------------------------------------------
/submissions/draft-mccain-keylist-05.xml:
--------------------------------------------------------------------------------
  1 | <?xml version="1.0"?>
  2 | <?rfc toc="yes"?>
  3 | <?rfc symrefs="yes"?>
  4 | <?rfc sortrefs="yes"?>
  5 | <?rfc compact="yes"?>
  6 | <?rfc subcompact="no"?>
  7 | <!DOCTYPE rfc SYSTEM "rfc2629.dtd">
  8 | <rfc ipr="trust200902" docName="draft-mccain-keylist-05" category="std">
  9 | 	<!-- TODO: We should verify that 'trust200902' is the intellectual property
 10 | 	designation we want. ~MM -->
 11 | 	<!-- TODO: figure out which category this goes in. ~MM -->
 12 | 	<front>
 13 | 		<!-- Working title. We'll want something that more accurately frames the
 14 | 		system before we submit. It never also hurts to have a more catchy
 15 | 		title... -->
 16 | 		<title abbrev="OpenPGP Keylist Subscriptions">
 17 | 			Distributing OpenPGP Key Fingerprints with Signed Keylist Subscriptions
 18 | 		</title>
 19 | 		<author initials="M.M." surname="McCain" fullname="R. Miles McCain">
 20 | 			<organization abbrev="FLM">
 21 | 				First Look Media
 22 | 			</organization>
 23 | 			<address>
 24 | 				<email>
 25 | 					ietf@sendmiles.email
 26 | 				</email>
 27 | 				<uri>
 28 | 					https://rmrm.io
 29 | 				</uri>
 30 | 			</address>
 31 | 		</author>
 32 | 		<author initials="M.L." surname="Lee" fullname="Micah Lee">
 33 | 			<organization abbrev="TI">
 34 | 				The Intercept
 35 | 			</organization>
 36 | 			<address>
 37 | 				<email>
 38 | 					micah.lee@theintercept.com
 39 | 				</email>
 40 | 				<uri>
 41 | 					https://micahflee.com/
 42 | 				</uri>
 43 | 			</address>
 44 | 		</author>
 45 | 		<author initials="N.D.W." surname="Welch" fullname="Nat Welch">
 46 | 			<organization abbrev="Google">
 47 | 				Google
 48 | 			</organization>
 49 | 			<address>
 50 | 				<email>
 51 | 					nat@natwelch.com
 52 | 				</email>
 53 | 				<uri>
 54 | 					https://natwelch.com
 55 | 				</uri>
 56 | 			</address>
 57 | 		</author>
 58 | 		<date month="September" year="2019" day="2" />
 59 | 		<area>
 60 | 			Security
 61 | 		</area>
 62 | 		<keyword>
 63 | 			OpenPGP
 64 | 		</keyword>
 65 | 		<keyword>
 66 | 			GPGSync
 67 | 		</keyword>
 68 | 		<keyword>
 69 | 			GPG
 70 | 		</keyword>
 71 | 		<keyword>
 72 | 			Keylist
 73 | 		</keyword>
 74 | 		<abstract>
 75 | 			<t>
 76 | 				This document specifies a system by which an OpenPGP client may subscribe
 77 | 				to an organization's public keylist to keep its keystore up-to-date with
 78 | 				correct keys from the correct keyserver(s), even in cases where the keys correspond to multiple
 79 | 				(potentially uncontrolled) domains. Ensuring that all members or followers
 80 | 				of an organization have their colleagues' most recent PGP public keys is
 81 | 				critical to maintaining operational security. Without the most recent
 82 | 				keys' fingerprints and a source of trust for those keys (as this document
 83 | 				specifies), users must manually update and sign each others' keys -- a
 84 | 				system that is untenable in larger organizations. This document proposes a
 85 | 				experimental format for the keylist file as well as requirements for
 86 | 				clients who wish to implement this experimental keylist subscription
 87 | 				functionality.
 88 | 			</t>
 89 | 			<!-- We'll want to tighten this abstract up a bit... ~MM -->
 90 | 			<!-- ^ I did what I could. ~MM -->
 91 | 		</abstract>
 92 | 	</front>
 93 | 	<middle>
 94 | 		<section anchor="intro" title="Introduction">
 95 | 			<t>
 96 | 				 This document specifies a system by which clients may subscribe to
 97 | 				 cryptographically signed 'keylists' of public key fingerprints. The public
 98 | 				 keys do not necesssarily all correspond to a single domain. This system
 99 | 				 enhances operational security by allowing seamless key rotation across
100 | 				 entire organizations without centralized public key hosting. To enable
101 | 				 cross-client compatibility, this document provides a experimental format
102 | 				 for the keylist, its cryptographic verification, and the method by which it
103 | 				 is retreived by the client. The user interface by which a client provides
104 | 				 this functionality to the user is out of scope, as is the process by which
105 | 				 the client retrieves public keys. Other non-security-related implementation
106 | 				 details are also out of scope.
107 | 			</t>
108 | 			<section anchor="notation" title="Requirements Notation">
109 | 				<t>
110 | 					The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
111 | 					"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
112 | 					and "OPTIONAL" in this document are to be interpreted as
113 | 					described in
114 | 					<xref target="RFC2119" />
115 | 					.
116 | 				</t>
117 | 			</section>
118 | 			<section anchor="terminology" title="Terminology">
119 | 				<t>
120 | 					This document uses the terms "OpenPGP", "public key",
121 | 					"private key", "signature", and "fingerprint" as defined by
122 | 					OpenPGP Message Format
123 | 					<xref target="RFC4880" />
124 | 					(the fingerprint type SHOULD be V4).
125 | 					<!-- TODO: clarify the _type_ of fingerprints we use (ideally V4/SHA-160) -->
126 | 				</t>
127 | 				<!-- TODO: add unicode definitions. ~MM -->
128 | 				<!-- TODO: verify that all the previous terms are actually
129 | 				defined in RFC4880. ~MM -->
130 | 				<!-- TODO: does 'URI' and 'Internet' need a citation? Probably
131 | 				not, but we should check. ~MM -->
132 | 				<t>
133 | 					 The term "keylist" is defined as a list of OpenPGP public key fingerprints
134 | 					 accessible via a URI in the format specified in
135 | 					 <xref target="formats" />. Keylists SHOULD be treated as public
136 | 					 documents, however a system administrator MAY choose, for example, to
137 | 					 restrict access to a keylist to a specific subnet or private network.
138 | 				</t>
139 | 				<!-- TODO: I avoid using the word 'file' here as it has a
140 | 				nuanced meaning and really we're just talking about data
141 | 				accessible via a URI. Is there a term other than 'data' that is
142 | 				appropriate here? ~MM -->
143 | 				<!-- I think this is fine. ~NDW -->
144 | 				<t>
145 | 					An "authority key" is defined as the OpenPGP secret key used
146 | 					to sign a particular keylist. Every keylist has a
147 | 					corresponding authority key, and every authority key has at
148 | 					least one corresponding keylist. A single authority key
149 | 					SHOULD NOT be used to sign multiple keylists.
150 | 				</t>
151 | 				<!-- I'm not opposed to it, but why shouldn't the same authority
152 | 				key be used to sign multiple keylists? I think it'd be confusing
153 | 				in the UI in GPG Sync if you do this, because they keylist is
154 | 				displayed by the authority key's UID. But from a security
155 | 				standpoint, it should be probably be just as secure. ~ML -->
156 | 				<!-- I removed the reference to security. One potential
157 | 				consideration, though, is that this sentence is less about the
158 | 				spec and more about the end user. Perhaps we should just remove
159 | 				the reference all together because it doesn't fit into the
160 | 				implementation but rather the end user's habits? Could be a
161 | 				point of criticism. ~MM -->
162 | 				<t>
163 | 					To be "subscribed" to a keylist means that a program will
164 | 					retreive that keylist on a regular interval. After
165 | 					retrieval, that program will perform an update to an
166 | 					internal OpenPGP keystore.
167 | 				</t>
168 | 				<!-- TODO: This needs to be cleaned/tightened. ~MM -->
169 | 				<t>
170 | 					A "client" is a program that allows the user to subscribe to
171 | 					keylists. A client may be an OpenPGP client itself or a
172 | 					separate program that interfaces with an OpenPGP client to
173 | 					update its keystore.
174 | 				</t>
175 | 			</section>
176 | 			<section anchor="note-to-readers" title="Note to Readers">
177 | 				<t>RFC Editor: please remove this section prior to
178 | 				publication.</t>
179 | 				<t>Development of this Internet draft takes place on GitHub at
180 | 				<eref
181 | 				target="https://github.com/firstlookmedia/keylist-rfc">firstlookmedia/Keylist-RFC</eref>.
182 | 				</t>
183 | 				<t>We are still considering whether this Draft is better for the Experimental or
184 | 				Informational track. All feedback is appreciated.</t>
185 | 			</section>
186 | 		</section>
187 | 		<section anchor="functions" title="Functions and Procedures">
188 | 			<t>
189 | 				As new keys are created and other keys are revoked, it is
190 | 				critical that all members of an organization have the most
191 | 				recent set of keys available on their computers. Keylists enable
192 | 				organizations to publish a directory of OpenPGP keys that
193 | 				clients can use to keep their internal keystores up-to-date.
194 | 			</t>
195 | 			<section anchor="keylist-subscribe" title="Subscribing to Keylists">
196 | 				<t>
197 | 					A single client may subscribe to any number of keylists.
198 | 					When a client first subscribes to a keylist, it SHOULD
199 | 					update or import every key present in the keylist into its
200 | 					local keystore. Keylist subscriptions SHOULD be persistent
201 | 					-- that is, they should be permanently stored by the client
202 | 					to enable future automatic updates.
203 | 				</t>
204 | 				<t>
205 | 					To subscribe to a keylist, the client must be aware of the
206 | 					keylist URI (see <xref target="RFC3986" />), and the
207 | 					fingerprint of the authority key used to sign the
208 | 					keylist. The protocol used to retrieve the keylist and its
209 | 					signature SHOULD be HTTPS (see <xref target="RFC2818" />),
210 | 					however other implementation MAY be supported. A client
211 | 					implementing keylist functionality MUST support the
212 | 					retrieval of keylists and signatures over HTTPS. All other
213 | 					protocols are OPTIONAL.
214 | 				</t>
215 | 				<t>
216 | 					A client MUST NOT employ a trust-on-first-use (TOFU) model for
217 | 					determining the fingerprint of the authority public key; the
218 | 					authority public key fingerprint must be explicitly provided
219 | 					by the user.
220 | 				</t>
221 | 				<t>
222 | 					The process by which the client stores its keylist
223 | 					subscriptions is out of scope, as is the means by which
224 | 					subscription functionality is exposed to the end-user.
225 | 				</t>
226 | 				<t>
227 | 					The client MAY provide the option to perform all its network
228 | 					activity over a SOCKS5 proxy (see <xref target="RFC1928" />).
229 | 				</t>
230 | 			</section>
231 | 			<section anchor="keylist-update" title="Automatic Updates">
232 | 				<t>
233 | 					The primary purpose of keylists is to enable periodic
234 | 					updates of OpenPGP clients' internal keystores. We RECOMMEND
235 | 					that clients provide automatic 'background' update functionality;
236 | 					we also regonize that automatic background updates are not possible
237 | 					in every application (specifically cross-platform CLI tools).
238 | 				</t>
239 | 				<t>When automatic background updates are provided, we RECOMMEND
240 | 					that clients provide a default refresh interval of less than
241 | 					one day, however we also RECOMMEND that clients allow the
242 | 					user to select this interval. The exact time at which
243 | 					updates are performed is not critical.
244 | 				</t>
245 | 				<t>
246 | 					To perform an update, the client MUST perform the following
247 | 					steps on each keylist to which it is subscribed. The steps
248 | 					SHOULD be performed in the given order.
249 | 				</t>
250 | 				<t>
251 | 					<list style="numbers">
252 | 						<t>
253 | 							Obtain a current copy of the keylist from its URI. If a
254 | 							current copy (i.e. not from local cache) cannot be obtained,
255 | 							the client SHOULD abort the update for this keylist and notify
256 | 							the user. The client SHOULD continue the update for other keylists
257 | 							to which it is subscribed, notwithstanding also failing the criteria
258 | 							described in this section.
259 | 						</t>
260 | 						<t>
261 | 							Obtain a current copy of the keylist's signature
262 | 							data from its URI, which is included in the keylist data
263 | 							format specified in <xref target="formats" />. If a current copy
264 | 							cannot be obtained, the client SHOULD abort the update and notify
265 | 							the user. The client SHOULD continue the update for other keylists
266 | 							to which it is subscribed, notwithstanding also failing the criteria
267 | 							described in this section.
268 | 						</t>
269 | 						<!-- I say 'obtain' rather than retrieve because I want
270 | 						to leave open the possibility of a client checking to
271 | 						see if the hash of the file, for example, has changed,
272 | 						and only re-requesting if it has. 'Obtain' is also very
273 | 						ambiguous, though, so it may be to our advantage to use
274 | 						something more specific or explain this rationale
275 | 						outright. ~MM -->
276 | 						<!-- we should be verifying a checksum, and be explicit
277 | 						about it in this description. ~NDW -->
278 | 						<t>
279 | 							Using the keylist and the keylist's signature,
280 | 							cryptographically verify that the keylist was signed
281 | 							using the authority key. If the signature does not
282 | 							verify, the client MUST abort the update of this
283 | 							keylist and SHOULD alert the user. The client SHOULD
284 | 							NOT abort the update of other keylists to which it
285 | 							is subscribed, unless they too fail signature
286 | 							verification.
287 | 						</t>
288 | 						<t>
289 | 							Validate the format of the keylist according to
290 | 							<xref target="formats" />
291 | 							. If the keylist is in an invalid format, the client
292 | 							MUST abort the update this keylist and SHOULD alert
293 | 							the user. The client SHOULD continue the update for
294 | 							other keylists to which it is subscribed, notwithstanding
295 | 							also failing the criteria described in this section.
296 | 						</t>
297 | 						<t>
298 | 							For each fingerprint listed in the keyfile, if a
299 | 							copy of the associated public key is not present in
300 | 							the client's local keystore, retrieve it from the
301 | 							keyserver specified by either the key entry, the keylist (see
302 | 							<xref target="formats" />) or, if the keylist specifies
303 | 							no keyserver, from the user's default keyserver. If the public
304 | 							key cannot be found for a particular fingerprint, the client
305 | 							MUST NOT abort the entire update process; instead, it SHOULD
306 | 							notify the user that the key retrieval failed but otherwise
307 | 							merely skip updating the key and continue.
308 | 							If the key is already present and not revoked,
309 | 							refresh it from the keyserver determined in the same 
310 | 							manner as above. If it is present and revoked, do nothing
311 | 							for that particular key.
312 | 						</t>
313 | 						<!-- TODO: Is it overkill to establish some concept of a
314 | 						'linked keystore' as the keystore that the client
315 | 						interacts with and keeps updated? This is a potential
316 | 						ambiguity for machines with multiple keystores. ~MM -->
317 | 						<!-- That could be useful, but I'd leave that up to the
318 | 						client. Maybe add a recommendation that says something
319 | 						around letting users specify which keystore they want to
320 | 						sync to? It seems slightly out of scope as you are
321 | 						saying retrival and update is out of scope. ~NDW -->
322 | 						<!-- TODO: Should anything else be in this list? ~MM -->
323 | 					</list>
324 | 				</t>
325 | 			</section>
326 | 			<section anchor="keylist-crypto" title="Cryptographic Verification of Keylists">
327 | 				<t>
328 | 					To ensure authenticity of a keylist during an update, the
329 | 					client MUST verify that the keylist's data matches its
330 | 					cryptographic signature, and that the public key used to
331 | 					verify the signature matches the authority key fingerprint
332 | 					given by the user.
333 | 				</t>
334 | 				<t>
335 | 					For enhanced security, it is RECOMMENDED that keylist
336 | 					operators sign each public key listed in their keylist with
337 | 					the authority private key. This way, an organization can
338 | 					have an internal trust relationship without requiring
339 | 					members of the organization to certify each other's public
340 | 					keys.
341 | 				</t>
342 | 			</section>
343 | 		</section>
344 | 		<section anchor="formats" title="Data Element Formats">
345 | 			<t>
346 | 				The following are format specifications for the keylist file and
347 | 				its signature file.
348 | 			</t>
349 | 			<section anchor="keylist-format" title="Keylist">
350 | 				<t>
351 | 					The keylist MUST be a valid JavaScript Object Notation
352 | 					(JSON) Data Interchange Format
353 | 					<xref target="RFC8259" /> object with specific keys
354 | 					and values, as defined below. Note that unless otherwise specified,
355 | 					'key' in this section refers to JSON keys -- not OpenPGP keys.
356 | 				</t>
357 | 				<t>
358 | 					To encode metadata, the keylist MUST have a "metadata" root key
359 | 					with an object as the value ("metadata object").
360 | 					The metadata object MUST contain a "signature_uri" key whose value
361 | 					is the URI string of the keylist's signature file. All metadata keys
362 | 					apart from "signature_uri" are OPTIONAL.
363 | 				</t>
364 | 				<t>
365 | 					The metadata object MAY contain a "keyserver" key with the value of the
366 | 					URI string of a HKP keyserver from which the OpenPGP keys in the keylist
367 | 					should be retrieved. Each PGP key listed in the keylist MAY have a
368 | 					"keyserver" JSON key; if a PGP key in the keylist specifies a HKP keyserver that is
369 | 					different from the one described in the metadata object, the PGP key-specific
370 | 					keyserver should be used to retrieve that particular key (and not the key listed
371 | 					in the metadata object).
372 | 				</t>
373 | 				<t>
374 | 					The metadata object MAY contain a "comment" key with the
375 | 					value of any string. The metadata object MAY also contain other arbitrary
376 | 					key-value pairs.
377 | 				</t>
378 | 				<!-- TODO: Should we specify in more detail what a keyserver URI
379 | 				is, or even what a keyserver is? More details here:
380 | 				https://github.com/firstlookmedia/keylist-rfc/issues/8#issuecomment-427133308
381 | 				~ML -->
382 | 				<t>
383 | 					The keylist MUST have a "keys" key with an array as the value.
384 | 					This array contains a list of OpenPGP key fingerprints and
385 | 					metadata about them. Each item in the array MUST be an object.
386 | 					Each of these objects MUST have a "fingerprint" key with the
387 | 					value of a string that contains the full 40-character
388 | 					hexadecimal public key fingerprint, as defined in OpenPGP
389 | 					Message Format
390 | 					<xref target="RFC4880" />
391 | 					. Any number of space characters (' ', U+0020) MAY be included
392 | 					at any location in the fingerprint string. These objects MAY
393 | 					contain "name" (the name of the PGP key's owner), "email" 
394 | 					(an email of the PGP key's owner), "keyserver" (a HKP keyserver 
395 | 					from which the key should be retrieved), and "comment" key-value pairs,
396 | 					as well as any other key-value pairs.
397 | 					<!-- Maybe the edit here was a bit _too_ reductive. Let me know if you
398 | 					think I cut too much. The thinking is really that "name", "email", and
399 | 					"comment" keys are really just optional, so it makes sense to merge them
400 | 					into a single sentence, but I'm also completely open to reverting this
401 | 					change if you prefer the old phrasing! -->
402 | 				</t>
403 | 				<t>
404 | 					The following is an example of a valid keylist.
405 | 				</t>
406 | 				<figure>
407 | 					<artwork>
408 | {
409 |   "metadata": {
410 |     "signature_uri": "https://www.example.com/keylist.json.asc",
411 |     "comment": "This is an example of a keylist file"
412 |   },
413 |   "keys": [
414 |     {
415 |       "fingerprint": "927F419D7EC82C2F149C1BD1403C2657CD994F73",
416 |       "name": "Micah Lee",
417 |       "email": "micah.lee@theintercept.com",
418 |       "comment": "Each key can have a comment"
419 |     },
420 |     {
421 |       "fingerprint": "1326CB162C6921BF085F8459F3C78280DDBF52A1",
422 |       "name": "R. Miles McCain",
423 |       "email": "0@rmrm.io",
424 | 	  "keyserver": "https://keys.openpgp.org/"
425 |     },
426 |     {
427 |       "fingerprint": "E0BE0804CF04A65C1FC64CC4CAD802E066046C02",
428 |       "name": "Nat Welch",
429 |       "email": "nat.welch@firstlook.org"
430 |     }
431 |   ]
432 | }
433 | 					</artwork>
434 | 				</figure>
435 | 			</section>
436 | 			<section anchor="sigfile" title="Signature">
437 | 				<t>
438 | 					The signature file MUST be an ASCII-armored 'detached
439 | 					signature' of the keylist file, as defined in OpenPGP
440 | 					Message Format
441 | 					<xref target="RFC4880" />
442 | 					.
443 | 				</t>
444 | 			</section>
445 | 			<section anchor="wellknown" title="Well-Known URL">
446 | 				<t>
447 | 					Keylists SHOULD NOT be well-known resources <xref target="RFC4880" />.
448 | 					To subscribe to a keylist, the client must be aware not only of the keylist's
449 | 					location, but also of the fingerprint of the authority public key used to sign the keylist.
450 | 					Furthermore, because keylists can reference public keys from several different domains,
451 | 					the expected host of the well-known location for a keylist may not always be self-evident.
452 | 				</t>
453 | 			</section>
454 | 		</section>
455 | 		<section anchor="implementation" title="Implementation Status">
456 | 			<t>
457 | 				GPG Sync, an open source program created by one of the authors,
458 | 				implements this experimental standard. GPG Sync is used by First
459 | 				Look Media and the Freedom of the Press Foundation to keep
460 | 				OpenPGP keys in sync across their organizations, as well as to
461 | 				publish their employee's OpenPGP keys to the world. These
462 | 				organizations collectively employ more than 200 people and have
463 | 				used the system described in this document successfully for
464 | 				multiple years.
465 | 			</t>
466 | 			<t>
467 | 				GPG Sync's existing code can be found at
468 | 				&lt;https://github.com/firstlookmedia/gpgsync&gt;
469 | 			</t>
470 | 			<t>
471 | 				First Look Media's keylist file can be found at
472 | 				&lt;https://github.com/firstlookmedia/gpgsync-firstlook-fingerprints&gt;
473 | 			</t>
474 | 			<!-- TODO: clunky. We could clean this. ~MM -->
475 | 		</section>
476 | 		<section anchor="securitybenefits" title="Security Benefits">
477 | 			<t>
478 | 				The keylist subscription functionality defined in this
479 | 				document provides a number of security benefits, including:
480 | 			</t>
481 | 			<t>
482 | 				<list style="symbols">
483 | 					<t>
484 | 						The ability for new keys to be quickly distributed
485 | 						across an organization.
486 | 					</t>
487 | 					<t>
488 | 						Removing the complexity of key distribution from
489 | 						end users, allowing them to focus on the content of
490 | 						their communications rather than on key management.
491 | 					</t>
492 | 					<t>
493 | 						The ability for an organization to prevent the
494 | 						spread of falsely attributed keys by centralizing
495 | 						the public key discovery process within their
496 | 						organization without centralized public key hosting.
497 | 					</t>
498 | 					<!-- TODO: others? ~MM -->
499 | 				</list>
500 | 			</t>
501 | 		</section>
502 | 		<section anchor="comparison" title="Relation to Other Technologies">
503 | 			<section anchor="wkd" title="Web Key Directories">
504 | 				<t>
505 | 					Unlike Web Key Directories, keylists are not domain specific. A keylist
506 | 					might contain public key fingerprints for email addresses across several
507 | 					different domains. Moreover, keylists only provide references to public
508 | 					keys by way of fingerprints; Web Key Directories provide the public keys
509 | 					themselves.
510 | 				</t>
511 | 			</section>
512 | 			<section anchor="dns" title="OPENPGPKEY DNS Records">
513 | 				<t>
514 | 					 A keylist MAY reference public keys corresponding to email addresses
515 | 					 across several different domains. Because managing OPENPGPKEY DNS Records
516 | 					 <xref target="RFC7929" /> for a particular domain requires control of that
517 | 					 domain, the OPENPGPKEY DNS Record system is not suitable for cases in
518 | 					 which keys are strewn about several different domains, including ones
519 | 					 outside of the control of an organization's system adminitrators.
520 | 				</t>
521 | 			</section>
522 | 			<!-- We'll want to clean this up, but the messaging we'd like to convey is there. -->
523 | 		</section>
524 | 		<section anchor="securityconsiderations" title="Security Considerations">
525 | 				<t>
526 | 					There is a situation in which keylist subscriptions could
527 | 					pose a potential security threat. If both the authority
528 | 					key and the keylist distribution system were to be
529 | 					compromised, it would be possible for an attacker to
530 | 					distribute any key of their choosing to the subscribers of the
531 | 					keylist. The potential consequences of this attack are limited,
532 | 					however, because the attacker cannot remove or modify the keys
533 | 					already present on subscribers' systems.
534 | 				</t>
535 | 				<t>
536 | 					Some organizations may wish to keep their keylists private. While
537 | 					this may be achievable by serving keylists at URIs only accessible from
538 | 					specific subnets, keylists are designed to be public
539 | 					documents. As such, clients may leak the contents of keylists to
540 | 					keyservers -- this specification ensures to the best of its ability
541 | 					the integrity of keylists, but not the privacy of keylists.
542 | 				</t>
543 | 			<!-- TODO, see https://tools.ietf.org/html/bcp72 ~MM -->
544 | 		</section>
545 | 		<section anchor="ianaconsiderations" title="IANA Considerations">
546 | 			<t>
547 | 				This document has no actions for IANA.
548 | 			</t>
549 | 		</section>
550 | 	</middle>
551 | 	<back>
552 | 		<references title="Normative References">
553 | 			<?rfc include="reference.RFC.7929.xml"?>
554 | 			<?rfc include="reference.RFC.4880.xml"?>
555 | 			<?rfc include="reference.RFC.3986.xml"?>
556 | 			<?rfc include="reference.RFC.2119.xml"?>
557 | 			<?rfc include="reference.RFC.8259.xml"?>
558 | 			<?rfc include="reference.RFC.2818.xml"?>
559 | 			<?rfc include="reference.RFC.1928.xml"?>
560 | 		</references>
561 | 		<!--
562 | 		<references title="Informative References"> </references>
563 | 		-->
564 | 	</back>
565 | </rfc>
566 | 


--------------------------------------------------------------------------------