[security] API key and PSK security schemes are not referenced or explained

[egekorkan]

In contrary to the other security schemes, API key and PSK are not referenced to other specifications that specify them. I thought a W3C recommendation cannot use a non standardized "standard" without properly explaining the way it works? The security guidelines document (https://w3c.github.io/wot-security/) provides no explanation either. In that regard, this has slipped through the review process before publication.

In another regard, if I am reading the TD recommendation for the first time, I have no idea what these security schemes are, when they are used, how they are used or simply where to find more information about them

[mmccool]

@ereshetova and also @OliverPfaff - would be good to comment.

• API key was meant to cover proprietary schemes such as used in Amazon Greengrass, and simply means a key is provided in the URL (we might want to add an example, perhaps using an API template in a TM?).
• PSK was meant for proprietary key-distribution schemes such as used in zero-trust systems, e.g. by Google, and also in OT contexts like smart factories. This basically means a certificate exists that is used by TLS etc. but is set up out-of-band.

We should at least explain the purpose of these better; I agree that they are underspecified, and we should include the above examples at a minimum. If anyone can suggest any references it would be helpful.

[mmccool]

Here are some possible references (but web pages; not sure if there are "normative" references in the usual sense, which may or may not be an issue):

• API keys
  • Amazon: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-setup-api-key-with-console.html
  • Google: https://developers.google.com/maps/documentation/javascript/get-api-key
  • Microsoft: https://docs.microsoft.com/en-us/learn/modules/control-authentication-with-apim/
• PSK - Preshared Keys
  • https://en.wikipedia.org/wiki/Pre-shared_key
  • https://en.wikipedia.org/wiki/TLS-PSK

"API key" is kind of a marketing term, since it depends on other technologies. In a sense these are "security patterns" widely used in industry, rather than "standards". However, we do know that Amazon, etc. will use a combination of technologies in a certain way. Google and Amazon, however, will use different combinations of technologies. So this is still useful to identify expectations in a consumer... To make this more complete we MIGHT also want to identify the "vendor ecosystem" - so we MAY need some additional information to make this complete. Right now it does specify where the API key can be found, though. Our understanding at the time that this would be enough to cover all the different vendor ecosystems, though, since they provide the encoded API key, and the consumer just has to present it when needed.

For PSK, there are also some variants (see TLS-PSK, there are multiple ciphersuites... which identifies the flavor, e.g. symmetric keys, or authenticated key exchange, etc). IANA is a good source for the names of these ciphersuites: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4

HOWEVER, it seems the PSK scheme is missing the ciphersuite used, which would be a useful addition (it is, however, provided during TLS negotiation). I think if we added this information it would be a non-breaking change, since it would be ignored by earlier implementations and resolved via negotiation. However, we also need to go back and look at previous discussion; we might have left this out to reduce complexity, and depend on existing TLS/DTLS negotiation mechanisms.

[mmccool]

TODOs:

• Create a PR to at least add some of the above discussion and references to the current document.
• Look at Amazon, Google, and Microsoft ecosystems to ensure that API key spec above covers all of them (ideally testing would cover IoT devices or services implemented using all three)

[egekorkan]

I agree with the added explanations. I think that we have to specify how they are used since they are very common but not standardized (like JSON Schema).

Also, API Key is sadly used a lot in URIs but there is no way to describe them in TDs yet. This is not a TM related problem though, there should never be a TD that gets generated that has credentials in the URI (A TM implies that a TD should be generated from it).

Related to #923

[mmccool]

Regarding API keys in URIs, yes, the idea is that you would NOT put these in the TD. However, the apikey scheme has a "name" parameter and you can also say it is "in" the "query". Our intention in this case was that the actual URI would be formed with an additional query parameter of the form ?name="key" appended to the URI.

Further points:

1. This intention should be explained better in the spec. Actually the "in" and "query" options show up in other places, too.
2. Maybe we should be using a URI template instead (the security scheme spec predated them, so they were not considered at the time we wrote these up).
3. The spec should clearly state that the API key itself should not be "baked into" the TD.

[mmccool]

There is also issue #923. Here there is an API key being used, but it is actually appended to the URL rather than being a query parameter. This would not fall under the "in" with "query" pattern, but needs a NEW pattern (perhaps "template", and then "name" would be used to identify the name of the template parameter).

You could ALSO handle the "query" pattern this way but (a) I'd rather not remove things already in the spec if I can help it (b) the "query" pattern covers a common use case in a less verbose way than the proposed "template" pattern would.

[egekorkan]

but needs a NEW pattern (perhaps "template", and then "name" would be used to identify the name of the template parameter).

I would say that this is needed. I would be supporting the template

[mmccool]

So the above PR #1031 I think addresses this issue and so I recommend that this issue be closed (if the current explanations are good enough).

[egekorkan]

They are definitely better but I, personally, still do not understand what PSK describes. The only implementation for it was by @mkovatsc and there is only one example at https://w3c.github.io/wot-thing-description/#example-mylampthing-with-coap-protocol-binding maybe we can at least point to it?

[JKRhb]

(I hope it is okay to add the first part here, otherwise I would open another issue for that.)

Dealing with the APIKeySecurityScheme, I got the impression that the name parameter should rather be mandatory, as otherwise there is no way of knowing where to actually put the key. I think name is actually mandatory in OpenAPI (see https://swagger.io/docs/specification/2-0/authentication/api-keys/), but I am not entirely sure.

Regarding the PSK scheme: Maybe the use of this Scheme for CoAPS could be added as an example/explanation? I think this is probably the most relevant scenario at the moment. It seems to me as if TLS-PSK is not (that well?) supported by HTTPS implementations, right?

[mmccool]

I think we should close this issue, as the main issue has been addressed. There are a few new comments but these should be followed up in new, more specific issues. A few final comments, however:

• using TLS-PSK (and mTLS) should not really matter to HTTP since it runs on top of the secure channel; setting up TLS is technically not part of HTTP itself
• CoAPS is likewise on top of a secure channel, and typically uses DTLS, but DTLS is just TLS with a few extra features to allow it to work with UDP. In particular we still want to cite the relevant TLS standards for PSK. Anyway, the current text for PSK should be appropriate for both HTTPS and CoAPS. As for testing it... yeah, we need to do that. Probably this will be marked as at-risk but we SHOULD have some implementations, especially in factory automation, that set up certs in advance for a closed network.

[mmccool]

I also just checked and the current implementation report records two PSK implementations, and three for API key. So we're good for testing.

[sebastiankb]

from today's TD call, decided to close

@mmccool please reopen this issue if you think this issue is not solved yet