Skip to content

Commit

Permalink
Merge pull request #1945 from w3c/assertion-alignment
Browse files Browse the repository at this point in the history 
Assertion id alignment
  • Loading branch information
@mjkoster
mjkoster authored Jan 17, 2024
2 parents b0fc385 + 77a9a70 commit 6a469f8
Show file tree
Hide file tree
Showing 4 changed files with 117 additions and 117 deletions.
80 changes: 40 additions & 40 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1807,7 +1807,7 @@ <h2>Security Vocabulary Definitions</h2>
<dt><code>body</code>:</dt>
<dd>The parameter will be provided in the body of the request payload, with the data schema element
used provided by <code>name</code>.
<span class="rfc2119-assertion" id="sec-body-name-json-pointer">When used in the context of a
<span class="rfc2119-assertion" id="td-security-body-name-json-pointer">When used in the context of a
<code>body</code> security information location, the value of <code>name</code>
MUST be in the form of a JSON pointer [[!RFC6901]] relative to
the root of the input <code>DataSchema</code> for each interaction it is used with.</span>
Expand All @@ -1819,17 +1819,17 @@ <h2>Security Vocabulary Definitions</h2>
The targeted element may or may not already exist at the specified location in the referenced object or array schema (consequently the mechanism is not applicable to simple types).
If it does not, it will be inserted. This avoids having to duplicate definitions in the data schemas of
every interaction.
<span class="rfc2119-assertion" id="sec-body-name-json-pointer-creatable">When an element
<span class="rfc2119-assertion" id="td-security-body-name-json-pointer-creatable">When an element
of a data schema indicated by a JSON pointer indicated in a <code>body</code> 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.</span>
<span class="rfc2119-assertion" id="sec-body-name-json-pointer-array">The JSON pointer
<span class="rfc2119-assertion" id="td-security-body-name-json-pointer-array">The JSON pointer
used in the <code>body</code> locator MAY
use the "<code>-</code>" character to indicate a non-existent array element when
it is necessary to insert an element after the last element of an existing array.
</span>
<span class="rfc2119-assertion" id="sec-body-name-json-pointer-type">The element referenced
<span class="rfc2119-assertion" id="td-security-body-name-json-pointer-type">The element referenced
(or created) by a
<code>body</code> security information location
MUST be required and of type "<code>string</code>".</span>
Expand All @@ -1855,7 +1855,7 @@ <h2>Security Vocabulary Definitions</h2>
</dd>
<dt><code>auto</code>:</dt>
<dd>The location is determined as part of the protocol, or negotiated.
<span class="rfc2119-assertion" id="sec-security-vocab-auto-in-no-name">If a value of <code>auto</code>
<span class="rfc2119-assertion" id="td-security-security-vocab-auto-in-no-name">If a value of <code>auto</code>
is set for the <code>in</code> field of a <code>SecurityScheme</code>,
then the <code>name</code> field SHOULD NOT be set.</span>
In this case, the application of the <code>SecurityScheme</code> is subject to
Expand Down Expand Up @@ -5467,7 +5467,7 @@ <h3>Data Schemas</h3>
<ul>
<li>
<span class="rfc2119-assertion"
id="client-data-schema">
id="td-client-data-schema">
A <a>Consumer</a> when interacting with another target <a>Thing</a>
described in a WoT Thing Description MUST generate data
organized according to the data schemas given in the corresponding
Expand All @@ -5476,14 +5476,14 @@ <h3>Data Schemas</h3>
</li>
<li>
<span class="rfc2119-assertion"
id="server-data-schema">
id="td-server-data-schema">
A WoT Thing Description MUST accurately describe the
data returned and accepted by each interaction.
</span>
</li>
<li>
<span class="rfc2119-assertion"
id="server-data-schema-extras">
id="td-server-data-schema-extras">
A <a>Thing</a> MAY return additional data from an interaction
even when such data is
not described in the data schemas given in its WoT Thing Description.
Expand All @@ -5494,7 +5494,7 @@ <h3>Data Schemas</h3>
</li>
<li>
<span class="rfc2119-assertion"
id="client-data-schema-accept-extras">
id="td-client-data-schema-accept-extras">
A <a>Consumer</a> when interacting with another <a>Thing</a> MUST accept without
error any additional data
not described in the data schemas given in the Thing Description of the target <a>Thing</a>.
Expand All @@ -5505,22 +5505,22 @@ <h3>Data Schemas</h3>
</li>
<li>
<span class="rfc2119-assertion"
id="client-data-schema-no-extras">
id="td-client-data-schema-no-extras">
A <a>Consumer</a> when interacting with another <a>Thing</a> MUST NOT generate data
not described in the data schemas given in the Thing Description of that <a>Thing</a>.
</span>
</li>
<li>
<span class="rfc2119-assertion"
id="client-uri-template">
id="td-client-uri-template">
A <a>Consumer</a> when interacting with another <a>Thing</a> MUST generate URIs
according to the URI Templates, base URIs, and form href parameters
given in the Thing Description of the target <a>Thing</a>.
</span>
</li>
<li>
<span class="rfc2119-assertion"
id="server-uri-template">
id="td-server-uri-template">
URI Templates, base URIs, and href members
in a WoT Thing Description MUST accurately describe the <a>WoT Interface</a> of the <a>Thing</a>.
</span>
Expand All @@ -5547,12 +5547,12 @@ <h3>Protocol Bindings</h3>
</p>
<ul>
<li>
<span class="rfc2119-assertion" id="bindings-requirements-scheme">
<span class="rfc2119-assertion" id="td-bindings-requirements-scheme">
Every form in a WoT Thing Description MUST follow the requirements of the <a>Protocol Binding</a> indicated by the URI scheme [[!RFC3986]] of its <code>href</code> member.
</span>
</li>
<li>
<span class="rfc2119-assertion" id="bindings-server-accept">
<span class="rfc2119-assertion" id="td-bindings-server-accept">
Every form in a WoT Thing Description MUST accurately describe requests
(including request headers, if present) accepted by the <a>Thing</a> in an
interaction.
Expand Down Expand Up @@ -6851,19 +6851,19 @@ <h2>Derivation of Thing Description Instances</h2>
following steps:
</p>
<ul>
<li> <span class="rfc2119-assertion" id="thing-model-td-generation-processor-imports"> Copy all definitions from the input <a>Thing Model</a> to the resulting <a>Partial TD</a> instance. If used, the extension and imports
<li> <span class="rfc2119-assertion" id="tm-td-generation-processor-imports"> Copy all definitions from the input <a>Thing Model</a> to the resulting <a>Partial TD</a> instance. If used, the extension and imports
feature MUST be resolved and represented in the <a>Partial TD</a> instance according to <a href="#thing-model-extension-import"></a>.</span></li>
<li> <span class="rfc2119-assertion" id="thing-model-td-generation-processor-extends"> If used, <code>links</code> element entry with <code>"rel":"tm:extends"</code> MUST be removed from the current <a>Partial TD</a></span></li>
<li> <span class="rfc2119-assertion" id="thing-model-td-generation-processor-type">The <code>tm:ThingModel</code> value of the top-level <code>@type</code> MUST be removed in the <a>Partial TD</a> instance.</span></li>
<li> <span class="rfc2119-assertion" id="thing-model-td-generation-processor-required">All required interactions (not listed in <code>tm:optional</code>) MUST be taken over to the <a>Partial TD</a> instance.</span> </li>
<li> <span class="rfc2119-assertion" id="thing-model-td-generation-processor-optional"> All optional interactions (listed in <code>tm:optional</code>) MAY be taken over to the <a>Partial TD</a> instance. </span></li>
<li> <span class="rfc2119-assertion" id="thing-model-td-generation-processor-placeholder">If used, all placeholders (see Section <a href="#thing-model-td-placeholder"></a>) in the <a>Thing Model</a> MUST be replaced with a valid corresponding value in the <a>Partial TD</a>.</span></li>
<li> <span class="rfc2119-assertion" id="tm-td-generation-processor-extends"> If used, <code>links</code> element entry with <code>"rel":"tm:extends"</code> MUST be removed from the current <a>Partial TD</a></span></li>
<li> <span class="rfc2119-assertion" id="tm-td-generation-processor-type">The <code>tm:ThingModel</code> value of the top-level <code>@type</code> MUST be removed in the <a>Partial TD</a> instance.</span></li>
<li> <span class="rfc2119-assertion" id="tm-td-generation-processor-required">All required interactions (not listed in <code>tm:optional</code>) MUST be taken over to the <a>Partial TD</a> instance.</span> </li>
<li> <span class="rfc2119-assertion" id="tm-td-generation-processor-optional"> All optional interactions (listed in <code>tm:optional</code>) MAY be taken over to the <a>Partial TD</a> instance. </span></li>
<li> <span class="rfc2119-assertion" id="tm-td-generation-processor-placeholder">If used, all placeholders (see Section <a href="#thing-model-td-placeholder"></a>) in the <a>Thing Model</a> MUST be replaced with a valid corresponding value in the <a>Partial TD</a>.</span></li>
</ul>
<p>
Finally, a TM-to-TD generator will take the resulting <a>Partial TD</a> and transform it into a <a>Thing Description</a> with this last step
</p>
<ul>
<li> <span class="rfc2119-assertion" id="thing-model-td-generation-processor-forms">Missing communication and/or security metadata details MUST be completed in the <a>Thing Description</a> instance based on Section <a href="#security-serialization-json"></a> and/or <a href="#form-serialization-json"></a>.</span></li>
<li> <span class="rfc2119-assertion" id="tm-td-generation-processor-forms">Missing communication and/or security metadata details MUST be completed in the <a>Thing Description</a> instance based on Section <a href="#security-serialization-json"></a> and/or <a href="#form-serialization-json"></a>.</span></li>

</ul>

Expand Down Expand Up @@ -7015,7 +7015,7 @@ <h5>TD Interception and Tampering</h5>
intermediary that can capture or manipulate data.
</p>
<dl><dt>Mitigation:</dt><dd>
<span class="rfc2119-assertion" id="security-mutual-auth-td">
<span class="rfc2119-assertion" id="td-security-mutual-auth-td">
Thing Descriptions SHOULD be obtained only through
mutually authenticated secure channels.
</span>
Expand All @@ -7024,7 +7024,7 @@ <h5>TD Interception and Tampering</h5>
identity of the other party to the communication.
However, mutual authentication also can be used to identify the
Consumer, which may be undesirable in some cases (privacy risk).
<span class="rfc2119-assertion" id="security-server-auth-td">
<span class="rfc2119-assertion" id="td-security-server-auth-td">
In cases where the Consumer is associated
with a person, e.g. browsers, TDs MAY be obtained
through a channel where only the TD provider is authenticated.
Expand Down Expand Up @@ -7062,7 +7062,7 @@ <h5>Context Interception and Tampering</h5>
"plain" HTTP URLs.
However, the HTTP protocol is vulnerable to interception and modification if
used without first establishing a secure transport channel using TLS.
<!-- <span class="rfc2119-assertion" id="security-context-secure-fetch"> -->
<!-- <span class="rfc2119-assertion" id="td-security-context-secure-fetch"> -->
If it is necessary to fetch a context definition file,
an implementation should first attempt to use HTTP over TLS
even when only an HTTP URL is given.
Expand All @@ -7087,7 +7087,7 @@ <h5>Limited Duration Accesses</h5>
<dl>
<dt>Mitigations:</dt>
<dd>
<span class="rfc2119-assertion" id="security-oauth-limits">
<span class="rfc2119-assertion" id="td-security-oauth-limits">
To limit the scope and duration of access to Things, tokens SHOULD
be used to manage access.
</span>
Expand Down Expand Up @@ -7123,12 +7123,12 @@ <h5>Vulnerability Auditing</h5>
in which the information is made available, and to whom it is made available to.
Ideally, only those with the rights to access the Things
described by TDs should get access to those TDs.
<span class="rfc2119-assertion" id="sec-vuln-auto">
<span class="rfc2119-assertion" id="td-security-vuln-auto">
The <code>auto</code> security scheme MAY be used if vulnerability
scanning is a concern.</span>
</dd></dl>
</section>
<section id="sec-security-consideration-script-injection">
<section id="td-security-consideration-script-injection">
<h5>Script Injection</h5>
<p>Many strings given in TDs, in particular the values carried in
<code>title</code>/<code>titles</code>
Expand Down Expand Up @@ -7166,7 +7166,7 @@ <h5>Script Injection</h5>
internationalization purposes,
for example to set the initial direction of text rendering in
bidirectional text.
<span class="rfc2119-assertion" id="sec-inj-no-intl-markup">
<span class="rfc2119-assertion" id="td-security-inj-no-intl-markup">
HTML markup SHOULD NOT be used for internationalization purposes in TD strings.
</span>

Expand All @@ -7182,7 +7182,7 @@ <h5>JSON Parsing</h5>
when executed, could have side effects compromising the security of a system.
<dl>
<dt>Mitigation:</dt>
<dd><span class="rfc2119-assertion" id="security-no-execution">
<dd><span class="rfc2119-assertion" id="td-security-no-execution">
A WoT Thing Description JSON-LD serialization MUST NOT be passed through a
code execution mechanism such as JavaScript's <code>eval()</code>
function to be parsed.
Expand All @@ -7209,7 +7209,7 @@ <h5>JSON-LD Expansion</h5>
<dl>
<dt>Mitigation:</dt>
<dd>
<span class="rfc2119-assertion" id="security-jsonld-expansion">
<span class="rfc2119-assertion" id="td-security-jsonld-expansion">
<a>Consumers</a> SHOULD
set and enforce limits on
memory usage to prevent buffer overflow and resource exhaustion
Expand Down Expand Up @@ -7267,11 +7267,11 @@ <h5>Context Fetching</h5>
and support only a limited set of domain-specific extensions.
The set of supported extensions can be established by a
WoT Profile [[WOT-PROFILE]], for example.
<span class="rfc2119-assertion" id="security-static-context">
<span class="rfc2119-assertion" id="td-security-static-context">
Constrained implementations SHOULD use vetted
versions of their supported context extensions
managed statically or as part of a secure update process.</span>
<span class="rfc2119-assertion" id="security-remote-context">
<span class="rfc2119-assertion" id="td-security-remote-context">
Constrained implementations SHOULD NOT follow links to remote contexts.
</span>
In this case the URLs are used only to identify extensions,
Expand All @@ -7291,7 +7291,7 @@ <h5>Immutable Identifiers</h5>
</p>
<dl><dt>Mitigation:</dt><dd>
<p>
<span class="rfc2119-assertion" id="privacy-mutable-identifiers">
<span class="rfc2119-assertion" id="td-privacy-mutable-identifiers">
All identifiers used in a TD SHOULD be mutable,
and in particular there SHOULD be a mechanism to update the <code>id</code>
of a <a>Thing</a> when necessary.
Expand All @@ -7313,7 +7313,7 @@ <h5>Immutable Identifiers</h5>
of the change in identifier when a change is made.
Note however that some classes of devices, e.g., medical devices,
may require immutable IDs by law in some jurisdictions.
<!-- <span class="rfc2119-assertion" id="privacy-immutable-id-as-property"> -->
<!-- <span class="rfc2119-assertion" id="td-privacy-immutable-id-as-property"> -->
Ideally, any required immutable identifiers should only be
made available via affordances, such as a property, whose value can
only be obtained after appropriate authentication and
Expand All @@ -7340,11 +7340,11 @@ <h5>Fingerprinting</h5>
identifiable person, such as a medical condition.
</p>
<dl><dt>Mitigation:</dt><dd>
<span class="rfc2119-assertion" id="privacy-auth-users-only">
<span class="rfc2119-assertion" id="td-privacy-auth-users-only">
Only authorized users SHOULD be provided access
to the Thing Description for a <a>Thing</a>.
</span>
<span class="rfc2119-assertion" id="privacy-essential-metadata-only">
<span class="rfc2119-assertion" id="td-privacy-essential-metadata-only">
Only the amount of
information needed for the level of authorization and the use case
SHOULD be provided in a TD.
Expand Down Expand Up @@ -7377,11 +7377,11 @@ <h5>ID Metadata</h5>
could be used to infer personal information.
</p>
<dl><dt>Mitigation:</dt><dd>
<span class="rfc2119-assertion" id="privacy-id-metadata">
<span class="rfc2119-assertion" id="td-privacy-id-metadata">
The value of the <code>id</code> of a TD SHOULD NOT contain metadata
describing the Thing or from the TD itself.
</span>
<span class="rfc2119-assertion" id="privacy-temp-id-metadata">
<span class="rfc2119-assertion" id="td-privacy-temp-id-metadata">
Any temporary ID generated to manage TDs, for example an ID for a database
or directory service, SHOULD NOT contain metadata
describing the Thing or from the TD itself.
Expand All @@ -7405,11 +7405,11 @@ <h5>Globally Unique Identifiers</h5>
design; for example, by detecting duplicates and regenerating IDs when necessary.
The scope of IDs also does not need to be global: it is acceptable to use identifiers
that only distinguish Things in a certain context, such as within a home or factory.
<span class="rfc2119-assertion" id="privacy-distributed-ids">
<span class="rfc2119-assertion" id="td-privacy-distributed-ids">
TD identifiers SHOULD be generated using a distributed mechanism such as UUIDs
that provides a high probability of uniqueness.
</span>
<span class="rfc2119-assertion" id="privacy-centralized-ids">
<span class="rfc2119-assertion" id="td-privacy-centralized-ids">
TD identifiers SHOULD NOT be generated using a centralized authority.
</span>
</dd></dl>
Expand Down
Loading

0 comments on commit 6a469f8

Please sign in to comment.