Browse Source

Move changes to bookmarks2 to actual XEP

Jonas Wielicki 1 year ago
parent
commit
a5d9506e68
2 changed files with 120 additions and 114 deletions
  1. 13
    101
      inbox/bookmarks2.xml
  2. 107
    13
      xep-0402.xml

+ 13
- 101
inbox/bookmarks2.xml View File

@@ -83,113 +83,29 @@
83 83
                 <td>string</td>
84 84
                 <td>OPTIONAL</td>
85 85
             </tr>
86
+            <tr>
87
+                <td>&lt;password/&gt; element</td>
88
+                <td>Unencrypted string for the password needed to enter a password-protected room. For security reasons, use of this element is NOT RECOMMENDED.</td>
89
+                <td>string</td>
90
+                <td>NOT RECOMMENDED</td>
91
+            </tr>
86 92
         </table>
87 93
         <p>Note: The datatypes are as defined in &w3xmlschema2;.</p>
88 94
         <example caption='An example of the conference element'><![CDATA[
89
-<conference xmlns=']]>&namespace;<![CDATA['
90
-            name='Council of Oberon'
91
-            autojoin='true'>
92
-    <nick>Puck</nick>
93
-</conference>
95
+      <conference xmlns=']]>&namespace;<![CDATA['
96
+                  name='Council of Oberon'
97
+                  autojoin='true'>
98
+        <nick>Puck</nick>
99
+      </conference>
94 100
 ]]></example>
95 101
         <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>
96 102
         <p>Note that a bookmark item MUST contain only one conference room.</p>
97 103
         <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>
98 104
         <example caption='Minimalist conference element'><![CDATA[
99
-<conference xmlns=']]>&namespace;<![CDATA['/>
105
+      <conference xmlns=']]>&namespace;<![CDATA['/>
100 106
 ]]></example>
101 107
     </section1>
102 108
 
103
-    <section1 topic='Examples' anchor='examples'>
104
-
105
-        <section2 topic='Retrieving all bookmarks' anchor='retrieving-bookmarks'>
106
-            <example caption='Client retrieves all bookmarks'><![CDATA[
107
-<iq from='juliet@capulet.lit/balcony' type='get' id='retrieve1'>
108
-    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
109
-        <items node='urn:xmpp:bookmarks:0'/>
110
-    </pubsub>
111
-</iq>
112
-        ]]></example>
113
-            <example caption='Server returns the bookmarks'><![CDATA[
114
-<iq type='result'
115
-    to='juliet@capulet.lit/balcony'
116
-    id='retrieve1'>
117
-  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
118
-    <items node='urn:xmpp:bookmarks:0'>
119
-      <item id='theplay@conference.shakespeare.lit'>
120
-          <conference name='The Play&apos;s the Thing'
121
-                      autojoin='true'>
122
-            <nick>JC</nick>
123
-          </conference>
124
-      </item>
125
-      <item id='orchard@conference.shakespeare.lit'>
126
-          <conference name='The Orchard'
127
-                      autojoin='true'>
128
-            <nick>JC</nick>
129
-          </conference>
130
-      </item>
131
-    </items>
132
-  </pubsub>
133
-</iq>
134
-        ]]></example>
135
-        </section2>
136
-
137
-        <section2 topic='Adding a bookmark' anchor='adding-a-bookmark'>
138
-            <p>Adding a bookmark means publishing a new item, with the bookmark JID as id, to the '&namespace;' node.</p>
139
-
140
-            <example caption='Client adds a new bookmark'><![CDATA[
141
-<iq from='juliet@capulet.lit/balcony' type='set' id='pip1'>
142
-    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
143
-        <publish node='urn:xmpp:bookmarks:0'>
144
-            <item id='theplay@conference.shakespeare.lit'>
145
-                <conference name='The Play&apos;s the Thing'
146
-                            autojoin='true'>
147
-                    <nick>JC</nick>
148
-                </conference>
149
-            </item>
150
-        </publish>
151
-        <publish-options>
152
-            <x xmlns='jabber:x:data' type='submit'>
153
-                <field var='FORM_TYPE' type='hidden'>
154
-                    <value>http://jabber.org/protocol/pubsub#publish-options</value>
155
-                </field>
156
-                <field var='pubsub#persist_items'>
157
-                    <value>true</value>
158
-                </field>
159
-                <field var='pubsub#access_model'>
160
-                    <value>whitelist</value>
161
-                </field>
162
-            </x>
163
-        </publish-options>
164
-    </pubsub>
165
-</iq>
166
-        ]]></example>
167
-            <example caption='Server acknowledges successful storage'><![CDATA[
168
-<iq to='juliet@capulet.lit/balcony' type='result' id='pip1'/>
169
-        ]]></example>
170
-        </section2>
171
-
172
-        <section2 topic='Removing a bookmark' anchor='removing-a-bookmark'>
173
-            <p>Removing a bookmark means retracting an existing item, identified by the bookmark's JID, form the '&namespace;' node.</p>
174
-            <p>This implies that server support for the "delete-items" pubsub feature is REQUIRED.</p>
175
-
176
-            <example caption='Client removes a new bookmark'><![CDATA[
177
-<iq from='juliet@capulet.lit/balcony' type='set' id='remove-bookmark1'>
178
-    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
179
-        <retract node='urn:xmpp:bookmarks:0'>
180
-            <item id='theplay@conference.shakespeare.lit'/>
181
-        </retract>
182
-    </pubsub>
183
-</iq>
184
-        ]]></example>
185
-            <example caption='Server acknowledges successful retraction'><![CDATA[
186
-<iq to='juliet@capulet.lit/balcony' type='result' id='remove-bookmark1'/>
187
-        ]]></example>
188
-        </section2>
189
-
190
-    </section1>
191
-
192
-
193 109
     <section1 topic="Bookmark Notifications">
194 110
         <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>
195 111
     </section1>
@@ -202,9 +118,6 @@
202 118
                 <li>The storage MUST be &xep0223;</li>
203 119
             </ul>
204 120
         </section2>
205
-        <section2 topic='Storage' anchor='storage'>
206
-            <p>&xep0060; is used for data storage, specifically through the use of private, personal pubsub nodes (described in &xep0223;) hosted at the user's virtual pubsub service (see &xep0163;).</p>
207
-        </section2>
208 121
         <section2 topic="Compatibility">
209 122
             <p>A server MAY choose to unify the bookmarks from both &xep0049; based and the current &xep0048;.</p>
210 123
             <section3 topic="Publishing via this specification">
@@ -225,7 +138,6 @@
225 138
     </section1>
226 139
 
227 140
     <section1 topic='Security Considerations' anchor='security'>
228
-        <p>Security considerations related to object persistence via publish-subscribe are described in <cite>XEP-0060</cite> and <cite>XEP-0223</cite>.</p>
229
-        <p>The client needs to make sure that the server actually supports the "http://jabber.org/protocol/pubsub#publish-options" feature, before relying on it. If it's not supported, the client should configure the '&namespace;' node first (see <cite>xep-0060</cite>), before adding any bookmarks.</p>
141
+        <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>
230 142
     </section1>
231 143
 </xep>

+ 107
- 13
xep-0402.xml View File

@@ -33,6 +33,12 @@
33 33
             <email>jc@opkode.com</email>
34 34
             <jid>jc@opkode.com</jid>
35 35
         </author>
36
+  <revision>
37
+    <version>0.2.0</version>
38
+    <date>2018-03-28</date>
39
+    <initials>jcb</initials>
40
+    <remark>Remove password element, add examples, update security considerations.</remark>
41
+  </revision>
36 42
   <revision>
37 43
     <version>0.1.0</version>
38 44
     <date>2018-03-28</date>
@@ -89,29 +95,113 @@
89 95
                 <td>string</td>
90 96
                 <td>OPTIONAL</td>
91 97
             </tr>
92
-            <tr>
93
-                <td>&lt;password/&gt; element</td>
94
-                <td>Unencrypted string for the password needed to enter a password-protected room. For security reasons, use of this element is NOT RECOMMENDED.</td>
95
-                <td>string</td>
96
-                <td>NOT RECOMMENDED</td>
97
-            </tr>
98 98
         </table>
99 99
         <p>Note: The datatypes are as defined in &w3xmlschema2;.</p>
100 100
         <example caption='An example of the conference element'><![CDATA[
101
-      <conference xmlns=']]>&namespace;<![CDATA['
102
-                  name='Council of Oberon'
103
-                  autojoin='true'>
104
-        <nick>Puck</nick>
105
-      </conference>
101
+<conference xmlns=']]>&namespace;<![CDATA['
102
+            name='Council of Oberon'
103
+            autojoin='true'>
104
+    <nick>Puck</nick>
105
+</conference>
106 106
 ]]></example>
107 107
         <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>
108 108
         <p>Note that a bookmark item MUST contain only one conference room.</p>
109 109
         <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>
110 110
         <example caption='Minimalist conference element'><![CDATA[
111
-      <conference xmlns=']]>&namespace;<![CDATA['/>
111
+<conference xmlns=']]>&namespace;<![CDATA['/>
112 112
 ]]></example>
113 113
     </section1>
114 114
 
115
+    <section1 topic='Examples' anchor='examples'>
116
+
117
+        <section2 topic='Retrieving all bookmarks' anchor='retrieving-bookmarks'>
118
+            <example caption='Client retrieves all bookmarks'><![CDATA[
119
+<iq from='juliet@capulet.lit/balcony' type='get' id='retrieve1'>
120
+    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
121
+        <items node='urn:xmpp:bookmarks:0'/>
122
+    </pubsub>
123
+</iq>
124
+        ]]></example>
125
+            <example caption='Server returns the bookmarks'><![CDATA[
126
+<iq type='result'
127
+    to='juliet@capulet.lit/balcony'
128
+    id='retrieve1'>
129
+  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
130
+    <items node='urn:xmpp:bookmarks:0'>
131
+      <item id='theplay@conference.shakespeare.lit'>
132
+          <conference name='The Play&apos;s the Thing'
133
+                      autojoin='true'>
134
+            <nick>JC</nick>
135
+          </conference>
136
+      </item>
137
+      <item id='orchard@conference.shakespeare.lit'>
138
+          <conference name='The Orchard'
139
+                      autojoin='true'>
140
+            <nick>JC</nick>
141
+          </conference>
142
+      </item>
143
+    </items>
144
+  </pubsub>
145
+</iq>
146
+        ]]></example>
147
+        </section2>
148
+
149
+        <section2 topic='Adding a bookmark' anchor='adding-a-bookmark'>
150
+            <p>Adding a bookmark means publishing a new item, with the bookmark JID as id, to the '&namespace;' node.</p>
151
+
152
+            <example caption='Client adds a new bookmark'><![CDATA[
153
+<iq from='juliet@capulet.lit/balcony' type='set' id='pip1'>
154
+    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
155
+        <publish node='urn:xmpp:bookmarks:0'>
156
+            <item id='theplay@conference.shakespeare.lit'>
157
+                <conference name='The Play&apos;s the Thing'
158
+                            autojoin='true'>
159
+                    <nick>JC</nick>
160
+                </conference>
161
+            </item>
162
+        </publish>
163
+        <publish-options>
164
+            <x xmlns='jabber:x:data' type='submit'>
165
+                <field var='FORM_TYPE' type='hidden'>
166
+                    <value>http://jabber.org/protocol/pubsub#publish-options</value>
167
+                </field>
168
+                <field var='pubsub#persist_items'>
169
+                    <value>true</value>
170
+                </field>
171
+                <field var='pubsub#access_model'>
172
+                    <value>whitelist</value>
173
+                </field>
174
+            </x>
175
+        </publish-options>
176
+    </pubsub>
177
+</iq>
178
+        ]]></example>
179
+            <example caption='Server acknowledges successful storage'><![CDATA[
180
+<iq to='juliet@capulet.lit/balcony' type='result' id='pip1'/>
181
+        ]]></example>
182
+        </section2>
183
+
184
+        <section2 topic='Removing a bookmark' anchor='removing-a-bookmark'>
185
+            <p>Removing a bookmark means retracting an existing item, identified by the bookmark's JID, form the '&namespace;' node.</p>
186
+            <p>This implies that server support for the "delete-items" pubsub feature is REQUIRED.</p>
187
+
188
+            <example caption='Client removes a new bookmark'><![CDATA[
189
+<iq from='juliet@capulet.lit/balcony' type='set' id='remove-bookmark1'>
190
+    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
191
+        <retract node='urn:xmpp:bookmarks:0'>
192
+            <item id='theplay@conference.shakespeare.lit'/>
193
+        </retract>
194
+    </pubsub>
195
+</iq>
196
+        ]]></example>
197
+            <example caption='Server acknowledges successful retraction'><![CDATA[
198
+<iq to='juliet@capulet.lit/balcony' type='result' id='remove-bookmark1'/>
199
+        ]]></example>
200
+        </section2>
201
+
202
+    </section1>
203
+
204
+
115 205
     <section1 topic="Bookmark Notifications">
116 206
         <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>
117 207
     </section1>
@@ -124,6 +214,9 @@
124 214
                 <li>The storage MUST be &xep0223;</li>
125 215
             </ul>
126 216
         </section2>
217
+        <section2 topic='Storage' anchor='storage'>
218
+            <p>&xep0060; is used for data storage, specifically through the use of private, personal pubsub nodes (described in &xep0223;) hosted at the user's virtual pubsub service (see &xep0163;).</p>
219
+        </section2>
127 220
         <section2 topic="Compatibility">
128 221
             <p>A server MAY choose to unify the bookmarks from both &xep0049; based and the current &xep0048;.</p>
129 222
             <section3 topic="Publishing via this specification">
@@ -144,6 +237,7 @@
144 237
     </section1>
145 238
 
146 239
     <section1 topic='Security Considerations' anchor='security'>
147
-        <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>
240
+        <p>Security considerations related to object persistence via publish-subscribe are described in <cite>XEP-0060</cite> and <cite>XEP-0223</cite>.</p>
241
+        <p>The client needs to make sure that the server actually supports the "http://jabber.org/protocol/pubsub#publish-options" feature, before relying on it. If it's not supported, the client should configure the '&namespace;' node first (see <cite>xep-0060</cite>), before adding any bookmarks.</p>
148 242
     </section1>
149 243
 </xep>

Loading…
Cancel
Save