No Description
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

xep-0373.xml 36KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886
  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY signcrypt "&lt;signcrypt/&gt;">
  4. <!ENTITY sign "&lt;sign/&gt;">
  5. <!ENTITY crypt "&lt;crypt/&gt;">
  6. <!ENTITY openpgp "&lt;openpgp/&gt;">
  7. <!ENTITY payload "&lt;payload/&gt;">
  8. <!ENTITY % ents SYSTEM 'xep.ent'>
  9. %ents;
  10. ]>
  11. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  12. <xep>
  13. <header>
  14. <title>OpenPGP for XMPP</title>
  15. <abstract>Specifies end-to-end encryption and authentication of data with the help of
  16. OpenPGP, announcement, discovery and retrieval of public keys and a
  17. mechanism to synchronize secret keys over multiple
  18. devices.</abstract>
  19. &LEGALNOTICE;
  20. <number>0373</number>
  21. <status>Experimental</status>
  22. <type>Standards Track</type>
  23. <sig>Standards</sig>
  24. <approver>Council</approver>
  25. <dependencies>
  26. <spec>XMPP Core</spec>
  27. <spec>XEP-0030</spec>
  28. <spec>XEP-0082</spec>
  29. <spec>XEP-0163</spec>
  30. <spec>XEP-0223</spec>
  31. <spec>XEP-0334</spec>
  32. </dependencies>
  33. <supersedes/>
  34. <supersededby/>
  35. <shortname>ox</shortname>
  36. &flow;
  37. <author>
  38. <firstname>Dominik</firstname>
  39. <surname>Schürmann</surname>
  40. <email>dominik@dominikschuermann.de</email>
  41. <jid>dominik@dominikschuermann.de</jid>
  42. </author>
  43. <author>
  44. <firstname>Vincent</firstname>
  45. <surname>Breitmoser</surname>
  46. <email>look@my.amazin.horse</email>
  47. <jid>valodim@stratum0.org</jid>
  48. </author>
  49. <revision>
  50. <version>0.3.0</version>
  51. <date>2018-04-16</date>
  52. <initials>fs</initials>
  53. <remark>
  54. Split public keys into metadata and data nodes.
  55. </remark>
  56. </revision>
  57. <revision>
  58. <version>0.2.1</version>
  59. <date>2017-11-13</date>
  60. <initials>fs</initials>
  61. <remark>
  62. <ul>
  63. <li>Recommend setting the PubSub configuration field 'send_last_published_item' to 'on_sub'.</li>
  64. <li>Only recommend persistent PubSub nodes.</li>
  65. </ul>
  66. </remark>
  67. </revision>
  68. <revision>
  69. <version>0.2</version>
  70. <date>2017-09-11</date>
  71. <initials>XEP Editor (jwi)</initials>
  72. <remark>Defer due to lack of activity.</remark>
  73. </revision>
  74. <revision>
  75. <version>0.1.3</version>
  76. <date>2016-07-15</date>
  77. <initials>fs (XEP Editor: ssw)</initials>
  78. <remark><p>Update acknowledgements.</p></remark>
  79. </revision>
  80. <revision>
  81. <version>0.1.2</version>
  82. <date>2016-07-11</date>
  83. <initials>bjc (XEP Editor: ssw)</initials>
  84. <remark><p>Minior editorial fixes.</p></remark>
  85. </revision>
  86. <revision>
  87. <version>0.1.1</version>
  88. <date>2016-06-04</date>
  89. <initials>fs</initials>
  90. <remark><p>Minior editorial fixes.</p></remark>
  91. </revision>
  92. <revision>
  93. <version>0.1</version>
  94. <date>2016-05-10</date>
  95. <initials>XEP Editor (ssw)</initials>
  96. <remark><p>Initial published version approved by the XMPP Council.</p></remark>
  97. </revision>
  98. <revision>
  99. <version>0.0.1</version>
  100. <date>2016-03-25</date>
  101. <initials>fs</initials>
  102. <remark><p>First draft.</p></remark>
  103. </revision>
  104. </header>
  105. <section1 topic='Introduction' anchor='intro'>
  106. <p>This XMPP extension protocol specifies the foundations of
  107. end-to-end encryption and authentication, based on digital
  108. signatures, of data with the help of OpenPGP. Additional XEPs will
  109. use this extension protocol as building block when specifying their
  110. own OpenPGP profile suiting their use case. One such profile is the
  111. Instant Messaging Profile specified in &xep0374;.</p>
  112. <p>XMPP provides the mechanisms to solve a lot of issues that come
  113. with modern day OpenPGP usage. For example, based on &xep0163; this
  114. specification describes a standardized way to discover OpenPGP
  115. public keys of other entities. But unlike the OpenPGP keyservers,
  116. this process establishes a strong relation between the key and the
  117. key's owning entity (usually a human user). A similar mechanism
  118. described herein allows to synchronize the secret key(s) across
  119. multiple devices.</p>
  120. <p>OpenPGP in return allows for end-to-end encrypted data to be
  121. exchanged between one, two or even multiple entities
  122. (multi-end-to-multi-end encryption). Therefore this XEP can be used
  123. for example to implement end-to-end encrypted &xep0045;.</p>
  124. </section1>
  125. <section1 topic='Glossary' anchor='glossary'>
  126. <dl>
  127. <di><dt>OpenPGP element</dt><dd>An XMPP extension element: &openpgp; qualified by the 'urn:xmpp:openpgp:0' namespace</dd></di>
  128. <di><dt>OpenPGP content element</dt><dd>An element embedded via OpenPGP in a &openpgp; element. Either one of &signcrypt;, &sign; or &crypt;, qualified by the 'urn:xmpp:openpgp:0' namespace.</dd></di>
  129. <di><dt>PEP</dt><dd>&xep0163;</dd></di>
  130. <di><dt>Public-Key metadata node ("metadata node")</dt><dd>A PEP node containing metadata of the entity's public OpenPGP key.</dd></di>
  131. <di><dt>Public-Key data node ("data node")</dt><dd>A PEP node containing an entity's public OpenPGP key.</dd></di>
  132. <di><dt>Secret-Key node</dt><dd>A PEP node containing an entity's encrypted secret OpenPGP key.</dd></di>
  133. <di><dt>OpenPGP v4 Fingerprint String</dt><dd>A String representing the OpenPGP v4 fingerprint of a key.</dd></di>
  134. </dl>
  135. </section1>
  136. <section1 topic='OpenPGP Encrypted and Signed Data' anchor='signcrypt'>
  137. <section2 topic='Exchanging OpenPGP Encrypted and Signed Data' anchor='exchange'>
  138. <p>The &openpgp; extension element qualified by the
  139. 'urn:xmpp:openpgp:0' namespace is used in order to exchange
  140. encrypted and signed data.</p>
  141. <example caption='The &openpgp; extension within a message.'><![CDATA[
  142. <message to='juliet@example.org'>
  143. <openpgp xmlns='urn:xmpp:openpgp:0'>
  144. BASE64_OPENPGP_MESSAGE
  145. </openpgp>
  146. </message>]]></example>
  147. <p>The text content of &openpgp; ("BASE64_OPENPGP_MESSAGE") is a
  148. Base64 encoded (&rfc4648; <link
  149. url='https://tools.ietf.org/html/rfc4648#section-4'>§ 4</link>)
  150. OpenPGP message as specified in &rfc4880; which contains an
  151. encrypted and/or signed UTF-8 (&rfc3629;) encoded string. This
  152. string MUST correspond to exactly one OpenPGP content element,
  153. that is, it represents either a &signcrypt;, a &sign; or a &crypt;
  154. extension element qualified by the 'urn:xmpp:openpgp:0'
  155. namespace. Note that OpenPGP's ASCII Armor is not used, instead
  156. the XMPP client MUST encode the raw bytes of the OpenPGP message using
  157. Base64.</p>
  158. <p>In case of a &signcrypt; element, the OpenPGP message embedded
  159. in the &openpgp; element MUST be encrypted and signed, and SHOULD
  160. also be encrypted to self. In case of a &sign; element, the
  161. OpenPGP message MUST be signed and MUST NOT be encrypted. In case
  162. of &crypt; the OpenPGP message MUST NOT be signed, but MUST be
  163. encrypted.</p>
  164. <example caption='The &signcrypt; extension element.'><![CDATA[
  165. <signcrypt xmlns='urn:xmpp:openpgp:0'>
  166. <to jid='juliet@example.org'/>
  167. <time stamp='2014-07-10T17:06:00+02:00'/>
  168. <rpad>
  169. f0rm1l4n4-mT8y33j!Y%fRSrcd^ZE4Q7VDt1L%WEgR!kv
  170. </rpad>
  171. <payload>
  172. <body xmlns='jabber:client'>
  173. This is a secret message.
  174. </body>
  175. </payload>
  176. </signcrypt>]]></example>
  177. <p>OpenPGP content elements MUST possess exactly one 'time'
  178. element as direct child elements. The &signcrypt; and &crypt;
  179. content elements MUST contain at least one 'to' element(s), which
  180. MUST have a 'jid' attribute containing the intended recipient's
  181. XMPP address of the signed and/or encrypted data to prevent
  182. Surreptitious Forward Attacks<note>Jee Hea An, Yevgeniy Dodis, and
  183. Tal Rabin. 2002. On the Security of Joint Signature and
  184. Encryption. In Proceedings of the International Conference on the
  185. Theory and Applications of Cryptographic Techniques: Advances in
  186. Cryptology (EUROCRYPT '02), Lars R. Knudsen
  187. (Ed.). Springer-Verlag, London, UK, UK, 83-107. &lt;<link
  188. url='https://www.iacr.org/archive/eurocrypt2002/23320080/adr.pdf'>https://www.iacr.org/archive/eurocrypt2002/23320080/adr.pdf</link>&gt;</note>.
  189. The XMPP address found in the 'to' element's 'jid' attribute
  190. SHOULD be without Resourcepart (i.e., a bare JID). A &sign; content
  191. element may not carry a 'to' attribute. The 'time' element MUST
  192. have a 'stamp' attribute which contains the timestamp when the
  193. OpenPGP content element was signed and/or encrypted in the
  194. DateTime format as specified in &xep0082; § 3.2. The &signcrypt;
  195. and &crypt; elements SHOULD furthermore contain a 'rpad' element
  196. which text content is a random-length random-content padding.</p>
  197. <table caption='OpenPGP Content Element Properties'>
  198. <tr>
  199. <th>Content Element</th>
  200. <th>'to' Element</th>
  201. <th>'time' Element</th>
  202. <th>&lt;rpad/&gt; Element</th>
  203. <th>&lt;payload/&gt; Element</th>
  204. </tr>
  205. <tr>
  206. <td>&signcrypt;</td>
  207. <td>MUST have at least one</td>
  208. <td>MUST have exactly one</td>
  209. <td>SHOULD have exactly one</td>
  210. <td>MUST have exactly one</td>
  211. </tr>
  212. <tr>
  213. <td>&sign;</td>
  214. <td>MAY NOT contain one</td>
  215. <td>MUST have exactly one</td>
  216. <td>NOT REQUIRED</td>
  217. <td>MUST have exactly one</td>
  218. </tr>
  219. <tr>
  220. <td>&crypt;</td>
  221. <td>MUST have at least one</td>
  222. <td>MUST have exactly one</td>
  223. <td>SHOULD have exactly one</td>
  224. <td>MUST have exactly one</td>
  225. </tr>
  226. </table>
  227. <p>OpenPGP content elements MUST possess exactly one &payload;
  228. element. The child elements of &payload; can be seen as OpenPGP
  229. secured Stanza extension elements which are encrypted and/or
  230. signed. After the &openpgp; element and the including &signcrypt;,
  231. &sign; or &crypt; element was verified, they are processed
  232. according to the specification of the relevant OpenPGP for XMPP
  233. profile (see for example &xep0374;).</p>
  234. </section2>
  235. <section2 topic='Verification of &openpgp; Content' anchor='openpgp-verification'>
  236. <p>Recipients MUST verify that the signature is valid, that the
  237. signature's key corresponds to the sender's key, and that the
  238. sender's key has a User ID containing the sender's XMPP
  239. address in the form "xmpp:juliet@example.org" (for details see
  240. <link url='#openpgp-user-ids'>"OpenPGP User IDs"</link>). Thus,
  241. the recipient may
  242. need to retrieve the key from the Personal Eventing Protocol node
  243. as described above. At least one of the XMPP addresses found in
  244. the 'to' elements contained in OpenPGP content element MUST
  245. correspond to the outer 'to' of the XMPP &MESSAGE;. Furthermore,
  246. recipients are RECOMMENDED to verify the 'time' element for
  247. plausibility or to display it to a user for verification.</p>
  248. </section2>
  249. </section1>
  250. <section1 topic='Announcing and Discovering Public Keys via PEP' anchor='announcing-discover-pubkey'>
  251. <p>Parties interested in exchanging encrypted data between each
  252. other via OpenPGP need to know the public key(s) of the
  253. recipients. The following section specifies a mechanism to announce
  254. and discover public keys.</p>
  255. <p>Two PEP node types are invovled: A "medatata node" is used to store meta information about
  256. OpenPGP keys used by an entity while the actual public keys are stored in "data nodes".</p>
  257. <section2 topic='The OpenPGP Public-Key Data Node' anchor='annoucning-pubkey'>
  258. <p>The public key data, as specified in <cite>RFC 4880</cite>, is stored in a PEP data
  259. node. Note that OpenPGP's ASCII Armor is not used, instead the XMPP client MUST encode the
  260. public key using Base64. The id of the node MUST be "urn:xmpp:openpgp:0:public-keys:" followed
  261. by the fingerprint string of the OpenPGP public-key contained in the data node.</p>
  262. <p>The <em>OpenPGP v4 fingerprint string</em> is obtained as follows: First the raw bytes of the
  263. fingerprint are computed as specified in <cite>RFC 4880 § 12.2.</cite>. Then the bytes are
  264. encoded as a hexadecimal string using upper case characters<note>This matches the representation
  265. used by GnuPG minus the SPACE separation.</note>.</p>
  266. <p>The data node MUST contain an &lt;pubkey/&gt; element qualified by the 'urn:xmpp:openpgp:0'
  267. namespace. An optional 'date' attribute holds the information about the last modification of the
  268. key as DateTime format of <cite>XEP-0082</cite>. The element MUST include a &lt;data/&gt;
  269. element which contains the data of the key Base64 encoded.</p>
  270. <example caption='Saving the public key in the data node.'><![CDATA[
  271. <iq type='set' from='juliet@example.org/balcony' id='publish1'>
  272. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  273. <publish node='urn:xmpp:openpgp:0:public-keys:1357B01865B2503C18453D208CAC2A9678548E35'>
  274. <item>
  275. <pubkey xmlns='urn:xmpp:openpgp:0' date='2018-01-21T10:46:21Z'>
  276. <data>
  277. BASE64_OPENPGP_PUBLIC_KEY
  278. </data>
  279. </pubkey>
  280. </item>
  281. </publish>
  282. </pubsub>
  283. </iq>]]></example>
  284. </section2>
  285. <section2 topic='The OpenPGP Public Key Metadata Node' anchor='announcing-pubkey-list'>
  286. <p>To update the public keys used by an entity, the metadata node is updated. Before adding a
  287. OpenPGP key ID to the metadata node, the publisher MUST ensure that the public key is available
  288. at the corresponding data node.</p>
  289. <p> The ID of the metadata node is 'urn:xmpp:openpgp:0:public-keys'. It contains a
  290. &lt;public-keys-list/&gt; element qualified by the 'urn:xmpp:openpgp:0' namespace containing one
  291. or more &lt;pubkey-metadata/&gt; elements. Every pubkey-metadata element MUST have a
  292. 'v4-fingerprint' attribute, containing the OpenPGP v4 fingerprint string, and a 'date'
  293. attribute, containing the time the key was published or updated in DateTime format of
  294. <cite>XEP-0082</cite>. An OpenPGP V4 fingerprint MUST NOT occur in the list more than once.</p>
  295. <example caption='Publishing a public key to the metadata node.'><![CDATA[
  296. <iq type='set' from='juliet@example.org/balcony' id='publish1'>
  297. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  298. <publish node='urn:xmpp:openpgp:0:public-keys'>
  299. <item>
  300. <public-keys-list xmlns='urn:xmpp:openpgp:0'>
  301. <pubkey-metadata
  302. v4-fingerprint='1357B01865B2503C18453D208CAC2A9678548E35'
  303. date='2018-03-01T15:26:12Z'
  304. />
  305. <pubkey-metadata
  306. v4-fingerprint='67819B343B2AB70DED9320872C6464AF2A8E4C02'
  307. date='1953-05-16T12:00:00Z'
  308. />
  309. </public-keys-list>
  310. </item>
  311. </publish>
  312. </pubsub>
  313. </iq>]]></example>
  314. </section2>
  315. <section2 topic='Discovering Public Keys' anchor='discover-pubkey'>
  316. <p>In order to discover the OpenPGP public keys, the interested entity first queries a remote
  317. entities metadata note to learn about its currently annouced OpenPGP keys. Then the public
  318. OpenPGP key(s) can be retrieved by querying the data node for a specific fingerprint.</p>
  319. <example caption='Requesting an OpenPGP public key from an XMPP entity.'><![CDATA[
  320. <iq from='romeo@example.org/orchard'
  321. to='juliet@example.org'
  322. type='get'
  323. id='getpub'>
  324. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  325. <items node='urn:xmpp:openpgp:0:public-keys:1357B01865B2503C18453D208CAC2A9678548E35'
  326. max_items='1'/>
  327. </pubsub>
  328. </iq>]]></example>
  329. <example caption='Personal Eventing Protocol result containing the requested public key.'><![CDATA[
  330. <iq from='juliet@example.org'
  331. to='romeo@example.org/orchard'
  332. type='result'
  333. id='getpub'>
  334. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  335. <items node='urn:xmpp:openpgp:0:public-keys:1357B01865B2503C18453D208CAC2A9678548E35'>
  336. <item>
  337. <pubkey xmlns='urn:xmpp:openpgp:0'>
  338. <data>
  339. BASE64_OPENPGP_PUBLIC_KEY
  340. </data>
  341. </pubkey>
  342. </item>
  343. </items>
  344. </pubsub>
  345. </iq>]]></example>
  346. <p>Note that the result may contain multiple pubkey elements. Only
  347. the public keys found in the most recent item MUST be used. Requesters
  348. may want to limit the results to the most recent item using the
  349. 'max_items' attribute set to '1'. Clients could alternatively use
  350. &xep0059; as an alternative to 'max_items' but accoding to
  351. <cite>XEP-0060</cite> RSM is not (yet) mandatory for PubSub
  352. services.</p>
  353. <p>Some XMPP services may not provide the Personal Eventing
  354. Protocol feature required to provide the mechanism described
  355. here. If so, they will return an &IQ; error of type
  356. service-unavailable.</p>
  357. </section2>
  358. <section2 topic='Receiving notifications about key changes' anchor='pubsub-notifications'>
  359. <p>Entities which are subscribed to the metadata node or advertise the
  360. "urn:xmpp:openpgp:0:public-keys+notify" feature via &xep0115; (see <cite>XEP-0060 § 9.2</cite>)
  361. receive a notification upon a node update.</p>
  362. </section2>
  363. </section1>
  364. <section1 topic='Synchronizing the Secret Key with a Private PEP Node' anchor='synchro-pep'>
  365. <!--
  366. TODO: Also split in metadata and data node? Probably not, because it could cause stale secret
  367. keys on the service (since it is not possible to list all PEP nodes starting with
  368. e.g. urn:xmpp:openpgp:0:secret-keys and delete old ones. We could split later anyways.
  369. -->
  370. <p>A private PEP node is used to allow XMPP clients to synchronize
  371. the user's secret OpenPGP key. Where private PEP node is defined: A
  372. PEP node in whitelist mode where only the bare JID of the key
  373. owner is whitelisted as described in &xep0223;. The secret key is
  374. additionally encrypted.</p>
  375. <section2 topic='Required PEP features'>
  376. <p>The used PEP server MUST support PEP and the whitelist access
  377. model. It SHOULD also support persistent items.</p>
  378. <section3 topic='Discovering support'>
  379. <example caption='Account owner queries server regarding protocol support'><![CDATA[
  380. <iq from='juliet@capulet.lit/balcony'
  381. to='juliet@capulet.lit'
  382. id='disco1'
  383. type='get'>
  384. <query xmlns='http://jabber.org/protocol/disco#info'/>
  385. </iq>
  386. ]]></example>
  387. <p>The service discovery result must contain a PEP identity
  388. '&lt;identity category='pubsub' type='pep'/&gt;, and the
  389. 'http://jabber.org/protocol/pubsub#access-whitelist'
  390. feature. Ideally it also contains the
  391. 'http://jabber.org/protocol/pubsub#persistent-items'
  392. feature</p>
  393. <example caption='Server communicates protocol support'><![CDATA[
  394. <iq from='juliet@capulet.lit'
  395. to='juliet@capulet.lit/balcony'
  396. id='disco1'
  397. type='result'>
  398. <query xmlns='http://jabber.org/protocol/disco#info'>
  399. <identity category='account' type='registered'/>
  400. <identity category='pubsub' type='pep'/>
  401. <feature var='http://jabber.org/protocol/pubsub#access-presence'/>
  402. <feature var='http://jabber.org/protocol/pubsub#auto-create'/>
  403. <feature var='http://jabber.org/protocol/pubsub#auto-subscribe'/>
  404. <feature var='http://jabber.org/protocol/pubsub#config-node'/>
  405. <feature var='http://jabber.org/protocol/pubsub#create-and-configure'/>
  406. <feature var='http://jabber.org/protocol/pubsub#create-nodes'/>
  407. <feature var='http://jabber.org/protocol/pubsub#filtered-notifications'/>
  408. <feature var='http://jabber.org/protocol/pubsub#persistent-items'/>
  409. <feature var='http://jabber.org/protocol/pubsub#publish'/>
  410. <feature var='http://jabber.org/protocol/pubsub#retrieve-items'/>
  411. <feature var='http://jabber.org/protocol/pubsub#subscribe'/>
  412. ...
  413. </query>
  414. </iq>]]></example>
  415. </section3>
  416. </section2>
  417. <section2 topic='Requesting Information About the Secret Key PEP Node' anchor='req-info-secret-pep-node'>
  418. <p>In order to synchronize the secret key over a private PEP node,
  419. clients first need to discover and verify the node for the correct
  420. settings.</p>
  421. <section3 topic='Client Sends Request'>
  422. <example caption='Requesting the user&apos;s secret key.'><![CDATA[
  423. <iq from='romeo@example.org/orchard'
  424. to='juliet@example.org'
  425. type='get'
  426. id='getsecret'>
  427. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  428. <items node='urn:xmpp:openpgp:secret-key:0'
  429. max_items='1'/>
  430. </pubsub>
  431. </iq>]]></example>
  432. </section3>
  433. <section3 topic='PEP Service Success Response'>
  434. <example caption='Personal Eventing Protocol result containing the requested secret key.'><![CDATA[
  435. <iq from='juliet@example.org'
  436. to='romeo@example.org/orchard'
  437. type='result'
  438. id='getsecret'>
  439. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  440. <items node='urn:xmpp:openpgp:secret-key:0'>
  441. <item>
  442. <secretkey xmlns='urn:xmpp:openpgp:0'>
  443. BASE64_OPENPGP_ENCRYPTED_SECRET_KEY
  444. </secretkey>
  445. </item>
  446. </items>
  447. </pubsub>
  448. </iq>]]></example>
  449. </section3>
  450. <section3 topic='PEP Node Does Not Exist Response'>
  451. <p>If the node does not exist the service will return an &IQ;
  452. error indicating the item-not-found error condition. The
  453. client MUST then create it with an whitelist access model.</p>
  454. <example caption='Node does not exist'><![CDATA[
  455. <iq from='juliet@example.org'
  456. to='romeo@example.org/orchard'
  457. type='error'
  458. id='getsecret'>
  459. <error type='cancel'>
  460. <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  461. </error>
  462. </iq>]]></example>
  463. </section3>
  464. <section3 topic='PEP Not Supported'>
  465. <p>The service will return a service-unavailable error &IQ; if
  466. it does not support PEP.</p>
  467. <example caption='Node does not exist'><![CDATA[
  468. <iq from='juliet@example.org'
  469. to='romeo@example.org/orchard'
  470. type='error'
  471. id='getsecret'>
  472. <error type='cancel'>
  473. <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  474. </error>
  475. </iq>]]></example>
  476. </section3>
  477. </section2>
  478. <section2 topic='Creating the Secret Key PEP Node'>
  479. <example caption='Client creates secret key PEP node'><![CDATA[
  480. <iq type='set'
  481. from='juliet@example.org/balcony'
  482. id='create-node'>
  483. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  484. <create node='urn:xmpp:openpgp:secret-key:0'/>
  485. <configure>
  486. <x xmlns='jabber:x:data' type='submit'>
  487. <field var='FORM_TYPE' type='hidden'>
  488. <value>http://jabber.org/protocol/pubsub#node_config</value>
  489. </field>
  490. <field var='pubsub#access_model'>
  491. <value>whitelist</value>
  492. </field>
  493. <field var='pubsub#send_last_published_item'>
  494. <value>on_sub</value>
  495. </field>
  496. </x>
  497. </configure>
  498. </pubsub>
  499. </iq>]]></example>
  500. <example caption='Service informs requesting entity of success'><![CDATA[
  501. <iq type='result'
  502. to='juliet@example.org/balcony'
  503. id='create-node'/>]]></example>
  504. <p>The node is now created and the only affiliated entity is the
  505. bare JID of the user, who created the node, with an affiliation as
  506. 'owner'.</p>
  507. <p>In order to set a new secret key, clients store the encrypted
  508. secret key as Base64 encoded raw OpenPGP message within an
  509. &lt;secretkey/&gt; element qualified by the 'urn:xmpp:openpgp:0'
  510. namespace. These secret key backups are created as follows:</p>
  511. <ol>
  512. <li>All secret keys that should be included in the backup MUST
  513. be concatenated in their transferable key format (<cite>RFC
  514. 4880</cite> <link
  515. url='http://tools.ietf.org/html/rfc4880#section-11.1'>§
  516. 11.1</link>).
  517. </li>
  518. <li>A backup code is generated from secure random: The backup
  519. code consists of 24 upper case characters from the Latin
  520. alphabet and numbers without 'O' ("LATIN CAPITAL LETTER O")
  521. and '0' ("DIGIT ZERO") (alphabet:
  522. <tt>123456789ABCDEFGHIJKLMNPQRSTUVWXYZ</tt>) grouped into
  523. 4-character chunks, e.g.,
  524. <tt>TWNK-KD5Y-MT3T-E1GS-DRDB-KVTW</tt>. The characters MUST be
  525. generated from cryptographically secure random. For example
  526. <tt><link
  527. url='https://lwn.net/Articles/606141/'>getrandom(2)</link></tt>,
  528. <tt><link
  529. url='https://docs.oracle.com/javase/8/docs/api/java/security/SecureRandom.html'>SecureRandom</link></tt>
  530. or <tt>/dev/urandom</tt>. More information about the
  531. randomness requirements for security can be found in &rfc4086;
  532. </li>
  533. <li>The whole backup code including the dashes is directly
  534. used as a string to encrypt the concatenated transferable keys
  535. as an OpenPGP message. More precisely: It is used as the
  536. symmetric-key for a Symmetric-Key Encrypted Session Key Packet
  537. according to <cite>RFC 4880</cite> <link
  538. url='http://tools.ietf.org/html/rfc4880#section-5.3'>§
  539. 5.3</link>; the symmetric-key is thus 29 characters long
  540. including the dashes. The encryption algorithm MUST be one of
  541. the standardized OpenPGP symmetric algorithms, e.g, AES-128.
  542. </li>
  543. </ol>
  544. </section2>
  545. </section1>
  546. <section1 topic='Business Rules' anchor='rules'>
  547. <section2 topic='OpenPGP Packet Format Version Restriction' anchor='openpgp-packet-format-version'>
  548. <p>Implementations of this XEP MUST generate and accept only
  549. version 4 (or higher) OpenPGP packets. Lower version OpenPGP
  550. packets are insecure in many aspects (see for example <cite>RFC
  551. 4880</cite> <link
  552. url='http://tools.ietf.org/html/rfc4880#section-5.5.2'>§
  553. 5.5.2</link>.).</p>
  554. </section2>
  555. <section2 topic='PubSub Node Configuration' anchor='pubsub-node-configuration'>
  556. <p>The Public-Key <em>metadata</em> node and the Secret-Key node SHOULD be configured to either
  557. never send the latest item, or to send the latest item only when a new entity subscribed. Thus
  558. the nodes 'send_last_published_item' configuration option SHOULD be set to either 'never' or
  559. 'on_sub' (see <cite>XEP-0060</cite> <link
  560. url='https://xmpp.org/extensions/xep-0060.html#registrar-formtypes-config'>§ 16.4.4</link>).</p>
  561. </section2>
  562. <section2 topic='Key Enforcement' anchor='key-enforcement'>
  563. <p>Whenever an entity becomes aware that the metadata node has changed (e.g., by receiving a PEP
  564. update from their own account), it SHOULD check that the list contains the key they use. If the
  565. key has been removed, the entity SHOULD reannounce it.</p>
  566. </section2>
  567. </section1>
  568. <section1 topic='Implementors Advice' anchor='implementors-advice'>
  569. <section2 topic='Design Principles and Techniques' anchor='design-and-techniques'>
  570. <p>OpenPGP implementations have a sad history of being not very
  571. user-friendly which results in users either not using OpenPGP or in
  572. users wrongly using OpenPGP. Implementors of this XEP, and
  573. additional future XEPs based on this XEP, therefore should read
  574. <span class='ref'><link
  575. url='http://g10code.com/steed.html'>STEED</link></span><note>Koch,
  576. Werner, and Marcus Brinkman "STEED — Usable End-to-End
  577. Encryption", White Paper, g10 GmbH, 2011-10-17. &lt;<link
  578. url='http://g10code.com/steed.html'>http://g10code.com/steed.html</link>&gt;</note>
  579. and <span class='ref'><link
  580. url='https://www.cs.berkeley.edu/~tygar/papers/Why_Johnny_Cant_Encrypt/OReilly.pdf'>"Why
  581. Johnny can't encrypt"</link></span><note>Whitten, Alma, and
  582. J. Doug Tygar. "Why Johnny Can't Encrypt: A Usability Evaluation
  583. of PGP 5.0." Usenix Security. Vol. 1999. 1999. &lt;<link
  584. url='https://www.cs.berkeley.edu/~tygar/papers/Why_Johnny_Cant_Encrypt/OReilly.pdf'>https://www.cs.berkeley.edu/~tygar/papers/Why_Johnny_Cant_Encrypt/OReilly.pdf</link>&gt;</note>. Implementors
  585. of this XEP are encouraged to provide the concepts described in
  586. STEED:</p>
  587. <ul>
  588. <li>Automatic key generation</li>
  589. <li>Automatic key distribution</li>
  590. <li>Opportunistic encryption</li>
  591. <li>Trust upon first contact</li>
  592. </ul>
  593. <p>Furthermore implementors should design the user interface for
  594. effective security by following the design principles and
  595. techniques for security mentioned in "Why Johnny Can't
  596. Encrypt".</p>
  597. </section2>
  598. <section2 topic='Stanza Size' anchor='stanza-size'>
  599. <p>Implementors should be aware that the size OpenPGP public and
  600. secret keys is somewhere in the range of tens of
  601. kilobytes. Applying Base64 encoding on keys, as it is described
  602. herein, further increases the size. The formula to determine the
  603. Base64 encoded size is: ceil(bytes / 3) * 4. Thus the lower bound
  604. for the maximum stanza size of 10000 bytes, as specified in <cite>RFC
  605. 6120</cite> § 13.12. 4., is usually exceeded. However all XMPP server
  606. implementations, the authors are aware of, follow the
  607. recommendation of the RFC and do not blindly set the maximum
  608. stanza size to such a low value, but use a much higher
  609. threshold. Therefore, this should hardly be an issue for
  610. implementations. Nevertheless, it is advised to keep the size of
  611. OpenPGP keys small by removing all signatures except the most
  612. recent self-signature on each User ID before exporting the key
  613. (cf. GnuPG's <tt>--export-options export-minimal</tt>).
  614. In addition, implementors are advised to handle
  615. &lt;policy-violation/&gt; error responses when trying to
  616. transmit Base64 encoded keys.</p>
  617. </section2>
  618. <section2 topic='XMPP Address Normalization' anchor='xmpp-address-normalization'>
  619. <p>The format of XMPP addresses, sometimes called JIDs, is well
  620. defined. Thus they need to be normalized, as defined in
  621. &rfc7622;. When implementations are required to compare XMPP
  622. addresses for equality, as it is the case in <link
  623. url='#openpgp-verification'>"Verification of &openpgp;
  624. Content"</link>, then they also have to compare the normalized
  625. versions of the addresses.</p>
  626. </section2>
  627. </section1>
  628. <section1 topic='Rationale' anchor='rationale'>
  629. <section2 topic='Key Handling' anchor='key-handling'>
  630. <p>This specification intentionally does not specify if the used
  631. OpenPGP key should be a primary key or a subkey. It is even
  632. possible to announce multiple public keys in the Personal Eventing
  633. Protocol node. Implementations MUST be prepared to find multiple
  634. public keys. The authors however believe that for ease of use only
  635. one OpenPGP key specially crafted for the XMPP use case should be
  636. created, announced and used.</p>
  637. </section2>
  638. <section2 topic='OpenPGP Element and Content Element Design' anchor='openpgp-element-design'>
  639. <p>The &openpgp; and OpenPGP content elements are container
  640. elements for arbitrary signed and encrypted data and can thus act
  641. as building blocks for encrypted data included in Message, IQ and
  642. Presence stanzas. For example, future specifications may use them
  643. to implement encrypted versions of &xep0047; or &xep0261;.</p>
  644. <p>Note that signed OpenPGP messages already contain a timestamp
  645. as per the OpenPGP specification. OpenPGP content elements
  646. nevertheless require the 'time' element because not every OpenPGP
  647. API may provide access to the embedded OpenPGP timestamp.</p>
  648. <p>The 'rpad' element of the OpenPGP content elements exists to
  649. prevent length-based side channel attacks.</p>
  650. </section2>
  651. <section2 topic='Addressing the Issues and Problems of XEP-0027' anchor='solving-xep0027-issues'>
  652. <p>This specification addresses all relevant issues of &xep0027;
  653. (<link url='https://xmpp.org/extensions/xep-0027.html#security'>§
  654. 4</link>, <link
  655. url='https://xmpp.org/extensions/xep-0027.html#issues'>§
  656. 5</link>). It mitigates replay attacks by including the
  657. recipient's address and a timestamp in the OpenPGP content
  658. element<note>Full Replay attack prevention would require a
  659. counter based approach.</note>. It allows for both, signing and
  660. encrypting of the element. The scope of the specification was
  661. deliberately limited to OpenPGP.</p>
  662. <p>Features like signed presences, which is provided by <cite>XEP-0027</cite>,
  663. may be added later on as add-on XEP to this.</p>
  664. </section2>
  665. <section2 topic='Not using OpenPGP ASCII Armor' anchor='openpgp-ascii-armor'>
  666. <p>We decided against OpenPGP ASCII Armor (which contains an
  667. additional checksum) and in favor for Base64, because
  668. encoding should be part of the network application rather than the
  669. crypto layer. Also XMPP, needs no additional error correction of payload.
  670. In "MIME Security with OpenPGP" (&rfc3156;), ASCII Armor
  671. has only been chosen to be backwards compatible with legacy applications
  672. supporting non-MIME OpenPGP emails only.</p>
  673. </section2>
  674. <section2 topic='OpenPGP User IDs' anchor='openpgp-user-ids'>
  675. <p>OpenPGP User IDs normally consist of a name - email address pair, e.g.,
  676. "Juliet &lt;juliet@example.org&gt;" (<cite>RFC 4880</cite> <link
  677. url='http://tools.ietf.org/html/rfc4880#section-5.11'>§ 5.11</link>).
  678. For this XEP, we require User IDs of the format "xmpp:juliet@example.org".
  679. First, it is required to have at least one User ID indicating the use
  680. of this OpenPGP key. When doing certification of keys (key signing),
  681. the partner must know what User ID she actually certifies.
  682. Second, this format uses the standardized URI from <cite>XEP-0147</cite> to indicate
  683. that this User ID corresponds to a key that is used for XMPP.
  684. Third, having the Real Name inside provides no additional security
  685. or guideline if this key should be certified. The XMPP address
  686. is the only trust anchor here.</p>
  687. </section2>
  688. </section1>
  689. <section1 topic='Security Considerations' anchor='security'>
  690. <p>The scope of this XEP is intentionally limited, so that the
  691. specification just defines way for XMPP entities to discover,
  692. announce and synchronize OpenPGP keys, and how to exchange signed
  693. and encrypted data between two or more parties. Everything else is
  694. outside its scope. For example, how 'secure' the key material is
  695. protected on the endpoints is up to the implementation.</p>
  696. <p>And while this XEP specifies a mechanism how to discover and
  697. retrieve a public key, it does not define how the trust relation to
  698. this key should be established. Even if key discovery and retrieval
  699. over XMPP provides a stronger coupling between the possessing entity
  700. (the XMPP address) and the key, as compared to the OpenPGP keyservers,
  701. how a XMPP server authenticates a remote server is a server policy,
  702. which does vary from server to server. Implementation MUST provide a
  703. way for the user to establish and assign trust to a public key. For
  704. example by using a QR code shown on the recipient's device screen.</p>
  705. <p>Besides the protocol defined herein, OpenPGP implementations are
  706. another big attack surface. Needless to say that the security of
  707. encrypted data exchanged using this protocol depends on the security
  708. of the used OpenPGP implementation. It is strongly RECOMMENED to use
  709. existing implementations instead of writing your own. OpenPGP
  710. implementations have suffered from various vulnerabilities in the past
  711. which opened up DoS attack vectors. For example <link
  712. url='https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-4402'>CVE-2013-4402</link>
  713. and <link
  714. url='https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-4617'>CVE-2014-4717</link>.</p>
  715. </section1>
  716. <section1 topic='IANA Considerations' anchor='iana'>
  717. <p>This document requires no interaction with &IANA;.</p>
  718. </section1>
  719. <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  720. <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
  721. <p>The &REGISTRAR; includes 'urn:xmpp:openpgp:0' in its registry of protocol namespaces (see &NAMESPACES;).</p>
  722. </section2>
  723. </section1>
  724. <section1 topic='XML Schema' anchor='schema'>
  725. <p>TODO: Add after the XEP leaves the 'experimental' state.</p>
  726. </section1>
  727. <section1 topic='Acknowledgements' anchor='acknowledgements'>
  728. <p>Thanks to Emmanuel Gil Peyrot, Sergei Golovan, Marc Laporte, Georg
  729. Lukas, Adithya Abraham Philip, Brian Cully and fiaxh for their feedback.</p>
  730. <p>The first draft of this specification was worked out and written
  731. on the wall of the 'Kymera' room in one of Google's buildings by the
  732. authors, consisting of members of the XMPP Standards Foundation and
  733. the OpenKeychain project, at the GSOC Mentors Summit 2015. The
  734. authors would like to thank Google for making it possible by
  735. bringing the right people together.</p>
  736. </section1>
  737. </xep>
  738. <!-- Local Variables: -->
  739. <!-- fill-column: 100 -->
  740. <!-- indent-tabs-mode: nil -->
  741. <!-- End: -->