XEP-0347 v0.3 - Added the possibility for owners to update meta-data about its things. This is done through the optional attribute jid on the update element; Added ROOM to the list of predefined tag names; Added anchors to section headers (pw)

2024-11-21 08:45:04 -05:00 · 2014-11-24 08:26:22 -07:00 · 2014-11-24 08:26:22 -07:00 · aa8fd0f4ea
commit aa8fd0f4ea
parent 7cba9d292e
1 changed files with 144 additions and 46 deletions
--- a/xep-0347.xml
+++ b/xep-0347.xml
@ -32,7 +32,7 @@
 		</dependencies>
 		<supersedes/>
 		<supersededby/>
-		<shortname>NOT_YET_ASSIGNED</shortname>
+		<shortname>iot-discovery</shortname>
 		<author>
 			<firstname>Peter</firstname>
 			<surname>Waher</surname>
@ -47,6 +47,19 @@
 			<jid>TBD</jid>
 			<uri>http://www-rnks.informatik.tu-cottbus.de/~rklauck</uri>
 		</author>
+		<revision>
+			<version>0.3</version>
+			<date>2014-11-11</date>
+			<initials>pw</initials>
+			<remark>
+				<p>
+					Added the possibility for <link url='#ownerupdate'>owners to update meta-data about its things</link>.
+					This is done through the optional attribute <strong>jid</strong> on the <strong>update</strong> element.
+				</p>
+				<p>Added <strong>ROOM</strong> to the <link url='#tags'>list of predefined tag names</link>.</p>
+				<p>Added anchors to section headers.</p>
+			</remark>
+		</revision>
 		<revision>
 			<version>0.2</version>
 			<date>2014-09-07</date>
@ -56,12 +69,12 @@
 			</remark>
 		</revision>
 		<revision>
-		  <version>0.1</version>
-		  <date>2014-04-10</date>
-		  <initials>editor (mam)</initials>
-		  <remark>
-		    <p>Initial published version approved by XMPP Council.</p>
-		  </remark>
+			<version>0.1</version>
+			<date>2014-04-10</date>
+			<initials>editor (mam)</initials>
+			<remark>
+				<p>Initial published version approved by XMPP Council.</p>
+			</remark>
 		</revision>
 		<revision>
 			<version>0.0.3</version>
@ -345,7 +358,7 @@
 			The life cycle of a Thing can be divided into multiple steps. The following sections will list many of these steps in possible order of occurrence during the
 			life cycle of the Thing.
 		</p>
-		<section2 topic='Production'>
+		<section2 topic='Production' anchor='production'>
 			<p>
 				During production of a Thing, decisions have to be made whether the following parameters should be pre-configured, manually entered after installation or
 				automatically found and/or created by the device if possible (zero-configuration networking):
@ -371,7 +384,7 @@
 				decentralized network architecture. A detailed discussion of the two alternatives goes beyond the scope of this specification, and will not be presented here.
 			</p>
 		</section2>
-		<section2 topic='Installation'>
+		<section2 topic='Installation' anchor='installation'>
 			<p>
 				Apart from physical installation, and connection to power and communication infrastructure, the installation phase of a Thing might also require manual entry of values that
 				could not be set in the production environment. Since Things might have very limited human user interfaces, external tools might be required to provide this information. Due
@ -379,7 +392,7 @@
 				resources where such cannot be found nor set in a production environment.
 			</p>
 		</section2>
-		<section2 topic='Finding XMPP Server'>
+		<section2 topic='Finding XMPP Server' anchor='findingserver'>
 			<p>
 				If the address of an XMPP Server is not preconfigured, the Thing must attempt to find one in its local surroundings. This can be done using one of several methods:
 			</p>
@ -391,7 +404,7 @@
 			<p>
 				The following sections describe them in more detail.
 			</p>
-			<section3 topic='DHCP'>
+			<section3 topic='DHCP' anchor='dhcp'>
 				<p>
 					DHCP offers an internal structure for advertising configuration information to clients in a network.
 					This includes configuration parameters and other control elements, which are transmitted in special marked data elements, called 'options', as described in
@ -415,7 +428,7 @@
 						<strong>TBD:</strong> Define and register DHCP and BOOTP option as described in <link url='#option'>Parameters for IoT Discovery</link>. Use of 'option-code' 84.
 					</li>
 				</ul>
-				<section4 topic='XMPP Server Option'>
+				<section4 topic='XMPP Server Option' anchor='serveroption'>
 					<p>
 						This option specifies the name of the XMPP server.
 						The name may or may not be qualified with the local domain name.
@ -434,7 +447,7 @@
   224 12 pronto.local]]>
 					</example>
 				</section4>
-				<section4 topic='Dynamic Host Configuration Protocol (DHCP) and Bootstrap Protocol (BOOTP) Parameters for IoT Discovery' anchor='option'>
+				<section4 topic='Dynamic Host Configuration Protocol (DHCP) and Bootstrap Protocol (BOOTP) Parameters for IoT Discovery' anchor='dhcpoption'>
 					<p>The following parameters in use as of MONTH 201x. Refer to the DHCP and BOOTP parameters itself for a complete and current list of parameters (this specification might or might not be revised when new parameters are registered).</p>
 					<example caption='IoT Discovery DHCP and BOOTP Parameters Registry'>
 						<![CDATA[
@ -446,7 +459,7 @@
 					</example>
 				</section4>
 			</section3>
-			<section3 topic='Multicast DNS (mDNS) and DNS Service Discovery (DNS-SD)'>
+			<section3 topic='Multicast DNS (mDNS) and DNS Service Discovery (DNS-SD)' anchor='dns'>
 				<p>
 					An introduction of mDNS/DNS-SD (e.g., how it works and terminology) is described in &xep0174; (i.e., sections [1.2] and [2]).
 					For the purpose of IoT Discovery we are interested only in the "xmpp-client" service.
@ -454,7 +467,7 @@
 					An XMPP chat client (actually its mDNS daemon) can send out multicast DNS queries for services of type "xmpp-client".
 					<strong>Note:</strong> the service of type "xmpp-client" is the reservered name for client-to-server connections by IANA, as described in &rfc6120;.
 				</p>
-				<section4 topic='DNS Records'>
+				<section4 topic='DNS Records' anchor='dnsrecords'>
 					<p>In order to advertise its availability, a server MUST publish four different kinds of DNS records:</p>
 					<ol>
 						<li>
@ -551,7 +564,7 @@
 				</section4>
 				<!-- Ref: XEP-0174 -->
 			</section3>
-			<section3 topic='SSDP/UPnP'>
+			<section3 topic='SSDP/UPnP' anchor='upnp'>
 				<p>TBD</p>
 				<!-- TODO -->
 			</section3>
@ -560,7 +573,7 @@
 				Provisioning Server and other peers it want to connect to. The next section can thus be skipped.
 			</p>
 		</section2>
-		<section2 topic='Connection to XMPP Server'>
+		<section2 topic='Connection to XMPP Server' anchor='connection'>
 			<p>
 				Once an XMPP Server has been found, a connection can be made. If multiple XMPP Servers are found, the client is free to choose the one that best suits its purposes.
 			</p>
@ -569,7 +582,7 @@
 				allows account creation can be used.
 			</p>
 		</section2>
-		<section2 topic='Finding Thing Registry'>
+		<section2 topic='Finding Thing Registry' anchor='findingregistry'>
 			<p>
 				If a Thing Registry is not preconfigured, one must be found. A Thing Registry can be hosted either as a server component using &xep0114; or as an XMPP Client accessible through
 				a JID. The following lists methods to obtaining the Component Address or JID for the Thing Registry. Note that the last one has <link url='#security'>security considerations</link> 
@ -593,7 +606,7 @@
 				</li>
 			</ol>
 		</section2>
-		<section2 topic='Registering Thing'>
+		<section2 topic='Registering Thing' anchor='register'>
 			<p>
 				Once a Thing Registry has been found and been befriended, the Thing can register itself with the registry, as follows:
 			</p>
@ -649,7 +662,7 @@
 				<strong>Note:</strong> Meta Tag names are case insensitive. In this document, all tag names have been written using upper case letters.
 			</p>
 		</section2>
-		<section2 topic='Register self-owned Thing'>
+		<section2 topic='Register self-owned Thing' anchor='registerselfowner'>
 			<p>
 				If a thing is self-owned, it can register itself with the Registry as normal, with the addition of setting the attribute <strong>selfOwned</strong> to <strong>true</strong>,
 				as is shown below. This registers the Thing directly as PUBLIC CLAIMED, with no need for an owner to claim ownership of the device. This can be useful if
@ -676,7 +689,7 @@
       id='2'/>]]>
 			</example>
 		</section2>
-		<section2 topic='Register Thing behind Concentrator'>
+		<section2 topic='Register Thing behind Concentrator' anchor='registerconcentrator'>
 			<p>
 				A Thing might reside behind a gateway or concentrator and might not be directly connected to the XMPP network itself, as is described in &xep0326;. In these cases, there are three optional
 				attributes that can be used to identify the Thing behind the JID: The <strong>nodeId</strong> attribute gives the ID of the Thing (a.k.a. "Node"). The Node might reside in
@ -713,7 +726,7 @@
 				If the Thing behind the concentrator is self-owned, it simply adds the <strong>selfOwned</strong> attribute to the request and sets it to <strong>true</strong>.
 			</p>
 		</section2>
-		<section2 topic='Claiming Ownership of a Thing'>
+		<section2 topic='Claiming Ownership of a Thing' anchor='claim'>
 			<p>
 				As mentioned above, the owner of the Thing must provide the information provided by the Thing to the Registry, in order to claim ownership over it. To avoid the
 				possibility that somebody can guess the information, the information must necessarily be long. This creates the problem of transfer of information. One method to solve this
@ -889,7 +902,7 @@
 				<strong>Note:</strong> Meta Tag names are case insensitive. In this document, all tag names have been written using upper case letters.
 			</p>
 		</section2>
-		<section2 topic='Removing Thing from Registry'>
+		<section2 topic='Removing Thing from Registry' anchor='remove'>
 			<p>
 				After a Thing has been claimed and is registed as a PUBLIC CLAIMED Thing in the Registry, it implies the Thing is available in searches. The owner can choose to remove
 				the Thing from the Registry, to avoid that the Thing appears in searches. To remove a Thing from the Registry the owner simply sends a removal request to the Registry
@ -983,7 +996,7 @@
       id='7'/>]]>
 			</example>
 		</section2>
-		<section2 topic='Finding Provisioning Server'>
+		<section2 topic='Finding Provisioning Server' anchor='findingprovisioning'>
 			<p>
 				Up to this point only basic configuration and ownership and visibility of a Thing has been covered. For more advanced operations, a Thing might be required to
 				use a Provisioning Server to whom it can delegate trust and allow making decisions, controlling access rights and privileges for the Thing, as described in &xep0324;.
@ -1015,12 +1028,12 @@
 				</li>
 			</ol>
 		</section2>
-		<section2 topic='Delegating Trust'>
+		<section2 topic='Delegating Trust' anchor='delegate'>
 			<p>
 				Once a Provisioning Server has been found and been befriended, the Thing can delegate its trust to it, according to &xep0324;.
 			</p>
 		</section2>
-		<section2 topic='Update Meta Information about Thing in Registry'>
+		<section2 topic='Update Meta Information about Thing in Registry' anchor='update'>
 			<p>
 				Once a Thing has been claimed and chooses to reside as a public Thing in the registry, it can update its meta information at any time. This meta information
 				will be available in searches made to the registry by third parties and is considered public. However, the Thing should be connected to a provisioning server
@ -1111,7 +1124,80 @@
 				<strong>Note:</strong> Meta Tag names are case insensitive. In this document, all tag names have been written using upper case letters.
 			</p>
 		</section2>
-		<section2 topic='Search for Public Things in Registry'>
+		<section2 topic='Owner updating Meta Information about Thing in Registry' anchor='ownerupdate'>
+			<p>
+				An owner of a thing can also update the meta-data of a thing it has claimed. To do this, you simply add a <strong>jid</strong> attribute containing the JID of the thing to the
+				<strong>update</strong> element. (If this attribute is not present, the JID is assumed to be that of the sender of the message.)
+			</p>
+			<example caption='Owner requests an update of Meta Data of Thing'>
+				<![CDATA[
+   <iq type='set'
+       from='owner@clayster.com/1234'
+       to='discovery.clayster.com'
+       id='8'>
+      <update xmlns='urn:xmpp:iot:discovery' jid='thing@clayster.com'>
+          <str name='ROOM' value='...'/>
+          <str name='APT' value='...'/>
+          <str name='BLD' value='...'/>
+          <str name='STREET' value='...'/>
+          <str name='STREETNR' value='...'/>
+          <str name='AREA' value='...'/>
+          <str name='CITY' value='...'/>
+          <str name='REGION' value='...'/>
+          <str name='COUNTRY' value='...'/>
+      </update>
+   </iq>]]>
+			</example>
+			<p>
+				The owner can update meta-data of things behind concentrators also. To do this, the corresponding attributes <strong>nodeId</strong>, <strong>sourceId</strong>
+				and <strong>cacheType</strong> must be used to identify the thing, as follows:
+			</p>
+			<example caption='Owner requests an update of Meta Data of Thing behind concentrator'>
+				<![CDATA[
+   <iq type='set'
+       from='owner@clayster.com/1234'
+       to='discovery.clayster.com'
+       id='8'>
+      <update xmlns='urn:xmpp:iot:discovery' jid='rack@clayster.com' nodeId='imc1' sourceId='MeteringTopology'>
+          <str name='ROOM' value='...'/>
+          <str name='APT' value='...'/>
+          <str name='BLD' value='...'/>
+          <str name='STREET' value='...'/>
+          <str name='STREETNR' value='...'/>
+          <str name='AREA' value='...'/>
+          <str name='CITY' value='...'/>
+          <str name='REGION' value='...'/>
+          <str name='COUNTRY' value='...'/>
+      </update>
+   </iq>]]>
+			</example>
+			<p>
+				If the Thing is found in the registry and it is claimed by the sender of the current message (i.e. owner is the sender), the registry simply acknowledges the update as follows:
+			</p>
+			<example caption='Owner updating thing Meta Data request acknowledgement'>
+				<![CDATA[
+   <iq type='result'
+       from='discovery.clayster.com'
+       to='owner@clayster.com/1234'
+       id='8'/>]]>
+			</example>
+			<p>
+				But if the owner is not the sender of the current message (i.e. owner is somebody else), or if the thing is not found at all, the server must report the node as 
+				<strong>not existing</strong> (i.e. not existing among the set of things claimed by the owner).
+			</p>
+			<example caption='Owner updating thing Meta Data request failure'>
+				<![CDATA[
+   <iq type='error'
+       from='discovery.clayster.com'
+       to='owner@clayster.com/1234'
+       id='8'>
+      <error type='cancel'>
+         <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
+      </error>
+   </iq>]]>
+			</example>
+		</section2>
+		<section2 topic='Search for Public Things in Registry' anchor='search'>
 			<p>
 				It is possible for anyone with access to the Thing Registry to search for public Things that have been claimed, including self-owned Things. Such searches
 				will never return things that have not been claimed or have been removed from the registry.
@ -1320,7 +1406,7 @@
 				<strong>Note:</strong> Meta Tag names are case insensitive. In this document, all tag names have been written using upper case letters.
 			</p>
 		</section2>
-		<section2 topic='Unregistering Thing from Registry'>
+		<section2 topic='Unregistering Thing from Registry' anchor='unregister'>
 			<p>
 				A thing can unregister itself from the Registry. This can be done in an uninstallation procedure for instance. To unregister from the registry, it simply sends
 				an un-registration request to the registry as follows.
@ -1358,7 +1444,7 @@
       id='10'/>]]>
 			</example>
 		</section2>
-		<section2 topic='Disowning Thing'>
+		<section2 topic='Disowning Thing' anchor='disown'>
 			<p>
 				The owner of a Thing can disown the Thing, returning it to a state without owner. This is done by sending the following request to the Thing Registry:
 			</p>
@ -1668,6 +1754,11 @@
 					<td>String</td>
 					<td>Region associated with the Thing</td>
 				</tr>
+				<tr>
+					<td>ROOM</td>
+					<td>String</td>
+					<td>Room associated with the Thing</td>
+				</tr>
 				<tr>
 					<td>SN</td>
 					<td>String</td>
@ -1697,7 +1788,7 @@
 				<strong>Note:</strong> Meta Tag names are case insensitive. In this document, all tag names have been written using upper case letters.
 			</p>
 		</section2>
-		<section2 topic='Friendships between Things and Registry'>
+		<section2 topic='Friendships between Things and Registry' anchor='friendships'>
 			<p>
 				In the case the Thing Registry is not the XMPP Server to which the Thing is connected, a friendship relationship between the Thing and the Thing Registry needs to be handled.
 				To minimize the number of concurrent friends the Thing Registry needs to maintain, a Thing must only maintain an active friendship with the registry if it needs to
@ -1729,7 +1820,7 @@
 				Component when the population of Things grows.
 			</p>
 		</section2>
-		<section2 topic='Hijacking predefined JIDs'>
+		<section2 topic='Hijacking predefined JIDs' anchor='hijackingjids'>
 			<p>
 				If using predefined user names when searching for a Thing Registry or Provisioning Server, care must be taken to which XMPP Server things connect.
 				It might be possible for third parties to register these predefined account names, and pretend to be a Thing Registry or Provisioning Server and in this way hijack 
@ -1737,7 +1828,7 @@
 				sure the things cannot be hijacked.
 			</p>
 		</section2>
-		<section2 topic='Hijacking things in public areas'>
+		<section2 topic='Hijacking things in public areas' anchor='hijackingthings'>
 			<p>
 				The combination of visible key meta information (perhaps in a visible QR-code) and a factory default reset button on a Thing, opens up the possibility to hijack the Thing.
 				To avoid this, at least one of the two should be removed after successful installation. Either the key meta information (QR-code) should be placed on the package or separate
@ -1751,7 +1842,7 @@
 				thing hijacked.
 			</p>
 		</section2>
-		<section2 topic='Key meta information in searches'>
+		<section2 topic='Key meta information in searches' anchor='keysearch'>
 			<p>
 				Care should be taken what key meta information is used to accept an ownership claim. After a successful claim, this meta information is still available in the registry,
 				at least until the Thing is removed from the registry. While public in the registry, the meta information can be searched and presented to third parties. Access to this
@ -1772,7 +1863,7 @@
 				</li>
 			</ul>
 		</section2>
-		<section2 topic='KEY tag'>
+		<section2 topic='KEY tag' anchor='key'>
 			<p>
 				The <strong>KEY</strong> tag is unique in that it is not searchable nor available is search results. For this reason it is ideal for providing secrets shared only
 				between the Thing and the owner. By providing a sufficiently long KEY value in the key meta information required to claim the Thing, guessing the information even though
@ -1783,7 +1874,7 @@
 				the key cannot be learned by looking into the database of the registry, or by some other means.
 			</p>
 		</section2>
-		<section2 topic='Tag name spam'>
+		<section2 topic='Tag name spam' anchor='tagspam'>
 			<p>
 				This document does not limit tag names or the number of tags that can be used by Things. This opens up the possibility of tag spam. Malicious things could fill the database
 				of the registry by reporting random tag names until the database is full.
@ -1793,21 +1884,21 @@
 				tag names defined in this document. If it has a configurable list of approved tags that can be stored, or if it allows any tags is an implementation decision.
 			</p>
 		</section2>
-		<section2 topic='External services for creating QR-codes'>
+		<section2 topic='External services for creating QR-codes' anchor='externalqr'>
 			<p>
 				If using external services when creating QR-codes, like the Google Charts API used in this document, make sure HTTPS is used and certificates validated. If HTTP is used,
 				meta-data tags used in Thing Registry registrations can be found out by sniffing the network, making it possible to hijack the corresponding devices.
 			</p>
 		</section2>
-		<section2 topic='DHCP Security Considerations'>
+		<section2 topic='DHCP Security Considerations' anchor='dhcpsec'>
 			<p>TBD</p>
 			<!-- TODO -->
 		</section2>
-		<section2 topic='DNS Security Considerations'>
+		<section2 topic='DNS Security Considerations' anchor='dnssec'>
 			<p>TBD</p>
 			<!-- TODO -->
 		</section2>
-		<section2 topic='UPnP Security Considerations'>
+		<section2 topic='UPnP Security Considerations' anchor='upnpsec'>
 			<p>TBD</p>
 			<!-- TODO -->
 		</section2>
@ -1832,7 +1923,7 @@
 
    <xs:element name='register' type='Register'/>
    <xs:element name='mine' type='Mine'/>
-    <xs:element name='update' type='MetaDataNodeInfo'/>
+    <xs:element name='update' type='Update'/>
 
    <xs:element name='claimed' type='Claimed'/>
    <xs:element name='remove' type='Jid'/>
@ -1897,13 +1988,12 @@
        <xs:attribute name='sourceId' type='xs:string' use='optional'/>
        <xs:attribute name='cacheType' type='xs:string' use='optional'/>
    </xs:attributeGroup>
-    
+     
    <xs:complexType name='MetaData'>
        <xs:choice minOccurs='0' maxOccurs='unbounded'>
            <xs:element name='str' type='StrTag'/>
            <xs:element name='num' type='NumTag'/>
        </xs:choice>
-        <xs:attributeGroup ref='nodeInfo'/>
    </xs:complexType>
 
    <xs:complexType name='MetaDataNodeInfo'>
@ -1921,15 +2011,23 @@
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
-  
+ 
    <xs:complexType name='Mine'>
        <xs:complexContent>
-            <xs:extension base='MetaData'>
+            <xs:extension base='MetaDataNodeInfo'>
                <xs:attribute name='public' type='xs:boolean' use='optional' default='true'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
 
+    <xs:complexType name='Update'>
+        <xs:complexContent>
+            <xs:extension base='MetaDataNodeInfo'>
+                <xs:attribute name='jid' type='xs:string' use='optional'/>
+            </xs:extension>
+        </xs:complexContent>
+    </xs:complexType>
+ 
    <xs:complexType name='Claimed'>
        <xs:complexContent>
            <xs:extension base='Jid'>
@ -2002,8 +2100,8 @@
 	</section1>
 	<section1 topic='Acknowledgements' anchor='ack'>
 		<p>
-			Thanks to Henrik Svedlund, Ivan Vučica, Joachim Lindborg, Joakim Eriksson, Joakim Ramberg, Johannes Hund, Karin Forsell, Kevin Smith, Lance Stout, Lars Åkerskog, Olof Zandrén, 
-			Philipp Hancke, Steffen Larsen, Teemu Väisänen and Yusuke Doi for all valuable feedback.
+			Thanks to Eelco Cramer, Henrik Svedlund, Ivan Vučica, Joachim Lindborg, Joakim Eriksson, Joakim Ramberg, Johannes Hund, Karin Forsell, Kevin Smith, Lance Stout, Lars Åkerskog, 
+			Olof Zandrén, Philipp Hancke, Steffen Larsen, Teemu Väisänen and Yusuke Doi for all valuable feedback.
 		</p>
 	</section1>
 </xep>