#715: Web of Things (WoT) Thing Description 1.1: TAG and Security Review

Visit on Github.

Opened Feb 14, 2022

Braw mornin' TAG!

I'm requesting a TAG review of the Web of Things (WoT) Thing Description 1.1.

In the WoT Architecture, a Thing is defined as an abstraction of a physical IoT device such as a sensor (temperature, CO2, ...), an actuator (lamp, motor, ...), or a virtual entity (e.g., composition of one or more Things, a weather service). The Thing Description (TD) provides descriptive metadata for a Thing's network interface.

Further details:

  • I have reviewed the TAG's Web Platform Design Principles
  • Relevant time constraints or deadlines:
    • Detailed schedule for all deliverables
    • TD 1.1 proposed milestones:
      • CR Candidate (e.g. including fixes for feedback points): May 1, 2022
      • CR Transition: mid-May, 2022
      • PR Transition: mid-June, 2022
  • The group where the work on this specification is currently being done: WoT WG
  • The group where standardization of this work is intended to be done (if current group is a community group or other incubation venue): WoT WG
  • Major unresolved issues with or opposition to this specification: None (WIP: may want to link to outstanding issues in tracker that have been pushed to TD 2.0)
  • This work is being funded by: members

You should also know that...

In the Thing Description 1.1 specification, text and table entries highlighted with a yellow background will indicate a feature associated with an at-risk assertion for which insufficient implementation experience exists. When an entire section is at-risk the words "This section is at risk." will be placed at the start of the section and highlighted with a yellow background.

There are also some related informative documents:

  • The WoT Binding Templates informative WG Note describes an optional WoT building block. This Note explains how to use the WoT Thing Description for specific IoT protocols.
  • The WoT Scripting API informative WG Note describes an optional WoT building block, and describes a JS API that can be used to implement behaviour in a WoT Thing (exposing a network API described by a WoT Thing Description) or a device consuming (reading) a WoT Thing Description.
  • The WoT Use Cases and Requirements informative WG Note includes a collection of stakeholder-submitted use cases driving requirements.

During the TAG review period, we plan to update the test results in the implementation report to reduce the number of at-risk assertions as much as possible before CR submission. The link above refers to the master branch of the repository, not the TAG-review branch.

We'd prefer the TAG provide feedback as (please delete all but the desired option):

🐛 open issues in our GitHub repo for each point of feedback


WIP! Will delete below only once this issue is complete and the referenced documents are ready for review.

CAREFULLY READ AND DELETE CONTENT BELOW THIS LINE BEFORE SUBMITTING

Please preview the issue and check that the links work before submitting.

In particular, if anything links to a URL which requires authentication (e.g. Google document), please make sure anyone with the link can access the document. We would prefer fully public documents though, since we work in the open.

¹ We require an explainer to give the relevant context for the spec review, even if the spec has some background information. For background, see our explanation of how to write a good explainer. We recommend the explainer to be in Markdown.

² A Security and Privacy questionnaire helps us understand potential security and privacy issues and mitigations for your design, and can save us asking redundant questions. See https://www.w3.org/TR/security-privacy-questionnaire/.

Discussions

2022-04-18

Minutes

Max: only questions I have, seems only to support IP based devices because it .. they can be reached by http.. assumption.. but in real world there are many IoT devices that don't have IP addresses. Not a problem, if this specs puprpose is only to work for IP addressed devices it's fine, but want to mention that in the real world there are many iot devices that don't have IP addresses. Maybe that is a question to be asekd.

Sangwhan: last time I read this it was JSON and IDL things. Is it still the same?

Max: JSON based to describe the properties of the IoT devices. How to get .. and how to control devices, how to get notifications

Sangwhan: Last time I read this document it was more like a protocol document than an API, is that still the case?

Max: I think it's not an API. Kind of a format. Data model to describe IoT devices so the developer can use that data model to automatically gather sensor data. Data format. Not a web platform API. Doesn't require the browser to implement that. Only the IoT devices developer or platform vendors.

Sangwhan: I don't have much to say on this.

Amy: security implications?

Max: they have a security mechanisms .. in the explainer has some.. and in getting started section

Sangwhan: how does the security model work?

Max: in the explainer, very simple example. JSON field with a thing description.. security measures user name and password based. Password in http header I think.

Sangwhan: no origin protection?

Sangwhan: given this device is accessible, what is the CORS equivalent mechanism here? I'm not understanding

Max: different from web platform. In this example the devices is a web server I think. It will have an IP address..

Sanwhan: this device, according to what I see here, has a web server, has https.. does this mean i'ts only accessible locally? Or can you make ..? I think the question is can an arbitrary application make a query to this device and turn off your light?

Max: in my understanding security mechanism is that the light will have password protected and only authorised applications have the password. When you send a query or certain command to the light you should provide the password.

Sangwhan: so if you're accessing this from a weba pplicatin, you have ten lights with ten different passwords, you have to type ten different passwords?

Max: in the spec they have different options. That's one option. Basic authentication option. Also key based security model.

Sangwhan: I don't see anything about auth in the spec, we should ask that question. I don't see how you'd do any reasonable protection here. I don't understand how the interaction with the weba pplications are supposed to work here. Haven't read carefully.

Max: my understanding of how the web applications interacts with iot devices.. the devices have three.. properties, stauts is one example of properties.. the web application can send an http get on the url, status url, to get status whether the light is turned on or off. The second is action - similar, the web application sends http post to the action url. Last one is event - here the if the light has something wrong, that can send a notification to the weba pplication, using the http protocol. The iot devices in the sepc have three services. For other devices it may be different.

Amy: also haven't read closely, but seems like the auth may be orthogonal.. possibly in another spec somewhere

Sangwhan: because it's not defined.. I don't know.. It's saying you consume a url.. no reference to cors in this entire doc, very concerning

Max: this spec doesn't require the web browser to do anything. Ony the iot devices platform vendors should implement this

Sangwhan: why is it called web of things then?

Max: I guess maybe they use semantic web or web technologies to do this..

Amy: looks like a small part of a bigger ecosystem.. other specs that go along with it to make it make more sense, not standalone

Sangwhan: I don't know how many specs they have. Last time I looked at at web of things specs they were more like device to device protocol, nothing to do with the web. Don't know what has changed. I will revisit when I have read the spec.

2022-04-25

Minutes

Max: responded to my question. Seems it's not meant for general web service, but often web services associated with them. This proposal is focussed on IP based as we assumed. Sangwhan had security concerns.

Sangwhan: was curious how the security model works in conjunction with CORS.

Amy: I think that's a question for another spec in the suite of specs - it's orthogonal to the data model

Dan: We have previously reviewed Thing Description.. at that time we were not recording resolution with labels. Hadley closed it in december 2019. We said we don't hvae any relevant feedback on the description language itself - feedback was primarily in the architecture. Unless we think there are major issues in the data model that are architecutral..

Hadley: diff since last version. Looks lightweight. They've added in Thing Model Concept which was an appendix of the previous document. I'm guessing it hasn't changed substantively, but if it has we might need to care.

Dan: I remember David had some issues with the use of JSON-LD..

Sangwhan: I think that's a preference..

Hadley: abstract says JSON format that allows JSON-LD processing

Dan: back in time, David's concern was it should not require a JSON-LD parser in order to be part of the WoT architecture. But something that simply parses json should be able to participate. Suggest we close sastisfied based on already having reviewed previous version. Any other comments we could make?

Hadley: they say in their request for review that their Architecutre is being submitted at the same time, I don't see it yet.

Amy: and they have two other things listed saying they'll be in for review soon. We could wait until the other things come in?

Hadley: I'd prefer to do that

Dan: I can say we'll keep this open until we get the others.. [leaves comment]

2022-06-13

Minutes

Amy: they did one security & privacy review for all... Lots of linked data in these specs. They have been very explicit about no dependency to JSON-LD. "Just JSON"

Yves: There are plenty of JSON-LD parsers around... Shouldn't be an issue. Usually IOT hubs would require processing those. I've run into some devices that have javascript... I have web of things devices...

Amy: one of the things thye've done in the arch document is to make security & privacy sections normative - seems like a good step. ... before plenary [call] I want to go through it and look at what the normative statements are in the arch doc - maybe see if it can be split into 2 documents. One consise normative document and one informative note...

Hadley: explainer section describing diff to 1.0.

Dan: what is a thing model?

Amy: a generalization of a thing... rather than an instance

Dan: why did they not need that in the previous version? Before it was Thing Template...

Dan: can we close thing description as it's a minor update and keep the reviews open for things arch and discovery...

Amy: yes makes sense.

Hadley: yes seconded - doesn't seem like it's a massive change.

Hadley: just re-reviewing the original review we did.

Dan: there are a whole bunch of issues in their repo that are linked from our issue 355 which all appear to be clsoed.

Dan: There is one open issue from our last review of web of things description.

Amy: it's got a label "defer to 2.0"...

Hadley: we could include a mention in our closing comment.

Dan: I think thay makes sense.

Amy: deferred several times though...

Dan: wonder if there's just a disagreement in the group with David's framing?

Hadley: looked at the issues opened against our arch review (355) - looks like they've all been considered... looking at 178...

Amy: if that's on the scripting APi then we're not reviewint it.

Hadley: Ok perfect. writes closing comment for 715

2022-06-20

Minutes

Amy: they responded to Hadley's feedback

Dan: I think they took our feedback on board. We can close this?

Hadley: fine with me