From aa8fd0f4ea4e35fd5d2b1da066b8f63fa495c44d Mon Sep 17 00:00:00 2001 From: "Matthew A. Miller" Date: Mon, 24 Nov 2014 08:26:22 -0700 Subject: [PATCH] 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) --- xep-0347.xml | 190 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 144 insertions(+), 46 deletions(-) diff --git a/xep-0347.xml b/xep-0347.xml index 53e2adfa..c1bde211 100644 --- a/xep-0347.xml +++ b/xep-0347.xml @@ -32,7 +32,7 @@ - NOT_YET_ASSIGNED + iot-discovery Peter Waher @@ -47,6 +47,19 @@ TBD http://www-rnks.informatik.tu-cottbus.de/~rklauck + + 0.3 + 2014-11-11 + pw + +

+ 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.

+ + 0.2 2014-09-07 @@ -56,12 +69,12 @@ - 0.1 - 2014-04-10 - editor (mam) - -

Initial published version approved by XMPP Council.

- + 0.1 + 2014-04-10 + editor (mam) + +

Initial published version approved by XMPP Council.

+ 0.0.3 @@ -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.

- +

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.

- +

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.

- +

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:

@@ -391,7 +404,7 @@

The following sections describe them in more detail.

- +

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 @@ TBD: Define and register DHCP and BOOTP option as described in Parameters for IoT Discovery. Use of 'option-code' 84. - +

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]]> - +

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).

 - +

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". Note: the service of type "xmpp-client" is the reservered name for client-to-server connections by IANA, as described in &rfc6120;.

- +

In order to advertise its availability, a server MUST publish four different kinds of DNS records:

  1. @@ -551,7 +564,7 @@ - +

    TBD

     @@ -560,7 +573,7 @@ Provisioning Server and other peers it want to connect to. The next section can thus be skipped.

    - +

    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.

    @@ -569,7 +582,7 @@ allows account creation can be used.

    - +

    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 security considerations @@ -593,7 +606,7 @@

- +

Once a Thing Registry has been found and been befriended, the Thing can register itself with the registry, as follows:

@@ -649,7 +662,7 @@ Note: Meta Tag names are case insensitive. In this document, all tag names have been written using upper case letters.

- +

If a thing is self-owned, it can register itself with the Registry as normal, with the addition of setting the attribute selfOwned to true, 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'/>]]> - +

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 nodeId 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 selfOwned attribute to the request and sets it to true.

- +

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 @@ Note: Meta Tag names are case insensitive. In this document, all tag names have been written using upper case letters.

- +

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'/>]]> - +

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 @@ - +

Once a Provisioning Server has been found and been befriended, the Thing can delegate its trust to it, according to &xep0324;.

- +

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 @@ Note: Meta Tag names are case insensitive. In this document, all tag names have been written using upper case letters.

- + +

+ An owner of a thing can also update the meta-data of a thing it has claimed. To do this, you simply add a jid attribute containing the JID of the thing to the + update element. (If this attribute is not present, the JID is assumed to be that of the sender of the message.) +

+ + + + + + + + + + + + + + ]]> + +

+ The owner can update meta-data of things behind concentrators also. To do this, the corresponding attributes nodeId, sourceId + and cacheType must be used to identify the thing, as follows: +

+ + + + + + + + + + + + + + ]]> + +

+ 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: +

+ + ]]> + +

+ 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 + not existing (i.e. not existing among the set of things claimed by the owner). +

+ + + + + + ]]> + + +

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 @@ Note: Meta Tag names are case insensitive. In this document, all tag names have been written using upper case letters.

- +

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'/>]]> - +

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:

@@ -1668,6 +1754,11 @@ String Region associated with the Thing + + ROOM + String + Room associated with the Thing + SN String @@ -1697,7 +1788,7 @@ Note: Meta Tag names are case insensitive. In this document, all tag names have been written using upper case letters.

- +

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.

- +

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.

- +

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.

- +

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 @@ - +

The KEY 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.

- +

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.

- +

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.

- +

TBD

 - +

TBD

 - +

TBD

 @@ -1832,7 +1923,7 @@ - + @@ -1897,13 +1988,12 @@ - + - @@ -1921,15 +2011,23 @@ - + - + + + + + + + + + @@ -2002,8 +2100,8 @@

- 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.