Web of Things (WoT) Architecture 1.1

Ready for review. The WD will be updated shortly based on branch architecture-1.1-pre-cr-wd

Braw mornin' TAG!

I'm requesting a TAG review of Web of Things (WoT) Architecture 1.1

The W3C WoT formally describes the interfaces of IoT devices and platforms to ease integration across IoT ecosystems and application domains. Rich metadata based on URIs, hypermedia controls, and collaborative schema definitions allows clients to adapt to the peculiarities of a given IoT platform by configuring its protocol stack.

The WoT Architecture document serves as an umbrella for all WoT specifications, and sets the general goals of the W3C Web of Things. It defines the abstract architecture and the design space for current and future WoT building blocks, which are specified in separate documents.

Explainer¹ (minimally containing user needs and example code): WoT Architecture Explainer11.md
Specification URL:
Tests: Draft Implementation Report
User research: WoT Use Cases and Requirements
Security and Privacy self-review²: https://github.com/w3c/wot-architecture/blob/main/publication/ver11/security_and_privacy.md
GitHub repo (if you prefer feedback filed there): https://github.com/w3c/wot-architecture
Primary contacts (and their relationship to the specification):
- Michael Lagally (mlagally), Oracle, editor
- Ryuichi Matsukura (mryuichi), Fujitsu, editor
- Kunihiko Toumura (k-toumura), Hitachi, editor
- Michael McCool (mmccool), Intel, co-chair
- Sebastian Kaebisch (sebastiankb), Siemens, co-chair
Organization(s)/project(s) driving the specification: WoT WG
Key pieces of existing multi-stakeholder review or discussion of this specification:
External status/issue trackers for this specification (publicly visible, e.g. Chrome Status):

Further details:

[x] I have reviewed the TAG's Web Platform Design Principles
Relevant time constraints or deadlines: CR Transition planned for 30 August 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):
Major unresolved issues with or opposition to this specification:
This work is being funded by:

You should also know that...

Security and Privacy Questionnaire was done for WoT as a whole, but answers call out individual deliverables as appropriate.

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

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

Thanks for the review request, and apologies for the delay. Being unfamiliar with the Web of Things work previously, I have done my best to review the set of related specs (Architecture, Description, Discovery, and security and privacy documentation) as thoroughly as possible.

We discussed this during our meeting today, and this feedback represents TAG consensus.

Security & Privacy

Overall we are happy with the direction, and really appreciate the extensive security and privacy work that has been done. Treating all Thing Descriptions as if they contain PII is a sensible precaution. Making the Security and Privacy considerations normative makes a strong statement, though we'd like to know how you have been testing these requirements for conformance purposes?

The spec refers normatively to the Security and Privacy Guidelines, but this is a NOTE, not a normative document and so can't be used as a normative reference. Are you planning to republish the Guidelines at some point (as it seems to have been updated since its last publication)? Also the Security Best Practices document appears to currently be unpublished - what status are you planning to give to this? How does it relate to the Guidelines?

Architecture

Regarding the Architecture specification specifically, the vast majority of the text is non-normative, and, while interesting and useful, we are not sure is appropriate for a REC-track document. Further, you have sections marked as non-normative (eg. 8. Abstract WoT System Architecture) which contain normative MUSTs and SHOULDs.

Some of these statements could be moved to other REC-track documents - eg. regarding Thing Descriptions - if the relevant documents don't already make the same statements.

Some seem to be entirely unnecessary - eg. in 8.1.2 Links, that "Things MUST be hosted on networked system components [..]". Apologies if this has been misunderstood, but this seems more of a foundational premise than a feature to test for conformance purposes.

Some are redundant - eg. in 12.1.1 Thing Description Private Security Data Risk, "MUST ensure that only Public Security Metadata is ever stored" and "MUST ensure that no Private Security Data is included" seem to be saying the same thing from different directions.

There are a number of normative references to non-normative documents - in one case to a document index rather than any specific specification - which need to be made into informative references.

Having reviewed all of the MUSTs and SHOULDs in the specification, our thought is to break the Security and Privacy sections into a separate, fully normative, Security and Privacy document. Then, to work through the remaining normative statements to see which are strictly necessary (ie. for interop, and testable) and of those which can fit in existing REC-track documents. The remainder of the Architecture document would work well as an informative NOTE, which provides additional background and context without implementers needing to sift through it to find what they actually need to design and build conforming Things.

We recognise that you've only asked us to review the difference between 1.0 and 1.1, and this kind of feedback is coming as a result of me personally not having been involved in the earlier review. However, given comments [1, 2] about how hard this has been to review, we'd say it's never too late (or too early) to make specifications more readable! We would be more than happy to re-review if this change is made.

[1] 2022-05-19 PING minutes

[2] 2019-07-11 previous TAG review comment

Compatibility

We can see a lot of work to survey the current (and, presumably, ever-changing) landscape of IoT devices, and the effort to bring fragmented ways of operating together. Can you summarise, or link to a summary of, what the compatibility story looks like in practice? Eg. what widely used devices would be compatible with this architecture out of the box? Or what would needed to be added to make them compatible? What is practically possible with what is out there today, if this suite of specs are published as-is? A few concrete examples would be really nice to help give us a better picture of the ecosystem.

Bonus points

From an editorial perspective, implementers who are approaching this set of specifiations for the first time may be deterred by the volume of text. In particular where sections or paragraphs do not relate to specific, implementable requirements. The specification abstracts are all rather long and we think all of the specs would benefit from a thorough proof-read, with an eye to removing redundant text, simplifying language, removing filler, and overall shortening throughout. While background and context are useful, we would encourage containing such sections in their own documents, which may be optionally read, and keeping only the informative language that is really crucial for implementation in the specifications themselves.

We remain naturally concerned about the potential for abuse using internet-connected devices, most of which are in some way very personal even where they might be part of a large network, in a smart city or similar. The Web can further amplify such threats, or make them easier to carry out. We recognise that there is only so much that can be done in a technical specification and that ultimately you have little control over how malicious people or groups might use or mis-use devices or networks. That said, if members of the WG could find time to work through the Societal Impact Questionnaire, we would be very interested to see some discussion or notes on some or all of the questions from the WoT context. This is a draft document, and a work in progress, and filling it in is not a requirement for progressing the TAG review. (Feedback on the questionnaire itself, additional questions, etc, are all welcome too.)

Thanks again for your work. We anticipate closing this and the related issues, but await your acknowledgement of our feedback and an indication of your next steps.

Response from WoT Security TF:

The "Security Best Practices" document was meant to contain a set of non-normative statements about security such as the best version of TLS to use, when to use it, etc. but these have been superseded by the normative statements about these in the current version of the deliverables (TD, Architecture, Discovery, and Profiles). We were going to update the "Security Best Practices" document but as it seems redundant at this point will remove reference to this document by the CR transition. ACTION: Remove references to "Security Best Practices" in normative documents. Update: the latest Editor's drafts of all deliverables no longer have direct references to this document. The "Security and Privacy Guidelines" document does, however, and should be updated to remove them. See wot-security issue 208.
The "Security and Privacy Guidelines" document was unfortunately not defined as a normative deliverable in our last charter. We might want to consider making it normative in our next charter and consolidating normative assertions about security and privacy in it, but can't do so according to our current charter. It's true this document has not been updated in a while but it currently makes general statements which are still correct. Being informative, we were also planning to update it after the current normative deliverables are in CR but prior to PR. ACTION: Review and update prior to PR transition of other deliverables.
References to "Security and Privacy Guidelines" should note that it is an informative document. ACTION: Update references to ensure that all references to "Security and Privacy Guidelines" are informative.
The "Security and Privacy Guidelines" document however also was also used as a place to put testing recommendations for security. In general we will be reviewing assertions prior to CR transition and making sure they are testable statements about implementations and not statements about policy. For example, a statement about "Identifiers SHOULD be rotated" should probably be "Implementations SHOULD provide a means to rotate identifiers." We would like to somehow make statements about recommended policies but these are hard to test in an implementation as they depend on usage of systems not available at release time (unfortunately). But at least we can make sure the suggested policy is possible. ACTION: Review and update security and privacy assertions so they are testable statements about implementations.

Dear TAG members,

thanks again for your extensive review.

@rhiaro We will work through the soceital impact questionnaire: https://github.com/w3c/wot-architecture/issues/807 Is there a Markdown version of the questionnaire?

We will address your review comments in individual issues, these are tracked with a dedicated label: https://github.com/w3c/wot-architecture/labels/address%20TAG%20feedback

Hi @mlagally - the Societal Impacts Questionnaire is at the moment on the outside an html doc, but on the inside markdown, so you can take the text from this page for markdown versions of the headings and descriptions for each question.

@mmccool Thank you for your comprehensive responses about the Security and Privacy documents, I really appreciate you taking the time to explain that and highlight actions. That all sounds like a positive direction.

Based on the responses to feedback, and assuming adequate discussion of and resolution to the open issues (linked by github above) that will track the various points, I'm going to close this review request. If you do any major restructuring and think it would be helpful for us to re-review at some point, please do open another review request. I will continue to follow the progress you make on the open issues with interest, and hope that your work progresses smoothly.

w3ctag / design-reviews