Security, WoT Scripting API doc: security failures

[ereshetova]

The WoT Scripting document should mention in respective places that while one can invoke all the methods in the API in order to achieve listed use cases, some of them may fail (fully or return only partial results) due to security restrictions. It also should emphasis of the importance for scripts to be ready for such security-failures and handle them at least safely.

I would propose to define a single (unless anyone has requirements to separate different cases of security errors or expose lower-level security errors up to the WoT level) security-related error in the scripting doc and each API should state if it is possible to get this error in return and why:

For example, the invokeAction() method from ComsumedThing interface might easily return a security-error if the client does not posses correct credentials.

Also, for some methods it should be explained that while they do not return any security-related errors, the results that they return might be limited because of some security restrictions:

For example, the discover() method might return only partial results for the actually present WoT Things around due to some security limitations (some devices won't reply to discovery broadcast, etc. ).

I think it is important to specify how each API behaves with regards to security that WoT developers can write their scripts correctly.

[ereshetova]

For your review: @zolkis, @mmccool

[zolkis]

We will address this when writing the algorithms for the methods. Thanks for the review.

[ereshetova]

And on related note: do we want to have a way for limiting for example discovery of a thing on a WoT level. For example, when a script exposes a new thing using the ExposedThing interface, should it be able to limit the discovery of this thing?

[zolkis]

when a script exposes a new thing using the ExposedThing interface, should it be able to limit the discovery of this thing?

The TD should support discoverable flag for that, which it does not. Given that, limiting discovery itself would be against the web principles, I think. If a Thing does not want to be discovered, then it should not respond to broadcast discovery requests, and should not register to a directory. Direct discovery (retrieve) is still possible, but if the requester does not have proper credentials, it could be handled in a clandestine way by not giving any answer - it depends on the Thing implementation.

If the Thing wants selective discovery (only clients fulfilling some criteria could discover), it is application territory. We should not provide a mechanism for that, since it would be hard to support on all underlying protocols.

Did you also have in mind to show a different Thing depending on a policy like security clearance? I think this is application territory with multiple TDs created for the use case, and in the WG we don't necessarily want to standardize (and protect) this.

@mkovatsc any opinion on this?

[ereshetova]

Indeed this might have two cases:

• selective discovery: only to subset of clients fulfilling certain criteria should be able to discover this thing. An example of this case is only authorized clients for the user's smart home should be able to see and discover available devices and not some random guest and/or some worker fixing the house.
  Having it implemented in the app layer most probably would be fine, I just want people to think of it and have a vision on how it can be done (and potentially try it out), to make sure it is possible to support case like this, since I can see this to be a useful use case from security POV.

• "variate" discovery (don't know what would be a proper name): depending if the client is authorized or not (might also have different authorization groups in really complex cases), the discovered Thing might be different (show different properties, provide different amount of information). For this one I cannot now think of use cases that would not be already possible with just access controls on the interfaces that Thing exposes. Only maybe to limit potentially privacy-related information from discoverable devices? But then you can always just make them discoverable only by authorized devices, like in the other example above. So, unless someone has a good use cases for this one, I would drop it.

[zolkis]

Thanks! So it seems we can drop the "limiting discovery" sub-topic for the moment. Perhaps the Architecture spec or Security note could mention the possible solutions to this use case, but scripting does not support it for now.

Error handling is still a gap in the spec.

[mkovatsc]

@zolkis For the F2F session, could you please prepare a list of functions that may return errors and which might need to be propagated over the network (e.g., using appropriate HTTP response codes)?

[zolkis]

General error handling is slightly larger scope than security error handling that is the topic of this issue.
In principle, we will deal with errors during the algorithm definitions, which we don't have yet.
Mapping of scripting Errors (to be defined) to HTTP response codes is definitely too early to do.
However, as general guidelines,

• All methods can fail for security/permission reasons with a SecurityError.
• All methods involving network communication can fail with a NetworkError where the error code is transparently carried in the error.message.
• All methods that accept parameters may fail with TypeError, RangeError, SyntaxError, URIError.
• All methods can fail because runtime errors, e.g. using InternalError.

Synchronous methods will throw an Error, asynchronous ones will reject their Promise with an Error.

[zolkis]

Comments from the F2F:

• we should expose error information already provided by the network
• but we should not expose more information to the scripts.

The first means we need to create WoT specific errors, for instance WoTSecurityError would extend SecurityError with underlying error codes (5xx, 4xx etc) and possibly links to resolve the error condition.

[zolkis]

Should be fixed by now with the past several PR's.
Please check in the current version of the spec and close this if satisfied.

[relu91]

I would close the issue for inactivity. It seems that the current document is mentioning security failures in different places. Re-open if needed.