moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-21 16:55:07 -05:00
Code Issues Releases Wiki Activity

Remove a bunch of accepted XEPs

Browse Source
This commit is contained in:
Jonas Wielicki 2018-03-28 20:29:16 +02:00
parent 84500a6051
commit e3560d71e6
5 changed files with 0 additions and 1296 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

143
inbox/bookmarks2.xml
View File

@ -1,143 +0,0 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY namespace "urn:xmpp:bookmarks:0">
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Bookmarks 2 (This Time it's Serious)</title>
<abstract>This specification defines a syntax and storage profile for keeping a list of chatroom bookmarks on the server.</abstract>
&LEGALNOTICE;
<number>XXXX</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies/>
<supersedes/>
<supersededby/>
<shortname>bookmarks2</shortname>
<registry/>
<discuss>standards</discuss>
<author>
<firstname>Dave</firstname>
<surname>Cridland</surname>
<email>dave.cridland@surevine.com</email>
<jid>dave.cridland@surevine.com</jid>
</author>
<author>
<firstname>Jan-Carel</firstname>
<surname>Brand</surname>
<email>jc@opkode.com</email>
<jid>jc@opkode.com</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2018-03-17</date>
<initials>dwd/jcb</initials>
<remark><p>First draft</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>The original Bookmarks specification (&xep0048;) used the widely available
Private XML Storage (&xep0049;), but stored all bookmarks in a single element.
When the specification was moved to the Standards Track and Draft, it was also
updated to use the user's Pubsub service (&xep0223;), but kept this single element
containing all bookmarks inside a single Pubsub item.</p>
<p>Most implementations have kept to the original, Private XML Storage based solution, and
while some newer implementations have used Pubsub, these are limited in capability by the use of
a single item.</p>
<p>This specification resolves both issues by providing a new Bookmarks specification to migrate to,
and takes the opportunity to update the XML namespace in use as well. The URL storage is dropped,
since it is rarely used. Storage of URL bookmarks is therefore out of scope.</p>
</section1>
<section1 topic="Outline of use">
<p>Clients store each bookmarked chatroom as a Pubsub item within the '&namespace;' node. Each
item SHALL have, as item id, the Room JID of the chatroom (eg, coven@chat.shakespeare.lit).</p>
<p>The payload of the item SHALL be a conference element qualified by the '&namespace;' namespace, with the following syntax:</p>
<table caption='Syntax of conference element'>
<tr>
<th>Element or Attribute</th>
<th>Definition</th>
<th>Datatype</th>
<th>Inclusion</th>
</tr>
<tr>
<td>'autojoin' attribute</td>
<td>Whether the client should automatically join the conference room on login.</td>
<td>boolean defaulting to false &BOOLEANNOTE;</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>'name' attribute</td>
<td>A friendly name for the bookmark.</td>
<td>string</td>
<td>RECOMMENDED</td>
</tr>
<tr>
<td>&lt;nick/&gt; element</td>
<td>The user's preferred roomnick for the chatroom.</td>
<td>string</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>&lt;password/&gt; element</td>
<td>Unencrypted string for the password needed to enter a password-protected room. For security reasons, use of this element is NOT RECOMMENDED.</td>
<td>string</td>
<td>NOT RECOMMENDED</td>
</tr>
</table>
<p>Note: The datatypes are as defined in &w3xmlschema2;.</p>
<example caption='An example of the conference element'><![CDATA[
<conference xmlns=']]>&namespace;<![CDATA['
name='Council of Oberon'
autojoin='true'>
<nick>Puck</nick>
</conference>
]]></example>
<p>This bookmark would be displayed as 'Council of Oberon' and, if activated, would attempt to join the conference room 'council@conference.underhill.org' with nickname 'Puck'.</p>
<p>Note that a bookmark item MUST contain only one conference room.</p>
<p>Note also that a conference element has no truly mandatory attributes or child elements, though a name SHOULD be given. Thus the following is legal:</p>
<example caption='Minimalist conference element'><![CDATA[
<conference xmlns=']]>&namespace;<![CDATA['/>
]]></example>
</section1>
<section1 topic="Bookmark Notifications">
<p>When a client is sent an event from the Pubsub service for the '&namespace;' node, it MUST check the 'autojoin' attribute if present, and join the room immediately if the attribute is both present and true.</p>
</section1>
<section1 topic="Implementation Notes">
<section2 topic="Differences to XEP-0048">
<ul>
<li>The conference element does not contain the jid - this is present only in the item id.</li>
<li>Each conference element is contained within an item.</li>
<li>The storage MUST be &xep0223;</li>
</ul>
</section2>
<section2 topic="Compatibility">
<p>A server MAY choose to unify the bookmarks from both &xep0049; based and the current &xep0048;.</p>
<section3 topic="Publishing via this specification">
<p>When a client publishes a new item, the server MAY collate all items, casting them into the 'storage:bookmarks' namespace and setting the jid attribute to the item id in each case. When contained within a storage element qualified by the 'storage:bookmarks' namespace, this will be the correct format for both current and previous variants of &xep0048;</p>
</section3>
<section3 topic="Publishing via the old specification">
<p>If a client publishes a replacement list of bookmarks via the older specifications, a server MAY examine the list and update the individual items as required, sending updates or retraction notifications as needed. Servers electing to perform this OPTIONAL behaviour SHOULD NOT send notifications for unchanged items.</p>
</section3>
</section2>
</section1>
<section1 topic='Determining Support' anchor='support'>
<p>This specification relies fully on a number of others. Most particularly, support for this protocol is available if &xep0223; is supported.</p>
</section1>
<section1 topic="Acknowledgements">
<p>The authors would like to note that much of the syntax description was copied exactly from &xep0048; by Rachel Blackman, Peter Millard, and Peter Saint-Andre. Much of the remainder of this specification is based closely on their work.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>The password child element of conference is well known to provide only very weak levels of security; storing it in bookmarks lowers this security still further.</p>
</section1>
</xep>

282
inbox/colors.xml
View File

@ -1,282 +0,0 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
<!ENTITY rgblind "<em>Red/Green-Blindness</em>">
<!ENTITY bblind "<em>Blue-Blindness</em>">
<!ENTITY cvd "Color Vision Deficiency">
<!ENTITY cvds "Color Vision Deficiencies">
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Consistent Color Generation</title>
<abstract>This specification provides a set of algorithms to consistently generate colors given a string. The string can be a nickname, a JID or any other piece of information. All entities adhering to this specification generate the same color for the same string, which provides a consistent user experience across platforms.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies></dependencies>
<supersedes/>
<supersededby/>
<shortname>colors</shortname>
<author>
<firstname>Jonas</firstname>
<surname>Wielicki</surname>
<email>jonas@wielicki.name</email>
<jid>jonas@wielicki.name</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2017-09-14</date>
<initials>jwi</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>Colors provide a valuable visual cue to recognize text. Recognition of colors works much faster than recognition of text. Together with the length and overall shape of a piece of text (such as a nickname), a color provides a decent amount of entropy to distinguish a reasonable amount of entities.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>The color generation mechanism should provide the following features:</p>
<ul>
<li>Consistent generation of color across all platforms depending solely on the identifier used as input for the algorithm.</li>
<li>The system should be reasonably fast; it must be possible to, for example, apply it to all roster entries even of very large rosters in reasonable amount of time.</li>
<li>It must be able to provide decent contrast on any background.</li>
<li>The implementation should be stateless and not be complex.</li>
<li>A fallback path for users with common types of &cvds; must be provided.</li>
<li>A fallback path for systems which can only use colors from a restricted palette must be provided.</li>
</ul>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Generating a color' anchor='usecase-textcolor'>
<p>To generate a color from a string of text, the follownig algorithms are applied in order:</p>
<ol>
<li><link url='#algorithm-angle'>Generate an angle in the CbCr plane from the text</link>.</li>
<li>If enabled, <link url='#algorithm-cvd'>apply configured corrections for &cvds;</link>.</li>
<li><link url='#algorithm-cbcr'>Convert the angle to a CbCr pair</link>.</li>
<li>If the output device only supports a small palette of colors, <link url='#algorithm-mappalette'>map the CbCr value to the closest palette color</link>.</li>
<li>If the output device supports RGB output, <link url='#algorithm-rgb'>convert the CbCr pair to an RGB triple</link>.</li>
</ol>
</section2>
<section2 topic='Adding colors to participants of a conversation' anchor='usecase-nickcolor'>
<p>Implementations may colorize the participants of a conversation with an individual color to make them easier to distinguish.</p>
<p>In such cases, the color SHOULD be generated as described in the <link url='#usecase-textcolor'>Generating a color</link> section. The input used SHOULD be, in descending order of preference, (a) the name assigned in the roster, (b) the nickname from the conversation, (c) the bare JID.</p>
</section2>
<section2 topic='Auto-Generating Avatars' anchor='usecase-avatar'>
<p>Implementations may want to show a picture in connection with a contact even if the contact does not have an avatar defined (e.g. via &xep0084;).</p>
<p>In such cases, auto-generating an avatar SHOULD happen as follows:</p>
<ol>
<li>Obtain a name for the contact, in descending order of preference, (a) from the roster, (b) by using the nickname from the conversation, (c) by using the bare JID.</li>
<li>Generate a color as described in the <link url='#usecase-textcolor'>Generating a color</link> section.</li>
<li>Fill an implementation-defined background shape with that color.</li>
<li>Render the first character of the name in white or black centered on the square.</li>
</ol>
</section2>
</section1>
<section1 topic='Business Rules' anchor='rules'>
<ul>
<li>Implementations MUST allow the user to turn off any colorization completely.</li>
<li>Implementations MUST implement the &cvd; profiles and MUST allow the user to choose any of these profiles or to disable the correction.</li>
<li>Implementations MUST NOT share the &cvd; correction settings with other entities.</li>
</ul>
</section1>
<section1 topic='Algorithms' anchor='algorithm'>
<section2 topic='Angle generation' anchor='algorithm-angle'>
<p>Input: An identifier, encoded as octets of UTF-8 (&rfc3269;).</p>
<p>Output: Angle in the CbCr plane.</p>
<p>Note: The goal of this algorithm is to convert arbitrary text into a scalar value which can then be used to calculate a color. As it happens, the CbCr plane of the YCbCr space determines the color (while Y merely defines the lightness); thus, an angle in the CbCr plane serves as a good scalar value to select a color.</p>
<ol>
<li>Run the input through CRC32 as defined by zlib (TODO: add citation).</li>
<li>Take the lower 16 bits and XOR them with the upper 16 bits.</li>
<li>Divide the value by 65535 (use float division) and multiply it by 2&#960; (two Pi).</li>
</ol>
</section2>
<section2 topic='Corrections for &cvds;' anchor='algorithm-cvd'>
<p>Input: Angle in the CbCr plane.</p>
<p>Output: Angle in the CbCr plane.</p>
<p>Note: This algorithm will re-map the angle to map it away from ranges which can not be distinguished by people with the respective &cvds;.</p>
<section3 topic='Red/Green-blindness' anchor='algorithm-cvd-rg'>
<p>Divide the angle by two.</p>
</section3>
<section3 topic='Blue-blindness' anchor='algorithm-cvd-b'>
<p>Divide the angle by two and add &#960;/2 (half Pi).</p>
</section3>
</section2>
<section2 topic='CbCr generation' anchor='algorithm-cbcr'>
<p>Input: Angle in the CbCr plane, from the previous algorithm.</p>
<p>Output: Values for Cb and Cr in the YCbCr BT.601 color space in the range from -0.5 to 0.5.</p>
<p>Form a vector from the angle and project it to edges of a quad in 2D space with edge length 1 around (0, 0). The resulting coordinates are Cb and Cr:</p>
<code><![CDATA[float cr = sin(angle);
float cb = cos(angle);
float factor;
if (abs(cr) > abs(cb)) {
factor = 0.5 / abs(cr);
} else {
factor = 0.5 / abs(cb);
}
cb = cb * factor;
cr = cr * factor;
]]></code>
</section2>
<section2 topic='CbCr to RGB' anchor='algorithm-rgb'>
<p>Input: Values for Cb and Cr in the YCbCr BT.601 color space in the range from -0.5 to 0.5; Value for Y.</p>
<p>Output: Values for Red (R), Green (G) and Blue (B) in the RGB color space in the range from 0 to 1.</p>
<p>Note: The recommended value for Y is 0.732. See <link url='#impl-gamma'>Gamma Correction</link> for a discussion on the choice of Y.</p>
<ol>
<li>Calculate r, g and b according to BT.601:<code><![CDATA[float r = 2*(1 - KR)*cr + y;
float b = 2*(1 - KB)*cb + y;
float g = (y - KR*r - KB*b)/KG;
]]></code></li>
<li>Clip the values of r, g and b to the range from 0 to 1.</li>
</ol>
</section2>
<section2 topic='Adapting the Color for specific Background Colors' anchor='algorithm-bg'>
<p>Input: RGB values for the color to adapt (Ri, Gi, Bi) and for the background color to adapt to (Rb, Gb, Bb), in the range from 0 to 1 each.</p>
<p>Output: Values for Red (Rc), Green (Gc) and Blue (Bc) in the RGB color space in the range from 0 to 1.</p>
<ol>
<li>Invert the background color by subtracting the individual channels from 1 each:
<code><![CDATA[
rb = 1-rb;
gb = 1-gb;
bb = 1-bb;]]></code></li>
<li>Mix the inverted background with the color to adapt, using a mixing factor of 0.2:
<code><![CDATA[
rc = 0.2*rb + 0.8*ri;
gc = 0.2*gb + 0.8*gi;
bc = 0.2*bb + 0.8*bi;]]></code></li>
</ol>
</section2>
<section2 topic='RGB to YCbCr' anchor='algorithm-rgb2cbcr'>
<p>Input: Values for Red (R), Green (G) and Blue (B) in the RGB color space in the range from 0 to 1.</p>
<p>Output: Values for Cb and Cr in the YCbCr BT.601 color space in the range from -0.5 to 0.5; Value for Y.</p>
<p>Calculate Y, Cb and Cr according to BT.601:</p>
<code><![CDATA[
y = KR*r + (1 - KR - KB)*g + KB*b;
cb = (b - y) / (1 - KB) / 2
cr = (r - y) / (1 - KR) / 2
]]></code>
</section2>
<section2 topic='Conversion of an RGB color palette to a CbCr color palette' anchor='algorithm-genpalette'>
<p>Input: A set of RGB colors (each component from 0 to 1).</p>
<p>Output: A mapping from CbCr pairs (each component from -0.5 to 0.5) to RGB colors.</p>
<p>Note: when the algorithm finishes, the mapping maps CbCr values (rounded to two decimal places) to the R, G, B triples which come closest to the desired color and lightness.</p>
<ol>
<li>Create an empty mapping M which maps from pairs of CbCr values to quadruples of Y, R, G and B.</li>
<li>For each color R, G, B from the input palette:
<ol>
<li>Calculate Y, Cb and Cr from R, G, B as described in <link url='#algorithm-rgb2cbcr'>RGB to YCbCr</link>.</li>
<li>Round Cb and Cr to two decimal places as Cb' and Cr'.</li>
<li>If the (Cb', Cr') pair is not in the mapping M yet, or if the Y value of the existing entry is farther away from 0.732 than the new Y value, put the Y, R, G, and B values as value for the (Cb', Cr') pair into the mapping.</li>
</ol>
</li>
<li>Strip the Y values from the values of mapping M.</li>
<li>Return M as the result of the algorithm.</li>
</ol>
</section2>
<section2 topic='Mapping of a CbCr color to closest palette color' anchor='algorithm-mappalette'>
<p>Input: A set of colors (the palette) as tuples of Cbp and Crp and a color to map to the closest palette color as Cb and Cr value.</p>
<p>Output: A palette color as Cbr and Crr values.</p>
<ol>
<li>For each color as pair Cbp, Crp in the palette, calculate the distance metric: <code>D = sqrt((Cbp-Cb)*(Cbp-Cb) + (Crp-Cr)*(Crp-Cr))</code>.</li>
<li>Pick the palette color Cbp, Crp with the smallest distance metric D as result color Cbr, Crr.</li>
</ol>
<p>Note: the distance metric is simply the euclidian distance in the CbCr plane.</p>
</section2>
<section2 topic='Test Vectors' anchor='algorithm-testvector'>
<p>This section holds test vectors for the different configurations. The test vectors are provided as Comma Separated Values. Strings are enclosed by single quotes (&apos;). The first line contains a header. Each row contains, in that order, the original text, the text encoded as UTF-8 as hexadecimal octets, and the Cb, Cr, Red, Green, and Blue values.</p>
<section3 topic='No &cvd; correction' anchor='algorithm-testvector-no-cvd'>
<code><![CDATA[
text,hextext,angle,cb,cr,r,g,b
'Romeo','526f6d656f',2.099189,-0.291880,0.500000,1.000,0.475,0.215
'juliet@capulet.lit','6a756c69657440636170756c65742e6c6974',5.830846,0.500000,-0.242972,0.391,0.733,1.000
'😺','f09f98ba',4.312757,-0.211180,-0.500000,0.031,1.000,0.358]]></code>
</section3>
<section3 topic='With Red/Green-blindess correction' anchor='algorithm-testvector-cvd-redgreen'>
<code><![CDATA[text,hextext,angle,cb,cr,r,g,b
'Romeo','526f6d656f',1.049594,0.287079,0.500000,1.000,0.276,1.000
'juliet@capulet.lit','6a756c69657440636170756c65742e6c6974',2.915423,-0.500000,0.115053,0.893,0.822,0.000
'😺','f09f98ba',2.156378,-0.331588,0.500000,1.000,0.489,0.144]]></code>
</section3>
<section3 topic='With Blue-blindess correction' anchor='algorithm-testvector-cvd-blue'>
<code><![CDATA[
text,hextext,angle,cb,cr,r,g,b
'Romeo','526f6d656f',2.620391,-0.500000,0.287079,1.000,0.699,0.000
'juliet@capulet.lit','6a756c69657440636170756c65742e6c6974',4.486219,-0.115053,-0.500000,0.031,1.000,0.528
'😺','f09f98ba',3.727175,-0.500000,-0.331588,0.267,1.000,0.000]]></code>
</section3>
<section3 topic='Mapping to 216 color palette' anchor='algorithm-testvector-palette'>
<p>The used palette can be generated by sampling the RGB cube evenly with six samples on each axis (resulting in 216 colors). The resulting palette is commonly known as the palette of so-called "Web Safe" colors.</p>
<section4 topic='No &cvd; correction' anchor='algorithm-testvector-palette-no-cvd'>
<code><![CDATA[
text,hextext,angle,cb,cr,r,g,b
'Romeo','526f6d656f',2.099189,-0.291880,0.500000,1.000,0.200,0.000
'juliet@capulet.lit','6a756c69657440636170756c65742e6c6974',5.830846,0.500000,-0.242972,0.000,0.200,1.000
'😺','f09f98ba',4.312757,-0.211180,-0.500000,0.000,1.000,0.200]]></code>
</section4>
<section4 topic='With Red/Green-blindess correction' anchor='algorithm-testvector-palette-cvd-redgreen'>
<code><![CDATA[
text,hextext,angle,cb,cr,r,g,b
'Romeo','526f6d656f',1.049594,0.287079,0.500000,1.000,0.000,0.800
'juliet@capulet.lit','6a756c69657440636170756c65742e6c6974',2.915423,-0.500000,0.115053,1.000,1.000,0.000
'😺','f09f98ba',2.156378,-0.331588,0.500000,1.000,0.200,0.000]]></code>
</section4>
<section4 topic='With Blue-blindess correction' anchor='algorithm-testvector-palette-cvd-blue'>
<code><![CDATA[
text,hextext,angle,cb,cr,r,g,b
'Romeo','526f6d656f',2.620391,-0.500000,0.287079,1.000,0.600,0.000
'juliet@capulet.lit','6a756c69657440636170756c65742e6c6974',4.486219,-0.115053,-0.500000,0.000,1.000,0.400
'😺','f09f98ba',3.727175,-0.500000,-0.331588,0.200,1.000,0.000]]></code>
</section4>
</section3>
</section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<section2 topic='Gamma Correction' anchor='impl-gamma'>
<p>An implementation may choose a different value for Y depending on whether the sink for the R, G and B values expects Gamma Encoded or Gamma Decoded values. The recommended default of 0.732 is 0.5 to the power of 0.45, that is, a Gamma Encoded 0.5.</p>
<p>Modifications to Y SHOULD NOT be used to correct for bright/dark backgrounds. Implementations SHOULD instead use the algorithm described in <link url='#algorithm-bg'>Adapting the Color for specific Background Colors</link> for that.</p>
</section2>
</section1>
<section1 topic='Accessibility Considerations' anchor='access'>
<p>As outlined above, implementations MUST offer the &rgblind; and &bblind; corrections as defined in the <link url='#algorithm-cvd'>Corrections for &cvds;</link> section. Users MUST be allowed to choose between:</p>
<ul>
<li>disabling all corrections (skip the Corrections for &cvds; step entirely),</li>
<li>applying one of the &cvd; correction profiles and</li>
<li>disabling colorization altogether.</li>
</ul>
<p>The last option is important for users with monochromatic view.</p>
<p>Some sources on the internet indicate that people with &cvds; may profit from having larger areas of color to be able to recognize them. This should be taken into consideration when selecting font weights and line widths for colored parts.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>This specification extracts a bit more information from an entity and shows it alongside the existing information to the user. As the algorithm is likely to produce different colors for look-alikes (see &xep0165; for examples) in JIDs, it may add additional protection against attacks based on those.</p>
<p>Due to the limited set of distinguishable colors, possible &cvds; and/or use of palettes, entities MUST NOT rely on colors being unique in any context.</p>
</section1>
<section1 topic='Design Considerations' anchor='design'>
<p>This section provides an overview of design considerations made while writing this specification. It shows alternatives which have been considered, and eventually rejected.</p>
<section2 topic='Other variants of the YCbCr color space' anchor='design-other-ycbcr'>
<p>The other common YCbCr variants, BT.709 and BT.2020, do not achieve a brightness across the color space as uniform as BT.601 does. Adapting the Y value for uniform luminosity across the range for CbCr would have complicated the algorithm with little or no gain.</p>
</section2>
<section2 topic='Hue-Saturation-Value/Lightness color space' anchor='design-hsv'>
<p>The HSV and HSL color spaces fail to provide uniform luminosity with fixed value/lightness and saturation parameters. Adapting those parameters for uniform luminosity across the hue range would have complicated the algorithm with litte to no gain.</p>
</section2>
<section2 topic='Palette-based and context-aware coloring' anchor='design-context'>
<p>Given a fixed-size and finite palette of colors, it would be possible to ensure that, until the number of entities to color exceeds the number of colors, no color collisions happen.</p>
<p>There are issues with this approach when the set of entities is dynamic. In such cases, it is possible that an entity changes its associated color (for example by re-joining a colored group chat), which defeats the original purpose.</p>
<p>In addition, more state needs to be taken into account, increasing the complexity of choosing a color.</p>
</section2>
<section2 topic='Choice of mixing function in angle generation' anchor='design-mixing'>
<p>This specification needs to collapse an arbitrarily long string into just a few bits (the angle in the CbCr plane). To do so, a CRC32 sum is used.</p>
<p>An alternative, which may yield better distribution of colors, would have been to use a cryptographic hash function. However, the performance and implementation cost for a cryptographic hash function is considerable compared with a simple CRC32, especially on small (less than 1 kiB) inputs.</p>
</section2>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;. </p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<p>This document requires no interaction with the &REGISTRAR;. </p>
</section1>
<section1 topic='Acknowledgements' anchor='acknowledgements'>
<p>Thanks to Daniel Gultsch, Georg Lukas, and Tobias Markmann.</p>
</section1>
</xep>

133
inbox/jet-omemo.xml
View File

@ -1,133 +0,0 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY secret "&lt;secret/&gt;">
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Jingle Encrypted Transports - OMEMO</title>
<abstract>Extension for JET introducing OMEMO End-to-End Encrypted Jingle Transports.</abstract>
&LEGALNOTICE;
<number>XXXX</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XEP-0391</spec>
<spec>XEP-0234</spec>
<spec>XEP-0384</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>jet-omemo</shortname>
<schemaloc>
<ns>jingle</ns>
<url>http://xmpp.org/schemas/jingle.xsd</url>
</schemaloc>
<schemaloc>
<ns>jingle:errors</ns>
<url>http://xmpp.org/schemas/jingle-errors.xsd</url>
</schemaloc>
<registry/>
<discuss>jingle</discuss>
<author>
<firstname>Paul</firstname>
<surname>Schaub</surname>
<email>vanitasvitae@riseup.net</email>
<jid>vanitasvitae@jabberhead.tk</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2017-10-06</date>
<initials>vv</initials>
<remark><p>First draft</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>&xep0391; can be used to utilize different end-to-end encryption methods to secure Jingle Transports, eg. in the context of &xep0234;. This document aims to extend &xep0391; to allow the use of OMEMO encryption with Jingle transports. To achieve this goal, this protocol extension makes use of OMEMOs <link url='https://xmpp.org/extensions/xep-0384.html#usecases-keysend'>KeyTransportElements</link>.</p>
</section1>
<section1 topic='Mappings' anchor='mappings'>
<p>Conveniently the OMEMO protocol already provides a way to transport key material to another entity. So called KeyTransportElements are basically normal OMEMO MessageElements, but without a payload, so the contained key can be used for something else (See Section 4.6 of <cite>XEP-0384</cite>). This extension uses the key encrypted in the KeyTransportMessages &lt;key&gt; attribute and initialization vector from the &lt;iv&gt; attribute to secure Jingle Transports. The key corresponds to the <cite>Transport Key</cite> of <cite>XEP-0391</cite>, while the iv corresponds to the <cite>Initialization Vector</cite>. The KeyTransportMessage is the equivalent to the <cite>Envelope Element</cite>. Note that within the Envelope Element, the Transport Key is encrypted with the OMEMO ratchet.</p>
</section1>
<section1 topic='Limitaions' anchor='limitations'>
<p>Unfortunately &xep0384; determines the type of the transported key to be AES-128-GCM-NoPadding, so no other configuration can be used in the context of this extension.</p>
<p>Since OMEMO deviceIds are not bound to XMPP resources, the initiator MUST encrypt the Transport Key for every device of the recipient.</p>
</section1>
<section1 topic='Key Transport' anchor='transport'>
<p>In order to transport a key to the responder, the initiator creates a fresh AES-128-GCM-NoPadding Transport Key and Initialization Vector and generates an OMEMO KeyTransportElement from it as described in <cite>XEP-0384</cite>. This is then added as a child of the JET &lt;security&gt; element. The 'cipher' attribute MUST be set to 'aes-128-gcm-nopadding:0' (see the <link url='https://xmpp.org/extensions/xep-0391.html#ciphers'>ciphers</link> section of <cite>XEP-0391</cite>). The value of the 'type' attribute must be set to the namespace of the used version of <cite>XEP-0384</cite> &VNOTE;.</p>
<p></p>
<example caption="Romeo initiates an OMEMO encrypted file offer"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='nzu25s8'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-initiate'
initiator='romeo@montague.example/dr4hcr0st3lup4c'
sid='851ba2'>
<content creator='initiator' name='a-file-offer' senders='initiator'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<date>1969-07-21T02:56:15Z</date>
<desc>This is a test. If this were a real file...</desc>
<media-type>text/plain</media-type>
<name>test.txt</name>
<range/>
<size>6144</size>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
mode='tcp'
sid='vj3hs98y'>
<candidate cid='hft54dqy'
host='192.168.4.1'
jid='romeo@montague.example/dr4hcr0st3lup4c'
port='5086'
priority='8257636'
type='direct'/>
</transport>
<security xmlns='urn:xmpp:jingle:jet:0'
name='a-file-offer'
cipher='urn:xmpp:ciphers:aes-128-gcm-nopadding'
type='eu.siacs.conversations.axolotl'>
<encrypted xmlns='eu.siacs.conversations.axolotl'>
<header sid='27183'>
<key rid='31415'>BASE64ENCODED...</key>
<key prekey="true" rid='12321'>BASE64ENCODED...</key>
<!-- ... -->
<iv>BASE64ENCODED...</iv>
</header>
</encrypted>
</security>
</content>
</jingle>
</iq>]]></example>
<p>The recipient decrypts the OMEMO KeyTransportElement to retrieve the Transport Secret. Transport Key and Initialization Vector are later used to encrypt/decrypt data as described in &xep0391;.</p>
</section1>
<section1 topic='Determining Support' anchor='support'>
<p>To advertise its support for JET-OMEMO, when replying to service discovery information ("disco#info") requests an entity MUST return URNs for any version of this extension, as well as of the JET extension that the entity supports -- e.g., "urn:xmpp:jingle:jet-omemo:0" for this version, or "urn:xmpp:jingle:jet:0" for &xep0391; &VNOTE;.</p>
<example caption="Service discovery information request"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='uw72g176'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]></example>
<example caption="Service discovery information response"><![CDATA[
<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
id='uw72g176'
to='romeo@montague.example/dr4hcr0st3lup4c'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='urn:xmpp:jingle:jet:0'/>
<feature var='urn:xmpp:jingle:jet-omemo:0'/>
</query>
</iq>]]></example>
<p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
</section1>
</xep>

302
inbox/jet.xml
View File

@ -1,302 +0,0 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY secret "&lt;secret/&gt;">
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Jingle Encrypted Transports</title>
<abstract>This specification defines a method that allows to use established encryption schemes for end-to-end encryption of Jingle transports.</abstract>
&LEGALNOTICE;
<number>XXXX</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XEP-0234</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>jet</shortname>
<schemaloc>
<ns>jingle</ns>
<url>http://xmpp.org/schemas/jingle.xsd</url>
</schemaloc>
<schemaloc>
<ns>jingle:errors</ns>
<url>http://xmpp.org/schemas/jingle-errors.xsd</url>
</schemaloc>
<registry/>
<discuss>jingle</discuss>
<author>
<firstname>Paul</firstname>
<surname>Schaub</surname>
<email>vanitasvitae@riseup.net</email>
<jid>vanitasvitae@jabberhead.tk</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2017-06-12</date>
<initials>vv</initials>
<remark><p>First draft</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>Jingle Encrypted Transports (JET) strives to provide a modular and easily extensible way to wrap Jingle Transports in an additional end-to-end encryption layer. The focus of this specification lays on being modular. It should be possible to extend existing Jingle use scenarios with end-to-end encryption by simply adding a JET element to the negotiation.</p>
</section1>
<section1 topic='Terminology' anchor='terminology'>
<p>JET uses multiple encryption layers, so it is necessary to declare a distinct denomination for the different keys involved.</p>
<table caption='Denomination of keys used in the protocol'>
<tr>
<th>Designation</th>
<th>Abbrevation</th>
<th>Usage</th>
</tr>
<tr>
<td>Transport Key</td>
<td>TK</td>
<td>(Symmetric) key that is used to encrypt/decrypt the bytestreams sent/received through Jingle transports. This key encrypts the data two entities want to exchange. Examples for TK can be found under <link url='#ciphers'>"Ciphers"</link>.</td>
</tr>
<tr>
<td>Initialization Vector</td>
<td>IV</td>
<td>Initialization vector that is used together with TK.</td>
</tr>
<tr>
<td>Transport Secret</td>
<td>TS</td>
<td>Serialization of TK and TI.</td>
</tr>
<tr>
<td>Envelope Element</td>
<td>EE</td>
<td>Output element of an established end-to-end encryption method when encrypting TS.</td>
</tr>
</table>
</section1>
<section1 topic='Principle' anchor='principle'>
<p>Lets assume Romeo wants to initiate an encrypted Jingle session with Juliet. Prior to the Jingle session initiation, an already existing, established and (ideally) authenticated end-to-end encryption session between Romeo and Juliet MUST exist. This session is needed to transfer the Transport Secret from Romeo to Juliet.</p>
<p>When this precondition is met, Romeo initially generates a transport key (TK) and associated initialization vector (IV). These will later be used by the sender to encrypt, and respectively by the recipient to decrypt data that is exchanged. This protocol defines a set of usable <link url='#ciphers'>ciphers</link> from which Romeo might choose. TK and IV are serialized to create the transport secret (TS).</p>
<p>Next Romeo uses her established encryption session with Juliet to encrypt TS. The resulting envelope element (EE) will be part of the Jingle session initiation as child of the JET &secret; element.</p>
<p>When Juliet receives Romeos session request, she decrypts EE to retrieve TS, from which she can deserialize TK and IV. Now she and Romeo can go on with the session negotiation. Once the session is established, data can be encrypted and exchanged. Both parties MUST keep a copy of TS in cache until the Jingle session is ended.</p>
</section1>
<section1 topic='Encrypted Jingle File Transfer using JET' anchor='jft'>
<p>&xep0234; has the disadvantage, that transmitted files are not encrypted (aside from regular TLS transport encryption), which means that intermediate nodes like XMPP/proxy server(s) have access to the transferred data. Considering that end-to-end encryption becomes more and more important to protect free speech and personal expression, this is a major flaw that needs to be addressed.</p>
<p>In order to initiate an encrypted file transfer, the initiator includes a JET &secret; in the Jingle file transfer request.</p>
<section2 topic='File Offer'>
<p>In this scenario Romeo wants to send an encrypted text file over to Juliet. First, he generates a fresh AES-256 transport key and IV. TK and IV are serialized into TS which is then encrypted using Romeos end-to-end-encryption session with Juliet.</p>
<p>The resulting envelope element (EE) is sent as part of the security element along with the rest of the jingle stanza over to Juliet.</p>
<example caption="Romeo initiates an encrypted file offer"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='nzu25s8'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-initiate'
initiator='romeo@montague.example/dr4hcr0st3lup4c'
sid='851ba2'>
<content creator='initiator' name='a-file-offer' senders='initiator'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<date>1969-07-21T02:56:15Z</date>
<desc>This is a test. If this were a real file...</desc>
<media-type>text/plain</media-type>
<name>test.txt</name>
<range/>
<size>6144</size>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
mode='tcp'
sid='vj3hs98y'>
<candidate cid='hft54dqy'
host='192.168.4.1'
jid='romeo@montague.example/dr4hcr0st3lup4c'
port='5086'
priority='8257636'
type='direct'/>
</transport>
<security xmlns='urn:xmpp:jingle:jet:0'
name='a-file-offer'
cipher='urn:xmpp:ciphers:aes-256-gcm-nopadding'
type='urn:xmpp:encryption:stub:0'>
<encrypted xmlns='urn:xmpp:encryption:stub:0'>
<payload>BASE64-ENCODED-ENCRYPTED-SECRET</payload>
</encrypted>
</security>
</content>
</jingle>
</iq>]]></example>
<p>Juliet decrypts the envelope element (EE) using her session with Romeo to retrieve TS from which she deserializes TK and IV. Both Juliet and Romeo then carry on with the session negotiation as described in &xep0234;. Before Romeo starts transmitting the file, he encrypts it using TK and IV. He then transmitts the encrypted file over to Juliet.</p>
<p>When Juliet received the file, she uses the TK and IV to decrypt the received file.</p>
</section2>
<section2 topic='File Request'>
<p>Juliet might want to request a file transfer from Romeo. This can be the case, when Romeo hosts the file. In order to do so, she sends generates TK and IV, creates TS from those and encrypts TS with an encryption method of her choice to get EE. TK and IV will be used by Romeo to encrypt the requested file before sending it to Juliet.</p>
<example caption="Juliet initiates an encrypted file request"><![CDATA[
<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
id='wsn361c3'
to='romeo@montague.example/dr4hcr0st3lup4c'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-initiate'
initiator='juliet@capulet.example/yn0cl4bnw0yr3vym'
sid='uj3b2'>
<content creator='initiator' name='a-file-request' senders='responder'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
mode='tcp'
sid='xig361fj'>
<candidate cid='ht567dq'
host='192.169.1.10'
jid='juliet@capulet.example/yn0cl4bnw0yr3vym'
port='6539'
priority='8257636'
type='direct'/>
</transport>
<security xmlns='urn:xmpp:jingle:jet:0'
name='a-file-request'
cipher='urn:xmpp:ciphers:aes-256-gcm-nopadding'
type='urn:xmpp:encryption:stub:0'>
<encrypted xmlns='urn:xmpp:encryption:stub:0'>
<payload>BASE64-ENCODED-ENCRYPTED-SECRET</payload>
</encrypted>
</security>
</content>
</jingle>
</iq>]]></example>
</section2>
<section2 topic='Encrypted Ranged Transfers'>
<p>&xep0234; defines a way for parties to request ranged transfers. This can be used to resume interrupted transfers etc. In case of an interrupted transfer, the receiving party might be able to decrypt parts of the received file. When requesting a resumption of the transfer, the recipient therefore can use the index of the last successfully decrypted byte of the file as offset in the ranged transfer. Since a resumed transfer takes place in a new session, the old transport secret might no longer be available to either party. For that reason the receiver creates a new TS for the session-initiation. The sending party then encrypts and sends only the requested parts of the file.</p>
<example caption="Romeo requests the resumption of an interrupted transfer using a fresh transport secret"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='wsn361c3'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-initiate'
initiator='romeo@montague.example/dr4hcr0st3lup4c'
sid='uj3b2'>
<content creator='initiator' name='restart' senders='responder'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<range offset='270336'/>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
mode='tcp'
sid='vj3hs98y'>
<candidate cid='hft54dqy'
host='192.168.4.1'
jid='romeo@montague.example/dr4hcr0st3lup4c'
port='5086'
priority='8257636'
type='direct'/>
<candidate cid='hutr46fe'
host='24.24.24.1'
jid='romeo@montague.example/dr4hcr0st3lup4c'
port='5087'
priority='8258636'
type='direct'/>
</transport>
<security xmlns='urn:xmpp:jingle:jet:0'
name='restart'
cipher='urn:xmpp:ciphers:aes-256-gcm-nopadding'
type='urn:xmpp:encryption:stub:0'>
<encrypted xmlns='urn:xmpp:encryption:stub:0'>
<payload>BASE64-ENCODED-ENCRYPTED-SECRET</payload>
</encrypted>
</security>
</content>
</jingle>
</iq>]]></example>
</section2>
</section1>
<section1 topic='Ciphers' anchor='ciphers'>
<p>In order to encrypt the transported bytestream, the initiator must transmit a cipher key to the responder. There are multiple options available:</p>
<table caption='Available ciphers, configurations and their namespaces'>
<tr>
<th>Namespace</th>
<th>Type</th>
<th>Length (bits)</th>
<th>Parameters</th>
<th>Serialization</th>
</tr>
<tr>
<td>urn:xmpp:ciphers:aes-128-gcm-nopadding:0</td>
<td>AES</td>
<td>128</td>
<td>GCM/NoPadding</td>
<td>128BitKey::96BitIV</td>
</tr>
<tr>
<td>urn:xmpp:ciphers:aes-256-gcm-nopadding:0</td>
<td>AES</td>
<td>256</td>
<td>GCM/NoPadding</td>
<td>256BitKey::96BitIV</td>
</tr>
</table>
<p>The column 'serialization' describes, how the key and iv are serialized. "::" means plain concatenation of byte arrays.</p>
</section1>
<section1 topic='Determining Support' anchor='support'>
<p>To advertise its support for the Jingle Encrypted Transports, when replying to service discovery information ("disco#info") requests an entity MUST return URNs for any version, or extension of this protocol that the entity supports -- e.g., "urn:xmpp:jingle:jet:0" for this version, or "urn:xmpp:jingle:jet-stub:0" for a stub encryption method &VNOTE;.</p>
<example caption="Service discovery information request"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='uw72g176'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]></example>
<example caption="Service discovery information response"><![CDATA[
<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
id='uw72g176'
to='romeo@montague.example/dr4hcr0st3lup4c'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='urn:xmpp:jingle:jet:0'/>
<feature var='urn:xmpp:jingle:jet-stub:0'/>
</query>
</iq>]]></example>
<p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>The initiator SHOULD NOT use the generated key TK as IV, but instead generate a seperate random IV.</p>
<p>Instead of falling back to unencrypted transfer in case something goes wrong, implementations MUST instead abort the Jingle session, informing the user.</p>
<p>IMPORTANT: This approach does not deal with metadata. In case of &xep0234;, an attacker with access to the sent stanzas can for example still see the name of the file and other information included in the &lt;file/&gt; element.</p>
<p>The responder MUST check, whether the envelope element belongs to the initiator to prevent MitM attacks</p>
</section1>
<section1 topic='Open Questions'>
<p>This is only a rough draft and there is still a ton of questions left to be answered. Here is a small non-exhaustive list of things I can think of:</p>
<ul>
<li>How exactly are interrupted transfers resumed? How (long) are keys/IVs cached?</li>
<li>May it be desirable to split data into chunks?</li>
<li>Please add to this list :)</li>
</ul>
</section1>
<section1 topic='TODO'>
<ul>
<li>Split up the protocol into encryption method specific sub protocols (jet-omemo, jet-ox...)</li>
</ul>
</section1>
</xep>

436
inbox/user-invite.xml
View File

@ -1,436 +0,0 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Easy User Onboarding</title>
<abstract>This document defines a protocol and URI scheme for user invitation in order to allow a third party to register on a server. The goal of this is to make onboarding for XMPP IM newcomers as easy as possible.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0001</spec>
<spec>XEP-0050</spec>
<spec>XEP-0082</spec>
<spec>XEP-0077</spec>
<spec>XEP-0147</spec>
<spec>XEP-0379</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>N/A</shortname>
<author>
<firstname>Marc</firstname>
<surname>Schink</surname>
</author>
<revision>
<version>0.0.1</version>
<date>2018-01-10</date>
<initials>ms</initials>
<remark><p>First submission.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>Romeo is an active XMPP IM (Instant Messaging) user or the operator of
an XMPP server. He convinces Juliet (who may not have an XMPP account yet)
to install a client but she may still need to choose an XMPP server,
create an account, and add Romeo as a contact.
This specification defines two ways for Romeo to simplify this process for Juliet:</p>
<section2 topic='User Invitation'>
<p>If Romeo is an XMPP user, he can create an out-of-band link (URI)
which allows Juliet to:</p>
<ol>
<li>Download an XMPP client (if needed).</li>
<li>Optionally register an account with Romeo's server (if permitted by
the server rules), or with a public server.</li>
<li>Establish a mutual presence subscription between Romeo and Juliet.</li>
</ol>
<p>The process is designed to automatically skip steps that Juliet already
completed, to make the overall experience as smooth as possible.</p>
</section2>
<section2 topic='Account Creation'>
<p>If Romeo is an administrator of an XMPP server, he can create an
out-of-band link (URI) which allows Juliet to:</p>
<ol>
<li>Download an XMPP client (if needed).</li>
<li>Register an account on Romeo's server with a user name defined by
Romeo and a password not known to Romeo.</li>
<li>Establish a mutual presence subscription between Romeo and Juliet.</li>
</ol>
</section2>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>This specification makes use of XMPP URIs. The basic URI scheme for XMPP
is defined in &rfc5122; and extended in &xep0147; and &xep0379;.
Furthermore, this heavily builds upon the blocks provided in
<cite>XEP-0379</cite> for landing page and roster subscription.
</p>
<p>
To create out-of-band invitation links, Romeo's server needs to implement
the &xep0050; commands specified in the following section, and his client
must be able to execute them.
</p>
<p>
Furthermore, Romeo's server SHOULD provide a HTTPS service hosting the
landing page.
</p>
</section1>
<section1 topic='Discovery' anchor='discover'>
<p>Romeo can query his server for the availability of "User Invitation" and
"Account Creation" commands:</p>
<example caption="Discover available ad-hoc commands"><![CDATA[
<iq type='get' from='romeo@example.com' to='example.com' id='disco'>
<query xmlns='http://jabber.org/protocol/disco#items'
node='http://jabber.org/protocol/commands'/>
</iq>
]]></example>
<p>TODO: use appropriate node namespace.</p>
<example caption="Discovery result for available ad-hoc commands"><![CDATA[
<iq type='result' to='romeo@example.com' from='example.com' id='disco'>
<query xmlns='http://jabber.org/protocol/disco#items'
node='http://jabber.org/protocol/commands'>
<item jid='example.com'
node='invite'
name='Invite user'/>
<item jid='example.com'
node='create-account'
name='Create account'/>
</query>
</iq>
]]></example>
<p>When performing the account creation, Juliet's client needs to ensure
that the server supports the extended IBR protocol with a &lt;preauth&gt;
token: TODO</p>
</section1>
<section1 topic='Glossary' anchor='glossary'>
<p>OPTIONAL.</p>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Creating a User Invitation' anchor='create-invitation'>
<p>A user can execute the 'invite' command to obtain a new invitation link
with a unique invitation token.</p>
<example caption="Exceute user invitation command"><![CDATA[
<iq type='set' from='romeo@example.com' to='example.com' id='exec1'>
<command xmlns='http://jabber.org/protocol/commands'
node='invite'
action='execute'/>
</iq>
]]></example>
<example caption="User invitation finished"><![CDATA[
<iq type='result' to='romeo@example.com' from='example.com' id='exec2'>
<command xmlns='http://jabber.org/protocol/commands'
node='invite'
status='completed'>
<x xmlns='jabber:x:data' type='result'>
<item>
<field var='uri'>
<value>xmpp:inviter@example.com?roster;preauth=TOKEN;ibr=y</value>
</field>
<field var='landing-url'>
<value>https://example.com/invite/#TOKEN</value>
</field>
<field var='expire'>
<value>2017-11-06T02:56:15Z</value>
</field>
</item>
</x>
</command>
</iq>
]]></example>
<p>The token should be unique, sufficiently
long and generated by a strong random number generator.</p>
<p>A server MUST provide the <strong>uri</strong> field which contains an
XMPP URI of the following format:</p>
<code>xmpp:inviter@example.com?roster;preauth=TOKEN;ibr=y</code>
<p>The <strong>ibr</strong> query component in the XMPP URI indicates that
the invitee is allowed to create an account on Romeo's server, using the
'preauth' token.
If the server does not support or allow in-band registration for invited
users, the server MUST omit the <strong>ibr</strong> query component.</p>
<p>Additionally, the server SHOULD provide the <strong>landing-url</strong>
field which contains an HTTPS URL of a web-based landing page as described
in &xep0379; § 3.3. The URL format may differ from the example shown here
depending on where the landing page is hosted.</p>
<p>If the server omits the <strong>landing-page</strong> field, Romeo's
client SHOULD generate an appropriate landing page URL hosted by the
client developer or a trusted third party.</p>
<p>A server MAY provide a field which provides the expiration date of the
generated token. The expiration date MUST conform to the DateTime profile
specified in &xep0082;. If the field is not provided, the token does not
expire.</p>
<p>Romeo's client should provide adequate means to export the
<strong>landing-page</strong> URL, possibly accompanied with a short
description and the <strong>expire</strong> information, so that Romeo can
share it with Juliet by other means than XMPP, like e-mail or a QR code.</p>
</section2>
<section2 topic='Landing Page' anchor='landing-page'>
<p>The landing page that the generated URL points to should correspond to
the format described in <cite>XEP-0379</cite> §3.3, and it needs to
convey the following information:</p>
<ul>
<li>A short text that this is an XMPP invitation from Romeo.</li>
<li>A client recommendation (based on the detected web browser/OS) with download links.</li>
<li>A prominent button that activates the encoded <strong>xmpp:</strong> link.</li>
</ul>
<p>If the landing page is hosted by Romeo's server, the server MAY display
additional information based on the supplied TOKEN value, like the name
of the inviter or validity information.</p>
</section2>
<section2 topic='Redeeming a User Invitation' anchor='redeem-invitation'>
<p>If Juliet does not have an XMPP client installed, she will not be able
to open the <strong>xmpp:</strong> link from the invitation page.
For this case, the landing page needs to indicate that a client must be
installed first, and that the link will not work as intended without.
The automatic installation of an appropriate IM client when a user
clicks on an <strong>xmpp:</strong> is outside of the scope of this
document.</p>
<p>With an XMPP client installed, Juliet can open the
<strong>xmpp:</strong> link and have the client process it
appropriately, as follows:</p>
<section3 topic='Pre-Configured Account' anchor='redeem-preconfigured'>
<p>If Juliet's client is already configured with an account, the default
action for the presented
<strong>xmpp:inviter@example.com?roster;...</strong> URI is to add the
inviter to Juliet's roster. This should be performed as described in
§3.4 of <cite>XEP-0379</cite>, by sending a presence subscription
request containing the 'preauth' token.</p>
<p>If Juliet already has Romeo in her roster, her client should open the
appropriate chat interface instead.</p>
</section3>
<section3 topic='No Configured Account' anchor='redeem-no-account'>
<p>If Juliet's client does not have an XMPP account configured, she
needs to login or register an account first. Therefore, the client
should provide an interface with the following options:</p>
<ul>
<li>Login with an existing XMPP account.</li>
<li>Register an account with Romeo's server (if the URI contains a
<strong>ibr=y</strong> parameter).</li>
<li>Register an account with a public or client-endorsed server.</li>
</ul>
<p>If the <strong>xmpp:</strong> URI provided by Romeo contains the
<strong>ibr=y</strong> parameter, it indicates that the server
supports the <link url="#preauth-ibr">Pre-Authenticated In-Band
Registration</link> defined in this document. If Juliet chooses this
approach, the server will ensure that after the registration, Romeo is
added to her roster with a full presence subscription.</p> <p>If
Juliet chooses to login or register with a different server, her
client must complete the respective process and issue a subscription
request as described in §3.4 of <cite>XEP-0379</cite>.</p>
</section3>
</section2>
<section2 topic='Initiating Account Creation' anchor='account-creation'>
<p>If Romeo is the administrator of an XMPP server, he might want to
ensure that Juliet obtains an account on this server, with a username
defined either by Romeo or by Juliet, and in a way that does not require
the out-of-band communication of user passwords.</p>
<p>TODO: description of overall process steps, design motivation.</p>
<example caption="Exceute account creation command"><![CDATA[
<iq type='set' from='romeo@example.com' to='example.com' id='exec1'>
<command xmlns='http://jabber.org/protocol/commands'
node='create-account'
action='execute'/>
</iq>
]]></example>
<example caption="Service returns form for account creation"><![CDATA[
<iq type='result' to='romeo@example.com' from='example.com' id='exec1'>
<command xmlns='http://jabber.org/protocol/commands'
sessionid='config:20020923T213616Z-700'
node='create-account'
status='executing'>
<actions execute='complete'>
<complete/>
</actions>
<x xmlns='jabber:x:data' type='form'>
<field var='username' label='Username' type='text-single'/>
<field var='roster-subscription' label='Roster subscription' type='boolean'/>
</x>
</command>
</iq>
]]></example>
<p>A server MAY require a username to be specified for account creation.
In this case, the server MUST add the &lt;required/&gt; element to the
username field.
The username MUST be a valid localpart as defined in &rfc6122; §2.3.</p>
<example caption="Account creation with specified username"><![CDATA[
<iq type='set' from='romeo@example.com' to='example.com' id='exec2'>
<command xmlns='http://jabber.org/protocol/commands'
sessionid='config:20020923T213616Z-700'
node='create-account'>
<x xmlns='jabber:x:data' type='submit'>
<field var='username'>
<value>juliet</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption="Account creation finished"><![CDATA[
<iq type='result' to='romeo@example.com' from='example.com' id='exec2'>
<command xmlns='http://jabber.org/protocol/commands'
sessionid='config:20020923T213616Z-700'
node='create-account'
status='completed'>
<x xmlns='jabber:x:data' type='result'>
<item>
<field var='uri'>
<value>xmpp:juliet@example.com?register;preauth=TOKEN</value>
</field>
<field var='landing-url'>
<value>https://example.com/invite/#TOKEN</value>
</field>
<field var='expire'>
<value>2017-11-06T02:56:15Z</value>
</field>
</item>
</x>
</command>
</iq>
]]></example>
<p>The server's response for account creation is the same as for user
invitation except for the format of the <strong>uri</strong> field which
contains an XMPP URI of the following format:</p>
<code>xmpp:juliet@example.com?register;preauth=TOKEN</code>
<p>If no username was specified during the account creation process, the
local part of the JID in the XMPP URI is omitted by the server which
results in the following format:</p>
<code>xmpp:example.com?register;preauth=TOKEN</code>
<p>TODO: note about sensitivity of TOKEN</p>
</section2>
<section2 topic='Pre-Authenticated In-Band Registration' anchor='preauth-ibr'>
<p>In order to allow invited users to register on a server, the
registration processs as defined in &xep0077; needs to be extended. The
invited user's client MUST add a &lt;preauth&gt; element in the 'TODO'
namespace to the 'jabber:iq:register' query in order to inform the
server that it wants to perform Pre-Authenticated IBR:</p>
<example caption="Retrieving registration fields"><![CDATA[
<iq type='get' id='reg1' to='example.com'>
<query xmlns='jabber:iq:register'>
<preauth xmlns='urn:xmpp:invite:0'/>
</query>
</iq>
]]></example>
<p>If the server supports and is ready to perform Pre-Authenticated IBR,
it MUST add a &lt;token&gt; element to the response (TODO: 'token' or
'preauth'?):</p>
<example caption="Receiving registration fields"><![CDATA[
<iq type='result' to='romeo@example.com' from='example.com' id='reg1'>
<query xmlns='jabber:iq:register'>
<username/>
<password/>
<token/>
</query>
</iq>
]]></example>
<example caption='Registration process aborted (invalid token)'><![CDATA[
<iq type='error' from='example.com' id='reg1'>
<query xmlns='jabber:iq:register'>
<username>juliet</username>
<password>m1cro$oft</password>
<token>BADTOKEN</token>
</query>
<error type='cancel'>
<invalid-token xmlns='urn:xmpp:invite:0'/>
</error>
</iq>
]]></example>
<example caption='Registration process aborted (token expired)'><![CDATA[
<iq type='error' from='example.com' id='reg1'>
<query xmlns='jabber:iq:register'>
<username>juliet</username>
<password>m1cro$oft</password>
<token>OLDTOKEN</token>
</query>
<error type='cancel'>
<token-expired xmlns='urn:xmpp:invite:0'/>
</error>
</iq>
]]></example>
<p>After the invitee has successfully registered on the inviter's server
and roster subscription is enabled for account creation, the server MUST
use roster pushes as defined in &rfc6121; §2.1.6 in order to inform the
inviter about the invitee's new account without the need to reconnect.</p>
<example caption="Push roster item of invitee to inviter"><![CDATA[
<iq type='set' from='romeo@example.com' id='push'>
<query xmlns='jabber:iq:roster'>
<item subscription='both' jid='juliet@example.com'/>
</query>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Business Rules' anchor='rules'>
<section2 topic='Fallback to Client-Side PARS'>
<p>If the inviter's server does not support user invitation, the client
application SHOULD silently fall back to &xep0379; for a good user
experience.</p>
</section2>
<section2 topic='Account Creation'>
<p>If a username was specified during the account creation process, the
server SHOULD NOT create an account on the server until the invitee
actually registers it with the corresponding token.
The server MUST reserve the username at least until the corresponding
token expires.</p>
</section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<section2 topic='XMPP Server Suggestion for Invitees'>
<p>If the invitee opens an invitation URI with <strong>ibr=y</strong> and
chooses to create a new account, the client SHOULD pre-fill the
inviter JID's domain part as the new account's domain. The client MAY
provide a mechanism to enter or choose a different server, though.</p>
</section2>
</section1>
<section1 topic='Accessibility Considerations' anchor='access'>
<p>OPTIONAL.</p>
</section1>
<section1 topic='Internationalization Considerations' anchor='i18n'>
<p>OPTIONAL.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>See security considerations in &xep0379;.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<p>As authorized by &xep0147;, the XMPP Registrar maintains a registry of
queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).</p>
<p>The key-value parameter <strong>preauth</strong> is added to the
<strong>register</strong> query action as defined in &xep0077;</p>
<code><![CDATA[
<querytype>
<name>register</name>
...
<key>
<name>preauth</name>
<desc>the token used to allow one-time in-band registration on the inviter's server</desc>
</key>
</querytype>
]]></code>
<p>In addition to the <strong>preauth</strong> key-value parameter define
in &xep0379;, the <strong>ibr</strong> parameter is added to the
<strong>roster</strong> query action.</p>
<code><![CDATA[
<querytype>
<name>roster</name>
...
<key>
<name>ibr</name>
<value>y</value>
<desc>the parameter to indicate that the token allows the invitee to create an account on the inviter's server via in-band registration</desc>
</key>
</querytype>
]]></code>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>REQUIRED for protocol specifications.</p>
</section1>
</xep>