Add integrity protection (proof section) to TDs

[mmccool]

A "proof" section, like in DIDs, should be added to TDs to protect their integrity. This is important if we want to do things like refer to public keys, etc. from inside TDs; we don't want a man-in-the-middle to spoof that information.

[mmccool]

See also https://w3c-ccg.github.io/ld-proofs/, which are designed for JSON-LD files, and are what DID document integrity proofs are based on.

[mmccool]

I think we agree we should adopt a common standard for signing json-ld documents. However, we should review the proposed json-ld signing spec above (ld-proofs) to ensure it has the "right stuff".

[mmccool]

As noted in the proposed new section 7.4 in the security guidelines document, there are alternatives like JWS that might be considered for "external" signing. These might make sense in the content of a directory service (that might return a TD that does not have "intrinsic" signatures like in ld-proofs). This might also apply when a directory returns part of TD, e.g. the result of a query.

[mmccool]

I will work on a PR for this... using ld-proofs... will see if I can do it in time for the TD 1.1 FPWD, if it's optional then it can be backward-compatible.

[mmccool]

Created an issue in the TD repo where it belongs... will follow up there. Already given the TD group a heads-up also. w3c/wot-thing-description#940

[mmccool]

PR Available, but WIP, need to resolve relationship to DID ontology, etc. Should consider what steps we need to complete this (for TD 2.0), and also a testing/implementation plan.

[mmccool]

So this PR is now obsolete and will have to be redone, and of course we'll have to deal with canonicalization.

[mmccool]

Discussed in APA call the need for "progressive disclosure" in many circumstances. This is related to the general idea of returning different variants of TDs to different users. This shows up in at least the following use cases:

• Providing different documentation to different kinds of users (developers, consumers)
• Providing documentation in different languages (already an internationalization requirement in TD 1.0)
• Omitting detailed documentation in machine-to-machine contexts over constrained communication channels (e.g. factory automation)
• Omitting interactions that a particular user does not have rights to (e.g. when sending a TD to an end user, we may want to omit the admin sub-api they don't have rights to access)
• Adding metadata (e.g. last-updated times in a directory for discovery)
• Adding derived or inferred information (e.g. geolocation, upon installation of a device, or for a portable device, when relocated)
• Adding proxy information and a proxy security scheme (when a TD is proxied)
• Modifying or adding URLs, possibly with different protocols (for a shadow copy in handled by a hub)

So the question is... how do we handle signing in this case? Is "proof chaining" sufficient? This does imply that a "master" exists which contains the "original". The above processes can add, delete, or modify information. But in general I won't know what was changed, so in addition to knowing that there was a change, should I have a general mechanism to get access to the original or a diff? Defeats the purpose in some use cases (e.g. hiding information).

[mmccool]

Requirements arising from memory limitations:

• Small devices may only have a small amount of RAM (e.g. 64KB), and even with the profile limits being discussed for TDs (16KB), may not have enough RAM to perform canonicalization (@mlagally is working on a PR in profiles for that process)
• Signing needs canonicalization, which would have to be applied before signing but after a TD template has been filled in (could be dealt with by having template be pre-canonicalized, and filling in templates preserving what is necessary) before a TD is exposed.
• We probably also should minimize the computational complexity of signing...
• Consuming a TD means computing the signature to verify it. If there is no space on the device to canonicalize it, then it MUST be precanonicalized.

The above generally means that profiles will probably have the requirements that TDs and TD templates are stored and transmitted in canonical form, and should be pre-validated.

See https://github.com/w3c/wot-testing/blob/main/events/2021.03.Online/reference/hw.md for a discussion of minimum hardware requirements. One note that is relevant: security requirements should be aligned with hardware acceleration availability.

Use case for consuming TDs on constrained devices needed. One example:

• A light switch (controller) connecting to a light (actuator) using peer-to-peer pairing.
• Process: switch does mDNS discovery, gets TDs from self-describing devices
• Switch would already have to have authorization and keys... (e.g. have gone through an onboarding process and be configured with appropriate keys)
• Determines if a TD is a light by looking for a particular @type (e.g. OneDM class), or the peer-to-peer exploration could support filtering (query parameters)
• OneDM class means there will be a particular property for turning light on and off
• Extract the URL from that property
• Rest of the TD would be ignored and the TD would be processed in a streaming fashion.

Notes:

• UI design would have to be able to deal with multiple lights, but this could be done by going through them one by one and having a UI to let the user confirm this is the one they want
• Would be easier to use if the device can present a web page over the network (already have HTTP stack available, so).

Canonicalization requirements:

• To support streaming processing, parameters (such as @type) that effect the processing of others (e.g. extracting URLs from a property) need to come before them.
• Standardized semantic types and sub-APIs are very useful (having to deal with a lot of different variants is inconvenient)

[mmccool]

TODO:

• Survey hardware accelerators for signing. TD signing should be compatible with hardware support on small devices.

[mmccool]

Need to update proposal. Consistency with available HW acceleration for signing capabilities would be useful (see PR #199); in addition, we have to decide how to populate the namespace for various signing algorithms. The following might be useful for that: https://tools.ietf.org/html/draft-ietf-netconf-crypto-types-18
In addition, we do have some existing names defined, e.g. for tokens, and it would probably also be useful to be consistent with names used by protocols, e.g. HTTP and CoAP. The "alg" examples for token are consistent with jws/jwt/jwe, and it makes sense (since a TD is a JSON object) for signing to use jwe, etc. We can start with LD-PROOFS (https://w3c-ccg.github.io/ld-proofs/#linked-data-signatures) but don't need to be constrained by it.

[mmccool]

Signing should also require:

1. Canonicalization. Signing a TD is also asserting that it has been canonicalized.
2. Validation. Signing a TD is also asserting that it has been validated.

[mmccool]

Signature type? If we could have only one, what should it be?
@Citrullin I suggest SHA256 (cryptographic hash) combined with ECDSA signatures (note: elliptic curve, so compute required, regardless SW implementation is ok for small devices, but there are also lots of cheap HW implementation, e.g. you can get chips for $0.60)

[Citrullin]

There is a small list for crypto ICs.

[mmccool]

So... different elliptic curves can be used with ECDSA/EdDSA. Let's further specify the curve: NIST-P256, which is widely supported in HW as well. However, this is not perfect, and there are other ones that could be used in the future. Not everyone will agree on which sig is best (for example, X25519/Curve25519), so maybe we should allow multiple signatures (with different cryptosuites) as well. We might be able to deal with this with a small update (to the TD spec... 1.2?) in 2022 or so. Alternatively we just wait for 2.0 (and LDS) in 2023. We could also list both NIST-P256 and X25519 (and if they are at risk, and we can't test both, then we just drop one...). These two curves should cover the needs of most communities. And it turns out the SW implementations of X25519 are pretty fast, so...