Web of Things (WoT) Security Ontology

W3C Editor's Draft

More details about this document
This version:
https://www.w3.org/2019/wot/security
Latest published version:
none
Latest editor's draft:
https://www.w3.org/2019/wot/security
Editors:
Victor Charpenay
Michael McCool
Ontology in RDF
Web of Things (WoT) Security Ontology in RDF

Abstract

This document introduces an RDF vocabulary for the security metadata definitions. This vocabulary provides a stable namespace IRI for security keywords, as well as simple axioms, defined against schema.org's meta-model. Examples on how to use the vocabulary are also introduced.

Status of This Document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the Web of Things Working Group as an Editor's Draft.

Publication as an Editor's Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 03 November 2023 W3C Process Document.

1. Introduction

This documents provides an ontology of a selection of well-established security mechanisms that are directly built into protocols eligible as Protocol Bindings for W3C WoT or are widely in use with those protocols. The current set of HTTP security schemes is partly based on OpenAPI 3.0.1 (see also [OPENAPI]). However while the HTTP security schemes, Vocabulary, and syntax given in this specification share many similarities with OpenAPI, they are not compatible.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

3. Terminology

The fundamental WoT terminology such as Thing, Consumer, Thing Description (TD), Interaction Model, Interaction Affordance, Property, Action, Event, Protocol Binding, Servient, etc. is defined in Section 3 of the WoT Architecture specification [WOT-ARCHITECTURE].

The Thing Description terminology such as TD Information Model, TD Document, Term (Vocabulary Term), TD Context Extension etc. is defined in Section 3 of the WoT Thing Description specification [WOT-THING-DESCRIPTION].

4. Axiomatization

4.1 Classes

4.1.1 APIKeySecurityScheme

IRI: https://www.w3.org/2019/wot/security#APIKeySecurityScheme

API key authentication security configuration identified by the term apikey (i.e., "scheme": "apikey"). This scheme is to be used when the access token is opaque, for example when a key in a proprietary format is provided by a cloud service provider. In this case the key may not be using a standard token format. This scheme indicates that the key provided by the service provider needs to be supplied as part of service requests using the mechanism indicated by the "in" field.
Sub-class of wotsec:SecurityScheme
In the domain of wotsec:in
wotsec:name

4.1.2 AutoSecurityScheme

IRI: https://www.w3.org/2019/wot/security#AutoSecurityScheme

An automatic authentication security configuration identified by the term auto (i.e., "scheme": "auto"). This scheme indicates that the security parameters are going to be negotiated by the underlying protocols at runtime, subject to the respective specifications for the protocol (e.g. [RFC8288] for Basic Authentication when using HTTP).
Sub-class of wotsec:SecurityScheme

4.1.3 BasicSecurityScheme

IRI: https://www.w3.org/2019/wot/security#BasicSecurityScheme

Basic authentication security configuration identified by the term basic (i.e., "scheme": "basic"), using an unencrypted username and password.
Sub-class of wotsec:SecurityScheme
In the domain of wotsec:in
wotsec:name

4.1.4 BearerSecurityScheme

IRI: https://www.w3.org/2019/wot/security#BearerSecurityScheme

Bearer token authentication security configuration identified by the term bearer (i.e., "scheme": "bearer"). This scheme is intended for situations where bearer tokens are used independently of OAuth2. If the oauth2 scheme is specified it is not generally necessary to specify this scheme as well as it is implied. For format, the value jwt indicates conformance with RFC7519, jws indicates conformance with RFC7797, cwt indicates conformance with RFC8392, and jwe indicates conformance with !RFC7516, with values for alg interpreted consistently with those standards. Other formats and algorithms for bearer tokens MAY be specified in vocabulary extensions.
Sub-class of wotsec:SecurityScheme
In the domain of wotsec:alg
wotsec:authorization
wotsec:format
wotsec:in
wotsec:name

4.1.5 ComboSecurityScheme

IRI: https://www.w3.org/2019/wot/security#ComboSecurityScheme

A combination of other security schemes identified by the Vocabulary Term combo (i.e., "scheme": "combo"). Elements of this scheme define various ways in which other named schemes defined in securityDefinitions, including other ComboSecurityScheme definitions, are to be combined to create a new scheme definition. Exactly one of either oneOf or allOf MUST be included. Only security scheme definitions which can be used together can be combined with allOf. For example, it is not possible in general to combine different OAuth 2.0 flows together using allOf unless one applies to a proxy and one to the endpoint. Note that when multiple named security scheme definitions are listed in a security field the same semantics apply as in an allOf combination (and the same limitations on allowable combinations). The oneOf combination is equivalent to using different security schemes on forms that are otherwise identical. In this sense a oneOf scheme is not an essential feature but it does avoid redundancy in such cases.

Sub-class of wotsec:SecurityScheme
In the domain of wotsec:allOf
wotsec:oneOf

4.1.6 DigestSecurityScheme

IRI: https://www.w3.org/2019/wot/security#DigestSecurityScheme

Digest authentication security configuration identified by the term digest (i.e., "scheme": "digest"). This scheme is similar to basic authentication but with added features to avoid man-in-the-middle attacks.
Sub-class of wotsec:SecurityScheme
In the domain of wotsec:in
wotsec:name
wotsec:qop

4.1.7 NoSecurityScheme

IRI: https://www.w3.org/2019/wot/security#NoSecurityScheme

A security configuration corresponding to identified by the term nosec (i.e., "scheme": "nosec"), indicating there is no authentication or other mechanism required to access the resource.
Sub-class of wotsec:SecurityScheme

4.1.8 OAuth2SecurityScheme

IRI: https://www.w3.org/2019/wot/security#OAuth2SecurityScheme

OAuth 2.0 authentication security configuration for systems conformant with [RFC6749] and [RFC8252], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). For the code flow both authorization and token MUST be included. For the client flow token MUST be included. For the client flow authorization MUST NOT be included. The mandatory elements for each flow are summarized in the following table:

Element code client
authorization mandatory omit
token mandatory mandatory
refresh optional optional
Sub-class of wotsec:SecurityScheme
In the domain of wotsec:authorization
wotsec:flow
wotsec:refresh
wotsec:scopes
wotsec:token

4.1.9 PSKSecurityScheme

IRI: https://www.w3.org/2019/wot/security#PSKSecurityScheme

Pre-shared key authentication security configuration identified by the term psk (i.e., "scheme": "psk"). This is meant to identify that a standard is used for pre-shared keys such as TLS-PSK [rfc4279], and that the ciphersuite used for keys will be established during protocol negotiation.
Sub-class of wotsec:SecurityScheme
In the domain of wotsec:identity

4.1.10 SecurityScheme

IRI: https://www.w3.org/2019/wot/security#SecurityScheme

Metadata describing the configuration of a security mechanism. The value assigned to the name scheme MUST be defined within a Vocabulary included in the Thing Description, either in the standard Vocabulary defined in § 5. TD Information Model or in a TD Context Extension.

For all security schemes, any keys, passwords, or other sensitive information directly providing access MUST NOT be stored in the TD and should instead be shared and stored out-of-band via other mechanisms. The purpose of a TD is to describe how to access a Thing if and only if a Consumer already has authorization, and is not meant be used to grant that authorization.

Each security scheme object used in a TD defines a set of requirements to be met before access can be granted. We say a security scheme is satisfied when all its requirements are met. In some cases requirements from multiple security schemes will have to be met before access can be granted.

Security schemes generally may require additional authentication parameters, such as a password or key. The location of this information is indicated by the value associated with the name in, often in combination with the value associated with name. The in name can take one of the following values:

header:
The parameter will be given in a header provided by the protocol, with the name of the header provided by the value of name.
query:
The parameter will be appended to the URI as a query parameter, with the name of the query parameter provided by name.
body:
The parameter will be provided in the body of the request payload, with the data schema element used provided by name. When used in the context of a body security information location, the value of name MUST be in the form of a JSON pointer [RFC6901] relative to the root of the input DataSchema for each interaction it is used with. Since this value is not a fragment identifier, and is not relative to the root of the TD but to whichever data schemas the security scheme is bound to, this value should not start with "#"; it is a "pure" JSON pointer. Since this value is not a fragment identifier, it also does not need to URL-encode special characters. The targeted element may or may not already exist at the specified location in the referenced data schema. If it does not, it will be inserted. This avoids having to duplicate definitions in the data schemas of every interaction. When an element of a data schema indicated by a JSON pointer indicated in a body locator does not already exist in the indicated schema, it MUST be possible to insert the indicated element at the location indicated by the pointer.. For example, pointing to a key of a Map where that key does not exist in the corresponding Data Schema, the key and its value, which is the credential, would be inserted to the Map at the specified location during the operation execution. On the other hand, pointing to an Array's item with a number as the item index, that number should be outside the range of the Array's already specified items in order to not alter the strict sequence of items. The JSON pointer used in the body locator MAY use the "-" character to indicate a non-existent array element when it is necessary to insert an element after the last element of an existing array. The element referenced (or created) by a body security information location MUST be required and of type "string". If name is not given, it is assumed the entire body is to be used as the security parameter.
cookie:
The parameter is stored in a cookie identified by the value of name.
uri:
The parameter is embedded in the URI itself, which is encoded in the relevant interaction using a URI template variable defined by the value of name. This is more general than the query mechanism but more complex. The value uri SHOULD be specified for in in a security scheme only if query is not applicable. The URIs provided in interactions where a security scheme using uri MUST be a URI template including the defined variable.
auto:
The location is determined as part of the protocol, or negotiated. If a value of auto is set for the in field of a SecurityScheme, then the name field SHOULD NOT be set. In this case, the application of the SecurityScheme is subject to the respective specification for the given protocol (e.g. [RFC8288] when using the BasicSecurityScheme with HTTP).
If multiple parameters are needed for a security scheme, repeat the security scheme definition for each parameter and combine them using a combo security scheme and allOf. In some cases parameters may not actually be secret but a user may wish to leave them out of the TD to help protect privacy. As an example of this, some security mechanisms require both a client identifier and a secret key. In theory, the client identifier is public however it may be hard to update and pose a tracking risk. In such a case it can be provided as an additional security parameter so it does not appear in the TD.

The names of URI variables declared in a SecurityScheme MUST be distinct from all other URI variables declared in the TD.

Super-class of wotsec:APIKeySecurityScheme
wotsec:AutoSecurityScheme
wotsec:BasicSecurityScheme
wotsec:BearerSecurityScheme
wotsec:ComboSecurityScheme
wotsec:DigestSecurityScheme
wotsec:NoSecurityScheme
wotsec:OAuth2SecurityScheme
wotsec:PSKSecurityScheme
In the domain of wotsec:proxy
td:description
td:descriptionInLanguage
td:hasConfigurationInstance

4.2 Object Properties

4.2.1 allOf

IRI: https://www.w3.org/2019/wot/security#allOf

Array of two or more strings identifying other named security scheme definitions, all of which must be satisfied for access.
Domain includes wotsec:ComboSecurityScheme

4.2.2 authorization

IRI: https://www.w3.org/2019/wot/security#authorization

URI of the authorization server.
Domain includes wotsec:BearerSecurityScheme
wotsec:OAuth2SecurityScheme

4.2.3 oneOf

IRI: https://www.w3.org/2019/wot/security#oneOf

Array of two or more strings identifying other named security scheme definitions, any one of which, when satisfied, will allow access. Only one may be chosen for use.
Domain includes wotsec:ComboSecurityScheme

4.2.4 refresh

IRI: https://www.w3.org/2019/wot/security#refresh

URI of the refresh server.
Domain includes wotsec:OAuth2SecurityScheme

4.2.5 token

IRI: https://www.w3.org/2019/wot/security#token

URI of the token server.
Domain includes wotsec:OAuth2SecurityScheme

4.3 Datatype Properties

4.3.1 alg

IRI: https://www.w3.org/2019/wot/security#alg

Encoding, encryption, or digest algorithm.
Domain includes wotsec:BearerSecurityScheme

4.3.2 in

IRI: https://www.w3.org/2019/wot/security#apikeyIn

Specifies the location of security authentication information.
Domain includes wotsec:APIKeySecurityScheme

4.3.3 flow

IRI: https://www.w3.org/2019/wot/security#flow

Authorization flow.
Domain includes wotsec:OAuth2SecurityScheme

4.3.4 format

IRI: https://www.w3.org/2019/wot/security#format

Specifies format of security authentication information.
Domain includes wotsec:BearerSecurityScheme

4.3.5 identity

IRI: https://www.w3.org/2019/wot/security#identity

Identifier providing information which can be used for selection or confirmation.
Domain includes wotsec:PSKSecurityScheme

4.3.6 in

IRI: https://www.w3.org/2019/wot/security#in

Specifies the location of security authentication information.
Domain includes wotsec:BasicSecurityScheme
wotsec:BearerSecurityScheme
wotsec:DigestSecurityScheme

4.3.7 name

IRI: https://www.w3.org/2019/wot/security#name

Name for query, header, cookie, or uri parameters.
Domain includes wotsec:APIKeySecurityScheme
wotsec:BasicSecurityScheme
wotsec:BearerSecurityScheme
wotsec:DigestSecurityScheme

4.3.8 proxy

IRI: https://www.w3.org/2019/wot/security#proxy

URI of the proxy server this security configuration provides access to. If not given, the corresponding security configuration is for the endpoint.
This feature is at risk.
Domain includes wotsec:SecurityScheme
Range includes

4.3.9 qop

IRI: https://www.w3.org/2019/wot/security#qop

Quality of protection.
This feature is at risk.
Domain includes wotsec:DigestSecurityScheme

4.3.10 scopes

IRI: https://www.w3.org/2019/wot/security#scopes

Set of authorization scope identifiers provided as an array. These are provided in tokens returned by an authorization server and associated with forms in order to identify what resources a client may access and how. The values associated with a form should be chosen from those defined in an OAuth2SecurityScheme active on that form.
This feature is at risk.
Domain includes wotsec:OAuth2SecurityScheme

4.4 Annotation Properties

No AnnotationProperty found in the ontology.

5. Usage Examples

5.1 Extended Configuration

A. References

A.1 Normative references

[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[rfc4279]
Pre-Shared Key Ciphersuites for Transport Layer Security (TLS). P. Eronen, Ed.; H. Tschofenig, Ed.. IETF. December 2005. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4279
[RFC6749]
The OAuth 2.0 Authorization Framework. D. Hardt, Ed.. IETF. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6749
[RFC6901]
JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[RFC8252]
OAuth 2.0 for Native Apps. W. Denniss; J. Bradley. IETF. October 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8252
[RFC8288]
Web Linking. M. Nottingham. IETF. October 2017. Proposed Standard. URL: https://httpwg.org/specs/rfc8288.html
[WOT-ARCHITECTURE]
Web of Things (WoT) Architecture. Matthias Kovatsch; Ryuichi Matsukura; Michael Lagally; Toru Kawaguchi; Kunihiko Toumura; Kazuo Kajimoto. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-architecture/
[WOT-THING-DESCRIPTION]
Web of Things (WoT) Thing Description. Sebastian Käbisch; Takuki Kamiya; Michael McCool; Victor Charpenay; Matthias Kovatsch. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-thing-description/

A.2 Informative references

[OPENAPI]
OpenAPI Specification. Darrell Miller; Jeremy Whitlock; Marsh Gardiner; Mike Ralphson; Ron Ratovsky; Uri Sarid; Tony Tam; Jason Harmon. OpenAPI Initiative. URL: https://www.openapis.org/