Skip to content

Commit

Permalink
Move securing mechanism requirements into separate section.
Browse files Browse the repository at this point in the history
  • Loading branch information
@msporny
msporny committed Dec 26, 2023
1 parent 788f9ae commit 8e50c75
Showing 1 changed file with 91 additions and 83 deletions.
174 changes: 91 additions & 83 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1990,90 +1990,13 @@ <h3>Securing Mechanisms</h3>
This specification recognizes two classes of securing mechanisms: those that use
enveloping proofs and those that use embedded proofs. An
<dfn class="export">enveloping proof</dfn> is one that wraps a serialization of
this data model. One such enveloping proof mechanism is JSON Web Token,
which is elaborated on in the [[[VC-JOSE-COSE]]] [[VC-JOSE-COSE]]
specification. An <dfn class="export">embedded proof</dfn> is a mechanism where
the proof is included in the data model, using the extension point
defined in Section <a href="#proofs"></a>. One such embedded proof mechanism
this data model. One such enveloping proof mechanism is elaborated on in the
[[[VC-JOSE-COSE]]] [[VC-JOSE-COSE]] specification. An
<dfn class="export">embedded proof</dfn> is a mechanism where
the proof is included in the data model. One such embedded proof mechanism
is [[[VC-DATA-INTEGRITY]]] [[VC-DATA-INTEGRITY]]. These two classes of securing
mechanisms are not mutually exclusive.
</p>

<p>
Securing mechanism specifications other than those
referred to above might also be defined, as necessary.
</p>

<p>
Securing mechanism specifications MUST document normative algorithms that
provide content integrity protection for [=conforming documents=]. The
algorithms MAY be general in nature and MAY be used to secure data other than
[=conforming documents=].
</p>

<p>
Securing mechanism specifications MUST provide a verification mechanism that
returns only the information in the [=conforming document=] that has been
secured, without any securing mechanism information included, such as `proof` or
JOSE/COSE metadata. Specifications MAY provide additional mechanisms to convey
other information that might be helpful (for example, during validation or for debugging
purposes), such as securing mechanism metadata. A securing mechanism's
verification algorithm MUST provide an interface that receives a sequence of
bytes ([=byte sequence=] |inputBytes|) or a document ([=map=] |inputDocument|)
and a media type ([=string=] |inputMediaType|) as inputs and returns a
verification result with at least the following [=struct/items=]:
</p>

<dl>
<dt>[=boolean=] |status|</dt>
<dd>
A verification status whose value is `true` if the verification succeeded and
`false` if it did not.
</dd>
<dt>[=map=] |document|</dt>
<dd>
A document that only contains information that was successfully secured.
</dd>
<dt>[=string=] |mediaType|</dt>
<dd>
A media type as defined in [[RFC6838]].
</dd>
<dt>[=string=] |controller|</dt>
<dd>
A verification method controller as defined in [[VC-CONTROLLER-DOCUMENT]].
</dd>
<dt>[=map=] |controllerDocument|</dt>
<dd>
A controller document as defined in [[VC-CONTROLLER-DOCUMENT]].
</dd>
</dl>

<p>
Securing mechanism specifications SHOULD provide integrity protection for any
information referenced by a URL that is critical to validation. Mechanisms that
can achieve this protection are discussed in Section
<a href="#integrity-of-related-resources"></a> and Section
<a href="#base-context"></a>.
</p>

<p>
Securing mechanism specifications SHOULD register the securing mechanism in the
<a data-cite="?VC-SPECS#securing-mechanisms">Securing Mechanisms</a> section
of the [[[?VC-SPECS]]] [[?VC-SPECS]].
</p>

<p class="note"
title="Choice of securing mechanism is use-case dependent">
There are multiple acceptable securing mechanisms, and this specification does
not mandate any particular securing mechanism for use with
[=verifiable credentials=] or [=verifiable presentations=].
The Working Group that produced this specification did standardize two
securing mechanism options, which are:
[[[VC-DATA-INTEGRITY]]] [[VC-DATA-INTEGRITY]] and [[[VC-JOSE-COSE]]]
[[VC-JOSE-COSE]]. Other securing mechanisms that are known to the community
can be found in the
<a data-cite="?VC-SPECS#securing-mechanisms">Securing Mechanisms</a> section
of the [[[?VC-SPECS]]] [[?VC-SPECS]].
mechanisms are not mutually exclusive. Securing mechanism specifications other
than those referred to previously might also be defined, as necessary.
</p>

</section>
Expand Down Expand Up @@ -4046,6 +3969,91 @@ <h3>Verifiable Credential Graphs</h3>
</p>
</section>

<section>
<h3>Securing Mechanism Specifications</h3>

<p>
As described in Section <a href="#securing-mechanisms"></a>, there are
multiple strategies that an implementer can use when securing a
<a>conforming document</a>. In order to maximize utility and interoperability,
specification authors that desire to author new ways of securing
<a>conforming documents</a> are provided with the guidance in this section.
</p>

<p>
Securing mechanism specifications MUST document normative algorithms that
provide content integrity protection for [=conforming documents=]. The
algorithms MAY be general in nature and MAY be used to secure data other than
[=conforming documents=].
</p>

<p>
Securing mechanism specifications MUST provide a verification mechanism that
returns only the information in the [=conforming document=] that has been
secured, without any securing mechanism information included, such as `proof` or
JOSE/COSE metadata. Specifications MAY provide additional mechanisms to convey
other information that might be helpful (for example, during validation or for
debugging purposes), such as securing mechanism metadata. A securing mechanism's
verification algorithm MUST provide an interface that receives a sequence of
bytes ([=byte sequence=] |inputBytes|) or a document ([=map=] |inputDocument|)
and a media type ([=string=] |inputMediaType|) as inputs and returns a
verification result with at least the following [=struct/items=]:
</p>

<dl>
<dt>[=boolean=] |status|</dt>
<dd>
A verification status whose value is `true` if the verification succeeded and
`false` if it did not.
</dd>
<dt>[=map=] |document|</dt>
<dd>
A document that only contains information that was successfully secured.
</dd>
<dt>[=string=] |mediaType|</dt>
<dd>
A media type as defined in [[RFC6838]].
</dd>
<dt>[=string=] |controller|</dt>
<dd>
A verification method controller as defined in [[VC-CONTROLLER-DOCUMENT]].
</dd>
<dt>[=map=] |controllerDocument|</dt>
<dd>
A controller document as defined in [[VC-CONTROLLER-DOCUMENT]].
</dd>
</dl>

<p>
Securing mechanism specifications SHOULD provide integrity protection for any
information referenced by a URL that is critical to validation. Mechanisms that
can achieve this protection are discussed in Section
<a href="#integrity-of-related-resources"></a> and Section
<a href="#base-context"></a>.
</p>

<p>
Securing mechanism specifications SHOULD register the securing mechanism in the
<a data-cite="?VC-SPECS#securing-mechanisms">Securing Mechanisms</a> section
of the [[[?VC-SPECS]]] [[?VC-SPECS]].
</p>

<p class="note"
title="Choice of securing mechanism is use-case dependent">
There are multiple acceptable securing mechanisms, and this specification does
not mandate any particular securing mechanism for use with
[=verifiable credentials=] or [=verifiable presentations=].
The Working Group that produced this specification did standardize two
securing mechanism options, which are:
[[[VC-DATA-INTEGRITY]]] [[VC-DATA-INTEGRITY]] and [[[VC-JOSE-COSE]]]
[[VC-JOSE-COSE]]. Other securing mechanisms that are known to the community
can be found in the
<a data-cite="?VC-SPECS#securing-mechanisms">Securing Mechanisms</a> section
of the [[[?VC-SPECS]]] [[?VC-SPECS]].
</p>

</section>

</section>

<section>
Expand Down

0 comments on commit 8e50c75

Please sign in to comment.