From 4eb67d7f698547c76a6aeb8c7d197f7de7afc7ab Mon Sep 17 00:00:00 2001 From: "Matthew A. Miller" Date: Mon, 10 Mar 2014 12:04:23 -0600 Subject: [PATCH] XEP-0324 v0.2: Corrected downloadPrivileges example; Made several corrections of the language; Expanded the introduction; Changes 'Sensor Networks' to 'Internet of Things'; Fixed links to documents with new numbers; Changed namespace urn:xmpp:sn to urn:xmpp:iot --- xep-0324.xml | 474 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 280 insertions(+), 194 deletions(-) diff --git a/xep-0324.xml b/xep-0324.xml index c5cbb652..8234422e 100644 --- a/xep-0324.xml +++ b/xep-0324.xml @@ -7,8 +7,9 @@
Internet of Things - Provisioning - This specification describes an architecture for efficient provisioning of services, access rights and user privileges in sensor networks. - &LEGALNOTICE; + This specification describes an architecture for efficient provisioning of services, access rights and user privileges in for the Internet of Things, where + communication between Things is done using the XMPP protocol. + &LEGALNOTICE; 0324 Experimental Standards Track @@ -19,27 +20,43 @@ XEP-0001 XEP-0030 XEP-0323 + XEP-0325 - NOT_YET_ASSIGNED + sensor-network-provisioning Peter Waher peter.waher@clayster.com peter.waher@jabber.org - http://se.linkedin.com/pub/peter-waher/1a/71b/a29/ + http://www.linkedin.com/in/peterwaher - - 0.1 - 2013-04-16 - psa -

Initial published version approved by the XMPP Council.

 - - + + 0.2 + 2014-03-10 + pw + +

Corrected downloadPrivileges example.

+

Made several corrections of the language.

+

Expanded the introduction.

+

Changes "Sensor Networks" to "Internet of Things".

+

Fixed links to documents with new numbers.

+

Changed namespace urn:xmpp:sn to urn:xmpp:iot

+ + + + 0.1 + 2013-04-16 + psa + +

Initial published version approved by the XMPP Council.

+ + + 0.0.5 2013-04-04 - pwa + pw

Added control use cases.

Grouped use cases.

@@ -48,7 +65,7 @@ 0.0.4 2013-04-01 - pwa + pw

Added altitude credentials.

Added resource information of original called to their corresponding JIDs.

@@ -60,7 +77,7 @@ 0.0.3 2013-03-18 - pwa + pw

Added information about how to read sensors from large subsystems.

Added friend recommendation message.

@@ -70,7 +87,7 @@ 0.0.2 2013-03-12 - pwa + pw

Added use cases for service access rights and corresponding user privileges.

 @@ -78,93 +95,110 @@ 0.0.1 2013-03-11 - pwa + pw

First draft.
-

- This XEP provides the underlying architecture, basic operations and data structures for provisioning of services, access rights and user privileges in sensor networks. +

+ This specification describes an architecture for efficient provisioning of services, access rights and user privileges in for the Internet of Things, where + communication between Things is done using the XMPP protocol. +

+

+ Note has to be taken, that this XEP, and other Internet of Things-related XEP's, are designed for implementation in small devices, many of which have very limited + amount of memory (both RAM and ROM) or resources (processing power). Therefore, simplicity is of utmost importance. Furthermore, Internet of Things networks can + become huge, easily containing millions or billions of devices in peer-to-peer networks.

- Note has to be taken, that these XEP's are designed for implementation in sensors, many of which have very limited amount of memory (both RAM and ROM) or resources (processing power). - Therefore, simplicity is of utmost importance. Furthermore, sensor networks can become huge, easily containing millions of devices in peer-to-peer networks. + An added complexity in the provisioning case is that Things (small sensors for example) often have very limited user interface options. Therefore, this document + explains how provisioning can be done efficiently using a trusted third party with more power and options when it comes to user interface design and storage.

+

+ This document defines the following important operations to allow for efficient provisioning of services in the Internet of Things, based on XMPP: +

+
    +
  • What Things knows what Things
    • +
  • What Things can read data from what Things, and what data.
    • +
  • What Things can control what Things, and what parts.
    • +
  • Control of Users in the network.
    • +
  • Control of Services in the network.
    • +
  • Control generic boolean User Privileges in the network.
    • +

- An added complexity in the provisioning case is that sensors often have very limited user interface options. Therefore, this document explains how provisioning can be done - efficiently using a trusted third party with more power and options when it comes to user interface design and storage. + This XEP relies on &xep0323; and &xep0325; for sensor data readout and control interfaces. + Internet of Things contain many different architectures and use cases. For this reason, the IoT standards have been divided into multiple XEPs according to the following table:

-

- This XEP relies heavily on sensor-data sensor-data. - Sensor networks contain many different architectures and use cases. For this reason, the sensor network standards have been divided into multiple XEPs according to the following table: -

- - +
- - - - - - - - - - - - - + - - + + - - + + - - + + - - - - - - - - - + - - + + - - - - - - + + + + + + + + + + -
XEP Description
XEP-0000-ColorParameterDefines extensions for how color parameters can be handled, based on &xep0004;
XEP-0000-DynamicFormsDefines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;.
exi - Defines how to EXI can be used in XMPP to achieve efficient compression of data. Albeit not a sensor network specific XEP, this XEP should be considered - in all sensor network implementations where memory and packet size is an issue. -
xep-0000-SN-BatteryPoweredSensorsxep-0000-IoT-BatteryPoweredSensors Defines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network.
xep-0000-SN-ConcentratorsDefines how to handle architectures containing concentrators or servers handling multiple sensors.xep-0000-IoT-DiscoveryDefines the peculiars of Thing discovery in Internet of Things. Apart from discovering Things by JID, it also defines how to discover Things based on location, etc.
xep-0000-SN-ControlDefines how to control actuators and other devices in sensor networks.xep-0000-IoT-EventsDefines how Things send events, how event subscription, hysteresis levels, etc., are configured.
xep-0000-SN-DiscoveryDefines the peculiars of sensor discovery in sensor networks. Apart from discovering sensors by JID, it also defines how to discover sensors based on location, etc.xep-0000-IoT-InteroperabilityDefines guidelines for how to achieve interoperability in Internet of Things, publishing interoperability interfaces for different types of devices.
xep-0000-SN-EventsDefines how sensors send events, how event subscription, hysteresis levels, etc., are configured.
xep-0000-SN-InteroperabilityDefines guidelines for how to achieve interoperability in sensor networks, publishing interoperability interfaces for different types of devices.
xep-0000-SN-Multicastxep-0000-IoT-Multicast Defines how sensor data can be multicast in efficient ways.
sensor-network-provisioningThis specification. Defines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented.xep-0000-IoT-PubSubDefines how efficient publication of sensor data can be made in Internet of Things.
xep-0000-SN-PubSubDefines how efficient publication of sensor data can be made in sensor networks.
sensor-data
xep-0000-IoT-ChatDefines how human-to-machine interfaces should be constructed using chat messages to be user friendly, automatable and consistent with other IoT extensions and possible underlying architecture.
XEP-0322 + Defines how to EXI can be used in XMPP to achieve efficient compression of data. Albeit not a Internet of Things specific XEP, this XEP should be considered + in all Internet of Things implementations where memory and packet size is an issue. +
XEP-0323 Provides the underlying architecture, basic operations and data structures for sensor data communication over XMPP networks. - It includes a hardware abstraction model, removing any technical detail implemented in underlying technologies. This XEP is used by all other sensor network XEPs. + It includes a hardware abstraction model, removing any technical detail implemented in underlying technologies. This XEP is used by all other + Internet of Things XEPs.
+ + XEP-0324 + This specification. Defines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented. + + + XEP-0325 + Defines how to control actuators and other devices in Internet of Things. + + + XEP-0326 + Defines how to handle architectures containing concentrators or servers handling multiple Things. + + + XEP-0331 + Defines extensions for how color parameters can be handled, based on &xep0004; + + + XEP-0336 + Defines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;. + +

The following table lists common terms and corresponding descriptions.

@@ -173,7 +207,11 @@
Actuator
Device containing at least one configurable property or output that can and should be controlled by some other entity or device.
- + +
Authority
+
Used synonymously with Provisioning Server.
+ +
Computed Value
A value that is computed instead of measured.
 @@ -219,22 +257,22 @@
Node
- Graphs contain nodes and edges between nodes. In Sensor Networks, sensors, actuators, meters, devices, gatewats, etc., are often depicted as nodes and links between sensors (friendships) - are depicted as edges. In abstract terms, it's easier to talk about a Node, than have to list different types of nodes possible (sensors, actuators, meters, devices, gateways, etc.). - Each Node has a Node ID. -
+ Graphs contain nodes and edges between nodes. In Internet of Things, sensors, actuators, meters, devices, gateways, etc., are often depicted as nodes whereas links between sensors (friendships) + are depicted as edges. In abstract terms, it's easier to talk about a Node, rather than list different possible node types (sensors, actuators, meters, devices, gateways, etc.). + Each Node has a Node ID. +
Node ID
- An ID uniquelly identifying a node within its corresponding context. If a globally unique ID is desired, an architechture should be used using a universally accepted + An ID uniquely identifying a node within its corresponding context. If a globally unique ID is desired, an architecture should be used using a universally accepted ID scheme.
Parameter
- Readable and/or writable property on a node/device. The XEP xep-0000-SN-Concentrators deals with reading and writing parameters + Readable and/or writable property on a node/device. The XEP-0326 &xep0326; deals with reading and writing parameters on nodes/devices. Fields are not parameters, and parameters are not fields.
@@ -242,7 +280,12 @@
Peak Value
A maximum or minimum value during a given period.
 - + +
Provisioning Server
+
An application that can configure a network and provide services to users or Things. In Internet of Things, a Provisioning Server knows who knows whom, + what privileges users have, who can read what data and who can control what devices and what parts of these devices.
+ +
Precision
In physics, precision determines the number of digits of precision. In sensor networks however, this definition is not easily applicable. Instead, precision @@ -269,10 +312,24 @@
Timestamp
Timestamp of value, when the value was sampled or recorded.
 - + +
Thing
+
+ Internet of Things basically consists of Things connected to the Internet. Things can be any device, sensor, actuator etc., that can have an + Internet connection. +
+ + +
Thing Registry
+
+ A registry where Things can register for simple and secure discovery by the owner of the Thing. The registry can also be used as a database for meta information + about Things in the network. +
+ +
Token
- A client, device or user can get a token from a provisioning server. These tokens can be included in requeests to other entities in the network, so these entities can validate + A client, device or user can get a token from a provisioning server. These tokens can be included in requests to other entities in the network, so these entities can validate access rights with the provisioning server.
@@ -369,14 +426,14 @@ from='device@clayster.com/device' to='provisioning@clayster.com' id='13'> - + - + ]]>

@@ -384,7 +441,7 @@

Note: In many cases, an address to a provisioning server might be preprogrammed during production of the - device. In these cases, parts of the above procedure may not neccessary. All the client needs to do, if the provisioning server is not available + device. In these cases, parts of the above procedure may not be necessary. All the client needs to do, if the provisioning server is not available in the roster of the device, is to send a subscription request to the provisioning server, to alert the server of the existence of the device, and possibly request a device token.

@@ -421,28 +478,28 @@ from='master@clayster.com/amr' to='device@clayster.com' id='15'> - + - + - + - + ]]> @@ -464,14 +521,14 @@ from='device@clayster.com/device' to='provisioning@clayster.com' id='1'> - + - + ]]>

@@ -498,14 +555,14 @@ from='device@clayster.com/device' to='provisioning@clayster.com' id='2'> - + - + ]]> @@ -529,7 +586,7 @@ - + ]]> @@ -545,7 +602,7 @@ - + ]]>

@@ -563,10 +620,11 @@

- Note: This use case is an extension of the use case 'Read-out rejected' in the XEP sensor-data. + Note: This use case is an extension of the use case 'Read-out rejected' in the XEP-0323 + Internet of Things - Sensor Data.

- The following example shows the communication first between the client and the device, then the device and the provisioning server, and last between the device and the client: + The following example shows the communication first between the client and the device, then between the device and the provisioning server, and last between the device and the client:

- + - + - + - + Access denied. ]]> -

- Note that the provisioning server responds with a canReadResponse element, with the same content as the canRead element in the request. -

@@ -613,14 +668,15 @@

- Note: This use case is an extension of the use case 'Read-out of multiple devices' in the XEP sensor-data. + Note: This use case is an extension of the use case 'Read-out of multiple devices' in the XEP-0323 + Internet of Things - Sensor Data.

Note 2: If the server responds, but without specifying a list of nodes, the device can assume that all nodes available in the original request are allowed to be read. If no nodes in the request are allowed to be read, the provisioning server must respond with a result='false', so the device can reject the read-out request.

- The following example shows the communication first between the client and the device, then the device and the provisioning server, and last between the device and the client: + The following example shows the communication first between the client and the device, then between the device and the provisioning server, and last between the device and the client:

@@ -629,7 +685,7 @@ from='master@clayster.com/amr' to='device@clayster.com' id='5'> - + @@ -639,7 +695,7 @@ from='device@clayster.com/device' to='provisioning@clayster.com' id='6'> - + @@ -649,7 +705,7 @@ from='provisioning@clayster.com' to='device@clayster.com/device' id='6'> - + @@ -658,7 +714,7 @@ from='device@clayster.com' to='master@clayster.com/amr' id='5'> - + ]]>

@@ -680,7 +736,7 @@ to be sent. If no fields in the request are allowed to be sent, the provisioning server must respond with a result='false', so the device can reject the read-out request.

- The following example shows the communication first between the client and the device, then the device and the provisioning server, and last between the device and the client: + The following example shows the communication first between the client and the device, then between the device and the provisioning server, and last between the device and the client:

@@ -689,21 +745,21 @@ from='master@clayster.com/amr' to='device@clayster.com' id='7'> - + - + - + @@ -713,7 +769,7 @@ from='device@clayster.com' to='master@clayster.com/amr' id='7'> - + ]]>

@@ -721,7 +777,7 @@ the fields allowed to be sent are listed. The client must only send fields having field names in this list.

- Also note, that the provisioning server can return both lists of allowed nodes and allowed field names in the response. In this case, the device must only send allowed fields + Also note, that the provisioning server can return a list of both allowed nodes and allowed field names in the response. In this case, the device must only send allowed fields from allowed nodes, and ignore all other fields and/or nodes.

@@ -737,15 +793,15 @@

- The following example shows the communication first between the client and the device, then the device and the provisioning server, and last between the device and the client: + The following example shows the communication first between the client and the device, then between the device and the provisioning server, and last between the device and the client:

- + @@ -754,7 +810,7 @@ from='device@clayster.com/device' to='provisioning@clayster.com' id='1'> - + @@ -763,14 +819,14 @@ from='provisioning@clayster.com' to='device@clayster.com/device' id='1'> - + - + ]]> @@ -789,15 +845,15 @@ The same is true for parameters: If the provisioning server does not specify parameters in the response, the caller can assume all parameters are allowed.

- The following example shows the communication first between the client and the device, then the device and the provisioning server, and last between the device and the client: -

- - + + - + @@ -810,7 +866,7 @@ from='concentrator@clayster.com/plc' to='provisioning@clayster.com' id='2'> - + @@ -823,7 +879,7 @@ from='provisioning@clayster.com' to='concentrator@clayster.com/plc' id='2'> - + @@ -833,46 +889,46 @@ from='concentrator@clayster.com' to='master@clayster.com/amr' id='19'> - + ]]> - -

- Note that the provisioning server responds with a canControlResponse element, similar to the canControl element in the request, except - only the nodes allowed to be controlled are included. The device must only permit control of nodes listed in the response from the provisioning server. Other nodes available - in the request should be ignored. -

-

- Also note, that the restricted set of nodes and/or parameters returned from the provisioning server must be returned to the original caller, so it can - act on the information that only a partial control action was allowed and taken. -

- - -

- In case the provisioning server wants to limit the control parameters a client can control in a device, the provisioning server has the possibility to grant - control access, but list a set of parameters the client is allowed to control in the corresponding device. -

-

- - -

-

- Note: If the server responds, but without specifying a list of nodes, the device can assume that all nodes available in the original request are allowed - to be controlled. If no nodes in the request are allowed to be controlled, the provisioning server must respond with a result='false', so the device can reject the read-out request. - The same is true for parameters: If the provisioning server does not specify parameters in the response, the caller can assume all parameters are allowed. -

-

- The following example shows the communication first between the client and the device, then the device and the provisioning server, and last between the device and the client: -

+ +

+ Note that the provisioning server responds with a canControlResponse element, similar to the canControl element in the request, except + only the nodes allowed to be controlled are included. The device must only permit control of nodes listed in the response from the provisioning server. Other nodes available + in the request should be ignored. +

+

+ Also note, that the restricted set of nodes and/or parameters returned from the provisioning server must be returned to the original caller, so it can + act on the information that only a partial control action was allowed and taken. +

+ + +

+ In case the provisioning server wants to limit the control parameters a client can control in a device, the provisioning server has the possibility to grant + control access, but list a set of parameters the client is allowed to control in the corresponding device. +

+

+ + +

+

+ Note: If the server responds, but without specifying a list of nodes, the device can assume that all nodes available in the original request are allowed + to be controlled. If no nodes in the request are allowed to be controlled, the provisioning server must respond with a result='false', so the device can reject the read-out request. + The same is true for parameters: If the provisioning server does not specify parameters in the response, the caller can assume all parameters are allowed. +

+

+ The following example shows the communication first between the client and the device, then between the device and the provisioning server, and last between the device and the client: +

- + @@ -888,7 +944,7 @@ from='plc@clayster.com/plc' to='provisioning@clayster.com' id='3'> - + @@ -904,7 +960,7 @@ from='provisioning@clayster.com' to='plc@clayster.com/plc' id='3'> - + @@ -916,7 +972,7 @@ from='plc@clayster.com' to='master@clayster.com/amr' id='20'> - + @@ -929,7 +985,7 @@ the parameters allowed to be sent are listed. The device must only control parameters included in this list.

- Also note, that the provisioning server can return both lists of allowed nodes and allowed parameter names in the response back to the client, so it can + Also note, that the provisioning server can return a list of both allowed nodes and allowed parameter names in the response back to the client, so it can act on the information that only a partial control action was allowed and taken.

@@ -955,14 +1011,14 @@ from='provisioning@clayster.com/provisioning' to='device@clayster.com' id='17'> - + - + ]]> @@ -978,14 +1034,14 @@ from='service@clayster.com/service' to='provisioning@clayster.com' id='14'> - + - + ]]> @@ -1070,7 +1126,7 @@

The provisioning server receives these credentials, and decides if the user should have access to the service or not, based on rules configured in the provisioning service. - If the user is granted access, a userToken is generated and returned to the service. This token + If the user is granted access, a userToken is generated and returned to the service.

Now, the service can determine if this access grant is sufficient or not. It can require the user to login into the service first. If so, the service should provide the provisioning @@ -1084,7 +1140,7 @@ from='service@clayster.com/service' to='provisioning@clayster.com' id='9'> - + @@ -1095,14 +1151,14 @@ from='provisioning@clayster.com' to='service@clayster.com/service' id='9'> - + - + ]]> @@ -1121,7 +1177,7 @@ using an invisible, but common, root privilege.

- The following table suggests some examples of Privilge IDs, with suggestive descriptions. (Only used as an example.) + The following table suggests some examples of Privilege IDs, with suggestive descriptions. (Only used as an example.)

@@ -1182,14 +1238,14 @@ from='service@clayster.com/service' to='provisioning@clayster.com' id='10'> - + - + ]]> @@ -1216,7 +1272,7 @@ from='service@clayster.com/service' to='provisioning@clayster.com' id='11'> - + @@ -1227,40 +1283,44 @@ from='provisioning@clayster.com' to='service@clayster.com/service' id='11'> - + - + - + - + - + ]]> +

+ Note: If the user or service has not been correctly identified, logged in, etc., the resulting list must only include privileges + that default users that are not logged in can have. This list can be empty. +

-

If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:sn:provisioning" in response to &xep0030; information requests.

+

If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:iot:provisioning" in response to &xep0030; information requests.

... - + ... ]]> @@ -1345,10 +1405,11 @@

All examples in this document have been simplified examples where a few devices containing a few fields have been read. However, in many cases large subsystems with - very many sensors containing many fields have to be read, as is documented in xep-0000-SN-Concentrators.html - xep-0000-SN-Concentrators.html. In such cases, a node may have to be specified using two or perhaps + very many sensors containing many fields have to be read, as is documented in Internet of Things - Concentrators + Internet of Things - Concentrators. In such cases, a node may have to be specified using two or perhaps even three ID's: a sourceId identifying the data source controlling the device, a possible cacheType narrowing down the search to - a specific kind of node, and the common nodeId. For more information about this, see xep-0000-SN-Concentrators.html. + a specific kind of node, and the common nodeId. For more information about this, see + Internet of Things - Concentrators.

Note: For cases where the nodeId is sufficient to uniquely identify the node, it is sufficient to provide this attribute in the request. @@ -1383,7 +1444,7 @@

  • Multiple provisioning servers could be allowed, for redundancy or for scalability. This specification does not limit the number of provisioning servers used in a network, - not used by a device. Examples use only one provisioning server for simplicity. + not used by a device. Examples in this specification use only one provisioning server for simplicity.
  • Generally, take care what kind of provisioning servers you allow in a network. @@ -1394,21 +1455,22 @@

    This document requires no interaction with &IANA;.

    -

    REQUIRED.

    - -     +

    + The protocol schema needs to be added to the list of XMPP protocol schemas. +

    + - + @@ -1664,7 +1726,31 @@ ]]> - -

    Thanks to Joachim Lindborg and Karin Forsell for all valuable feedback.

    -     + +

    + For more information, please see the following resources: +

    +
      +
    • +

      + The Sensor Network section of the XMPP Wiki contains further information about the + use of the sensor network XEPs, links to implementations, discussions, etc. +

      +
      • +
    • +

      + The XEP's and related projects are also available on github, thanks to Joachim Lindborg. +

      +
      • +
    • +

      + A presentation giving an overview of all extensions related to Internet of Things can be found here: + http://prezi.com/esosntqhewhs/iot-xmpp/. +

      +
      • +
    +     + +

    Thanks to Joachim Lindborg, Karin Forsell, Tina Beckman and Teemu Väisänen for all valuable feedback.

    +