index.html

<!DOCTYPE html>
<html>
<head>
    <title>Verifiable Credential Data Integrity 1.0</title>
    <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
    <!--
      === NOTA BENE ===
      For the three scripts below, if your spec resides on dev.w3 you can check them
      out in the same tree and use relative links so that they'll work offline,
     -->
    <script src='//www.w3.org/Tools/respec/respec-w3c' class='remove'></script>
    <script class='remove' src="./common.js"></script>
    <script class="remove"
      src="https://cdn.jsdelivr.net/gh/digitalbazaar/respec-vc@3.4.2/dist/main.js"></script>

    <script type="text/javascript" class="remove">
      var respecConfig = {
          // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
          specStatus:           "REC",

          // the specification's short name, as in http://www.w3.org/TR/short-name/
          shortName:            "vc-data-integrity",

          // subtitle
          subtitle: "Securing the Integrity of Verifiable Credential Data",

          // if you wish the publication date to be other than today, set this
          publishDate: "2025-5-15",
          //crEnd: "2025-01-19",
          //prEnd: "2025-4-17",

          // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
          // and its maturity status
          // previousPublishDate:  "1977-03-15",
          // previousMaturity:  "WD",

          // if there a publicly available Editor's Draft, this is the link
          edDraftURI:           "https://w3c.github.io/vc-data-integrity/",
          errata:               "https://w3c.github.io/vc-data-integrity/errata.html",

          // if this is a LCWD, uncomment and set the end of its review period
          implementationReportURI: "https://w3c.github.io/vc-data-integrity/implementations/",

          // if you want to have extra CSS, append them to this list
          // it is recommended that the respec.css stylesheet be kept
          //extraCSS:             ["spec.css", "prettify.css"],

          // editors, add as many as you like
          // only "name" is required
          editors: [{
            name: "Manu Sporny", url: "https://www.linkedin.com/in/manusporny/",
            company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/",
            w3cid: 41758
          }, {
            name: "Ted Thibodeau Jr", url: "https://github.com/TallTed",
            company: "OpenLink Software", companyURL: "https://www.openlinksw.com/",
            w3cid: 42501
          }, {
            name: "Ivan Herman", url: "https://www.w3.org/People/Ivan/",
            company: "W3C", companyURL: "https://www.w3.org",
            w3cid: 7382, orcid: "0000-0003-0782-2704"
          }, {
            name: "Dave Longley", url: "https://digitalbazaar.com/",
            company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/",
            w3cid: 48025
          }, {
            name: "Greg Bernstein", url: "https://www.grotto-networking.com/",
            company: "Invited Expert", w3cid: 140479
          }],

          // authors, add as many as you like.
          // This is optional, uncomment if you have authors as well as editors.
          // only "name" is required. Same format as editors.

          authors:  [{
            name: "Dave Longley", url: "https://digitalbazaar.com/",
            company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/",
            w3cid: 48025
          }, {
            name: "Manu Sporny", url: "https://www.linkedin.com/in/manusporny/",
            company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/",
            w3cid: 41758
          }, {
            name: "Ivan Herman", url: "https://www.w3.org/People/Ivan/",
            company: "W3C", companyURL: "https://www.w3.org",
            w3cid: 7382, orcid: "0000-0003-0782-2704"
          }],

          // extend the bibliography entries
          //localBiblio: webpayments.localBiblio,

          // name of the WG
          group:           "vc",

          // name (with the @w3c.org) of the public mailing to which comments are due
          wgPublicList: "public-vc-wg",

          github: "w3c/vc-data-integrity",

          // URI of the patent status for this WG, for Rec-track documents
          // !!!! IMPORTANT !!!!
          // This is important for Rec-track documents, do not copy a patent URI from a random
          // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
          // Team Contact.
          //wgPatentURI:  "",
          maxTocLevel: 3,
          /*preProcess: [ ],
          alternateFormats: [ {uri: "diff-20111214.html", label: "diff to previous version"} ],
          */
          localBiblio:  {
            "DI-EDDSA": {
              title:    "The Edwards Digital Signature Algorithm Cryptosuites v1.0",
              href:     "https://www.w3.org/TR/vc-di-eddsa/",
              authors:  ["David Longley", "Manu Sporny", "Dmitri Zagidulin"],
              status:   "WD",
              publisher:  "W3C Verifiable Credentials Working Group"
            },
            "DI-ECDSA": {
              title:    "The Elliptic Curve Digital Signature Algorithm Cryptosuites v1.0",
              href:     "https://www.w3.org/TR/vc-di-ecdsa/",
              authors:  ["David Longley", "Manu Sporny", "Marty Reed"],
              status:   "WD",
              publisher:  "W3C Verifiable Credentials Working Group"
            },
            "DI-BBSDSA": {
              title:    "The BBS Digital Signature Algorithm Cryptosuites v1.0",
              href:     "https://www.w3.org/TR/vc-di-bbs/",
              authors:  ["Tobias Looker", "Orie Steele"],
              status:   "WD",
              publisher:  "W3C Verifiable Credentials Working Group"
            },
            "JOSE-REGISTRIES": {
              title:    "The JSON Object Signing and Encryption (JOSE) Registries",
              href:     "https://www.iana.org/assignments/jose",
              authors:  ["The Internet Assigned Numbers Authority"],
              status:   "REC",
              publisher:  "The Internet Assigned Numbers Authority"
            },
            "SECURITY-VOCABULARY": {
              title:    "The Security Vocabulary",
              href:     "https://w3id.org/security",
              authors:  ["Ivan Herman", "Manu Sporny","David Longley"],
              status:   "ED",
              publisher:  "Verifiable Credentials Working Group"
            },
            "ZCAP": {
              title:    "Authorization Capabilities for Linked Data",
              href:     "https://w3c-ccg.github.io/zcap-spec/",
              status:   "CGDRAFT",
              publisher:  "Credentials Community Group"
            },
            "MULTIBASE": {
              title: "The Multibase Data Format",
              date: "February 2023",
              href: "https://datatracker.ietf.org/doc/draft-multiformats-multibase",
              authors: [
                "Juan Benet",
                "Manu Sporny"
              ],
              status: "Internet-Draft",
              publisher: "IETF"
            },
            "MULTIHASH": {
              title: "The Multihash Data Format",
              date: "February 2023",
              href: "https://datatracker.ietf.org/doc/draft-multiformats-multihash",
              authors: [
                "Juan Benet",
                "Manu Sporny"
              ],
              status: "Internet-Draft",
              publisher: "IETF"
            },
            "MULTICODEC": {
              title: "The Multi Codec Encoding Scheme",
              date: "February 2022",
              href: "https://github.com/multiformats/multicodec/blob/master/table.csv",
              authors: [
                "The Multiformats Community"
              ],
              status: "Internet-Draft",
              publisher: "IETF"
            },
            "VC-EXTENSIONS": {
              title: "Verifiable Credential Extensions",
              href: "https://w3c.github.io/vc-extensions/",
              authors: [
                "Manu Sporny"
              ],
              status: "ED",
              publisher: "W3C Verifiable Credentials Working Group"
            },
            "DID-KEY": {
              title: "The did:key Method",
              href: "https://w3c-ccg.github.io/did-key-spec/",
              authors: [
                "Manu Sporny",
                "Dmitri Zagidulin",
                "Dave Longley",
                "Orie Steele"
              ],
              status: "CG-DRAFT",
              publisher: "W3C Credentials Community Group"
            },
            "SHA3": {
              title: "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions",
              href: "https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf",
              authors: [
                "National Institute of Standards and Technology",
              ],
              status: "National Standard",
              publisher: "U.S. Department of Commerce"
            },
            "SD-JWT": {
              title:    "Selective Disclosure for JWTs (SD-JWT)",
              href:     "https://datatracker.ietf.org/doc/draft-ietf-oauth-selective-disclosure-jwt/",
              authors: [
                "Daniel Fett",
                "Kristina Yasuda",
                "Brian Campbell"
              ],
              status:   "I-D",
              publisher:  "The IETF OAuth Working Group"
            }
          },
          postProcess: [
            restrictRefs,
            window.respecVc.createVcExamples
          ],
          xref: ["INFRA", "MIMESNIFF", "VC-DATA-MODEL-2.0", "CID"],
          otherLinks: [{
            key: "Related Specifications",
            data: [{
              value: "The Verifiable Credentials Data Model v2.0",
              href: "https://www.w3.org/TR/VC-DATA-MODEL-2.0/"
            }, {
              value: "The Edwards Digital Signature Algorithm Cryptosuites v1.0",
              href: "https://www.w3.org/TR/vc-di-eddsa/"
            }, {
              value: "The Elliptic Curve Digital Signature Algorithm Cryptosuites v1.0",
              href: "https://www.w3.org/TR/vc-di-ecdsa/"
            }, {
              value: "The BBS Digital Signature Algorithm Cryptosuites v1.0",
              href: "https://www.w3.org/TR/vc-di-bbs/"
            }]
          }]
      };
    </script>
    <style>
code {
  color: rgb(199, 73, 0);
  font-weight: bold;
}
pre {
  overflow-x: auto;
  white-space: pre-wrap;
}
pre .highlight {
  font-weight: bold;
  color: Green;
}
pre .subject {
  font-weight: bold;
  color: RoyalBlue;
}
pre .property {
  font-weight: bold;
  color: DarkGoldenrod;
}
pre .comment {
  font-weight: bold;
  color: SteelBlue;
  -webkit-user-select: none;
  -moz-user-select: none;
  -ms-user-select: none;
  user-select: none;
}
ol.algorithm { counter-reset:numsection; list-style-type: none; }
ol.algorithm li { margin: 0.5em 0; }
ol.algorithm li:before { font-weight: bold; counter-increment: numsection; content: counters(numsection, ".") ") "; }

table.simple {
    border-collapse: collapse;
    margin: 25px 0;
    min-width: 400px;
    border: 1px solid #dddddd;
}
table.simple thead tr {
    background-color: #005a9c;
    color: #ffffff;
    text-align: left;
}
table.simple th,
table.simple td {
    padding: 12px 15px;
    vertical-align: top;
    text-align: left;
}
table.simple tbody tr {
    border-bottom: 1px solid #dddddd;
}
table.simple tbody tr:nth-of-type(even) {
    background-color: #00000008;
}
table.simple tbody tr:last-of-type {
    border-bottom: 2px solid #005a9c;
}
    </style>
</head>
<body>
    <section id='abstract'>
      <p>
This specification describes mechanisms for ensuring the authenticity and
integrity of [=verifiable credentials=] and similar types of constrained digital
documents using cryptography, especially through the use of digital
signatures and related mathematical proofs.
      </p>
    </section>

    <section id='sotd'>
      <p>
Comments regarding this specification are welcome at any time.
Please file issues directly on
<a href="https://github.com/w3c/vc-data-integrity/issues/">GitHub</a>,
or send them to
<a href="mailto:public-vc-comments@w3.org">public-vc-comments@w3.org</a>
if that is not possible.
(<a href="mailto:public-vc-comments-request@w3.org?subject=subscribe">subscribe</a>,
<a href="https://lists.w3.org/Archives/Public/public-vc-comments/">archives</a>).
      </p>
    </section>

    <section class="informative">
      <h2>Introduction</h2>
      <p>
This specification describes mechanisms for ensuring the authenticity and
integrity of [=verifiable credentials=] and similar types of constrained digital
documents using cryptography, especially through the use of digital signatures
and related mathematical proofs. Cryptographic proofs enable functionality that
is useful to implementors of distributed systems. For example, proofs can be
used to:
      </p>

      <ul>
        <li>
Make statements that can be shared without loss of trust, because their
authorship can be verified by a third party, for example as part of a
[=verifiable credential=] [[?VC-DATA-MODEL-2.0]], [=verifiable presentation=],
or social media post.
        </li>
        <li>
Authenticate as an entity identified by a particular identifier, for example, as
the subject identified by a Decentralized Identifier (DID) [[?DID]].
        </li>
        <li>
Delegate authorization for actions in a remote execution environment, via
mechanisms such as Authorization Capabilities [[ZCAP]].
        </li>
        <li>
Agree to contracts where the agreement can be verified by another party.
        </li>
        <li>
Additionally, many proofs that are based on cryptographic digital signatures
provide the benefit of integrity protection, making documents and data
tamper-evident.
        </li>
      </ul>

      <section class="informative">
        <h3>How it Works</h3>

        <p>
The operation of Data Integrity is conceptually simple. To create a
cryptographic proof, the following steps are performed: 1) Transformation,
2) Hashing, and 3) Proof Generation.
        </p>

        <figure id="hiw-creation">
          <img style="margin: auto; display: block; width: 100%;"
               src="diagrams/hiw-creation.svg" alt="
Diagram showing the three steps involved in the creation of a cryptographic
proof. The diagram is laid out left to right with a blue box labeled 'Data'
on the far left. The blue box travels, left to right, through three subsequent
yellow arrows labeled 'Transform Data', 'Hash Data', and 'Generate Proof'. The
resulting blue box at the far right is labeled 'Data with Proof'.
               ">
          <figcaption style="text-align: center;">
To create a cryptographic proof, data is transformed, hashed, and
cryptographically protected.
          </figcaption>
        </figure>

        <p>
<dfn>Transformation</dfn> is a process described by a <dfn>transformation
algorithm</dfn> that takes input data and prepares it for the hashing process.
One example of a possible transformation is to take a record of people's names
that attended a meeting, sort the list alphabetically by the individual's family
name, and rewrite the names on a piece of paper, one per line, in sorted order.
Examples of transformations include
<a href="https://en.wikipedia.org/wiki/Canonicalization">canonicalization</a>
and
<a href="https://en.wikipedia.org/wiki/Binary-to-text_encoding">
binary-to-text</a> encoding.
        </p>

        <p>
<dfn>Hashing</dfn> is a process described by a <dfn>hashing algorithm</dfn> that
calculates an identifier for the transformed data using a
<a href="https://en.wikipedia.org/wiki/Cryptographic_hash_function">
cryptographic hash function</a>. This process is conceptually similar to how a
phone address book functions, where one takes a person's name (the input data)
and maps that name to that individual's phone number (the hash). Examples of
cryptographic hash functions include
<a href="https://en.wikipedia.org/wiki/Cryptographic_hash_function#SHA-3">
SHA-3</a> and
<a href="https://en.wikipedia.org/wiki/Cryptographic_hash_function#BLAKE3">
BLAKE-3</a>.
        </p>

        <p>
<dfn class="lint-ignore">Proof Generation</dfn> is a process described by a
<dfn>proof serialization algorithm</dfn> that calculates a value that protects the
integrity of the input data from modification or otherwise proves a certain
desired threshold of trust. This process is conceptually similar to the way a
wax seal can be used on an envelope containing a letter to establish trust in
the sender and show that the letter has not been tampered with in transit.
Examples of proof serialization functions include
<a href="https://en.wikipedia.org/wiki/Digital_signature">
digital signatures</a>,
<a href="https://en.wikipedia.org/wiki/Proof_of_stake">proofs of stake</a>, and
<a href="https://en.wikipedia.org/wiki/Proof_of_knowledge">
proofs of knowledge</a>, in general.
        </p>

        <p>
To verify a cryptographic proof, the following steps are performed:
1) Transformation, 2) Hashing, and 3) Proof Verification.
        </p>

        <figure id="hiw-verification">
          <img style="margin: auto; display: block; width: 100%;"
               src="diagrams/hiw-verification.svg" alt="
Diagram showing the three steps involved in the verification of a cryptographic
proof. The diagram is laid out left to right with a blue box labeled
'Data with Proof' on the far left. The blue box travels, left to right, through
three subsequent yellow arrows labeled 'Transform Data', 'Hash Data', and
'Verify Proof'. The resulting blue box at the far right is labeled 'Data with
Proof'.
               ">
          <figcaption style="text-align: center;">
To verify a cryptographic proof, data is transformed, hashed, and
checked for correctness.
          </figcaption>
        </figure>

        <p>
During verification, the [=transformation=] and [=hashing=] steps are
conceptually the same as described above.
        </p>

        <p>
<dfn class="lint-ignore">Proof Verification</dfn> is a process that is described
by a <dfn>proof verification algorithm</dfn> that applies a cryptographic proof
verification function to see if the input data can be trusted. Possible proof
verification functions include
<a href="https://en.wikipedia.org/wiki/Digital_signature">
digital signatures</a>,
<a href="https://en.wikipedia.org/wiki/Proof_of_stake">proofs of stake</a>, and
<a href="https://en.wikipedia.org/wiki/Proof_of_knowledge">
proofs of knowledge</a>, in general.
        </p>

        <p>
This specification details how cryptographic software architects and
implementers can package these processes together into things called
[=cryptographic suites=] and provide them to application developers for the
purposes of protecting the integrity of application data in transit and at rest.
        </p>

      </section>

      <section class="informative">
        <h3>Design Goals and Rationale</h3>

        <p>
This specification optimizes for the following design goals:
        </p>

        <dl>
          <dt>Simplicity</dt>
          <dd>
The technology is designed to be easy to use for application developers,
without requiring significant training in cryptography. It optimizes for the
following priority of constituencies: application developers over cryptographic
suite implementers, over cryptographic suite designers, over cryptographic
algorithm specification authors.  The solution focuses on sensible defaults to
prevent the selection of ineffective protection mechanisms. See section
[[[#protecting-application-developers]]] and
[[[#versioning-cryptography-suites]]] for further details.
          </dd>
          <dt>Composability</dt>
          <dd>
A number of historical digital signature mechanisms have had monolithic
designs which limited use cases by combining data transformation, syntax,
digital signature, and serialization into a single specification. This
specification layers each component such that a broader range of use cases are
enabled, including generalized selective disclosure and serialization-agnostic
signatures. See section [[[#transformations]]], section [[[#data-opacity]]], and
[[[#versioning-cryptography-suites]]] for further rationale.
          </dd>
          <dt>Resilience</dt>
          <dd>
Since digital proof mechanisms might be compromised without warning due to
technological advancements, it is important that [=cryptographic suites=]
provide multiple layers of protection and can be rapidly upgraded. This
specification provides for both algorithmic agility and cryptographic layering,
while still keeping the digital proof format easy for developers to understand
and use. See section [[[#agility-and-layering]]] to understand the particulars.
          </dd>
          <dt>Progressive Extensibility</dt>
          <dd>
Creating and deploying new cryptographic protection mechanisms is designed to be
a deliberate, iterative, and careful process that acknowledges that extension
happens in phases from experimentation, to implementation, to standardization.
This specification strives to balance the need for an increase in the rate of
innovation in cryptography with the need for stable production-grade
cryptography suites. See section [[[#cryptographic-suites]]] for instructions on
establishing new types of cryptographic proofs.
          </dd>
          <dt>Serialization Flexibility</dt>
          <dd>
Cryptographic proofs can be serialized in many different but equivalent ways and
have often been tightly bound to the original document syntax. This
specification enables one to create cryptographic proofs that are not
bound to the original document syntax, which enables more advanced use cases
such as being able to use a single digital signature across a variety of
serialization syntaxes such as JSON and CBOR without the need to regenerate the
cryptographic proof. See section [[[#transformations]]] for an explanation of
the benefits of such an approach.
          </dd>
        </dl>

      <p class="note" title="Application of technology to broader use cases">
While this specification primarily focuses on [=verifiable credentials=], the
design of this technology is generalized, such that it can be used for other use
cases. In these instances, implementers are expected to perform their own due
diligence and expert review as to the applicability of the technology to their
use case.
      </p>

      </section>

      <section id="conformance">
        <p>
A <dfn>conforming secured document</dfn> is any [=byte sequence=] that can be
converted to a
<a data-cite="INFRA#parse-json-bytes-to-a-javascript-value">
JSON document</a> that follows the relevant normative requirements in
Sections [[[#proofs]]], [[[#proof-purposes]]], [[[#resource-integrity]]],
[[[#contexts-and-vocabularies]]], and [[[#dataintegrityproof]]].
        </p>

        <p>
A <dfn class="lint-ignore">conforming cryptographic suite specification</dfn> is
any specification that follows the relevant normative requirements in Section
[[[#cryptographic-suites]]].
        </p>

        <p>
A <dfn class="lint-ignore">conforming processor</dfn> is any algorithm realized
as software and/or hardware that generates and/or consumes a
[=conforming secured document=] according to the relevant normative statements
in Section [[[#algorithms]]]. Conforming processors MUST produce errors when
non-conforming documents are consumed.
        </p>

      </section>

      <section>
        <h3>Terminology</h3>

        <p>
This section defines the terms used in this specification. A link to these terms
is included whenever they appear in this specification.
        </p>

        <dl class="termlist definitions" data-sort="ascending">
          <dt><dfn class="export">data integrity proof</dfn></dt>
          <dd>
A set of attributes that represent a digital proof and the parameters required
to verify it. A <strong>digital signature</strong> is a type of data integrity
proof.
          </dd>
          <dt><dfn>public key</dfn></dt>
          <dd>
Cryptographic material that can be used to verify digital proofs created with a
corresponding [=secret key=].
          </dd>
          <dt><dfn>secret key</dfn></dt>
          <dd>
Cryptographic material, sometimes referred to as a
<strong>private key</strong>, that is not to be shared with anyone, and is used
to generate digital proofs and/or digital signatures.
          </dd>
          <dt><dfn class="export">proof purpose</dfn></dt>
          <dd>
The specific intent for the proof; the reason why an entity created it. The
protected declaration acts as a safeguard to prevent the proof from being
misused for a purpose other than the one it was intended for.
          </dd>

          <dt><dfn class="export" data-lt="cryptosuite">cryptographic suite</dfn></dt>
          <dd>
A specification defining the usage of specific cryptographic primitives in
order to achieve a particular security goal. These documents are often used
to specify [=verification methods=], digital signature types,
their identifiers, and other related properties. See Section
[[[#cryptographic-suites]]] for further detail.
          </dd>

          <dt><dfn>controlled identifier document</dfn></dt>

          <dd>
A document that contains public cryptographic material as defined in the
[[[CID]]] specification.
          </dd>

          <dt><dfn data-lt="verifier|verifiers|verifier's">verifier</dfn></dt>
          <dd>
A role an entity performs by receiving data containing one or more
[=data integrity proofs=] and then determining whether or not the proof
is legitimate.
          </dd>

          <dt><dfn class="export">verification method</dfn></dt>

          <dd>
            <p>
A set of parameters that can be used together with a process to independently
verify a proof. For example, a cryptographic [=public key=] can be used as a
verification method with respect to a digital signature; in such usage, it
verifies that the signer possessed the associated cryptographic [=secret key=].
            </p>
            <p>
"Verification" and "proof" in this definition are intended to apply broadly. For
example, a cryptographic public key might be used during Diffie-Hellman key
exchange to negotiate a shared symmetric key for encryption. This guarantees the
integrity of the key agreement process. It is thus another type of verification
method, even though descriptions of the process might not use the words
"verification" or "proof."
            </p>
          </dd>

          <dt><dfn class="export">verification relationship</dfn></dt>

          <dd>
            <p>
An expression of the relationship between the [=subject=] and a
[=verification method=]. An example of a verification relationship is
<a data-cite="CID#authentication">authentication</a>.
            </p>
          </dd>

        </dl>

      </section>
    </section>

    <section>
      <h2>Data Model</h2>

      <p>
This section specifies the data model that is used for expressing
[=data integrity proofs=] and the integrity of related resources.
      </p>

      <p>
All of the data model properties and types in this specification map to URLs.
The vocabulary where these URLs are defined is the [[[?SECURITY-VOCABULARY]]].
The explicit mechanism that is used to perform this mapping in a secured
document is the `@context` property.
      </p>

      <p>
The mapping mechanism is defined by [[[JSON-LD11]]]. To ensure a document can be
interoperably consumed without the use of a JSON-LD library, document authors
are advised to ensure that domain experts have 1) specified the expected order
for all values associated with a `@context` property, 2) published cryptographic
hashes for each `@context` file, and 3) deemed that the contents of each
`@context` file are appropriate for the intended use case.
      </p>

      <p>
When a document is processed by a processor that does not utilize JSON-LD
libraries, and there is a requirement to use the same semantics as those used in
a JSON-LD environment, implementers are advised to 1) enforce the expected order
and values in the `@context` property, and 2) ensure that each `@context` file
matches the known cryptographic hashes for each `@context` file.
      </p>

      <p>
Using static, versioned, `@context` files with published cryptographic hashes in
conjunction with JSON Schema is one acceptable approach to implementing the
mechanisms described above, which ensures proper term identification, typing,
and order, when a processor that does not utilize a JSON-LD library is used.
See the section on
<a data-cite="?VC-DATA-MODEL-2.0#type-specific-credential-processing">
Type-Specific Processing</a> in [[[?VC-DATA-MODEL-2.0]]] for more details.
      </p>

      <section>
        <h3>Proofs</h3>
        <p>
A [=data integrity proof=] provides information about the proof mechanism,
parameters required to verify that proof, and the proof value itself. All of
this information is provided using Linked Data vocabularies such as
[[[?SECURITY-VOCABULARY]]].
        </p>

        <p>
When expressing a [=data integrity proof=] on an object, a
<dfn class="lint-ignore">`proof`</dfn> property MUST be used. The `proof`
property within a [=verifiable credential=] is a [=named graph=]. If present,
its value MUST be either a single object, or an unordered set of objects,
expressed using the properties below:
        </p>

        <dl style="margin-left: 1em;">
          <dt>id</dt>
          <dd>
An optional identifier for the proof, which MUST be a URL [[URL]], such as
a UUID as a URN (`urn:uuid:6a1676b8-b51f-11ed-937b-d76685a20ff5`).
The usage of this property is further explained in Section [[[#proof-chains]]].
          </dd>

          <dt>type</dt>
          <dd>
The specific type of proof MUST be specified as a [=string=] that maps to a URL
[[URL]]. Examples of proof types include `DataIntegrityProof` and
`Ed25519Signature2020`. Proof types determine what other fields are required to
secure and verify the proof.
          </dd>

          <dt><dfn class="lint-ignore">proofPurpose</dfn></dt>
          <dd>
The reason the proof was created MUST be specified as a [=string=] that maps to a
URL [[URL]]. The proof purpose acts as a safeguard to prevent the proof from
being misused by being applied to a purpose other than the one that was
intended. For example, without this value the creator of a proof could be
tricked into using cryptographic material typically used to create a Verifiable
Credential (`assertionMethod`) during a login process (`authentication`) which
would then result in the creation of a [=verifiable credential=] they never meant to
create instead of the intended action, which was to merely log in to a website.
          </dd>

          <dt>verificationMethod</dt>
          <dd>
A verification method is the means and information needed to verify the proof.
If included, the value MUST be a [=string=] that maps to a [[URL]]. Inclusion of
`verificationMethod` is OPTIONAL, but if it is not included, other properties
such as `cryptosuite` might provide a mechanism by which to obtain the information
necessary to verify the proof. Note that when `verificationMethod` is
expressed in a [=data integrity proof=], the value points to the actual location
of the data; that is, the `verificationMethod` references, via a URL, the
location of the [=public key=] that can be used to verify the proof. This
[=public key=] data is stored in a [=controlled identifier document=], which contains a
full description of the verification method.
          </dd>

          <dt>cryptosuite</dt>
          <dd>
An identifier for the cryptographic suite that can be used to verify the proof. See
[[[#cryptographic-suites]]] for more information. If the proof `type` is
`DataIntegrityProof`, `cryptosuite` MUST be specified; otherwise,  `cryptosuite`
MAY be specified. If specified, its value MUST be a string.
          </dd>

          <dt><dfn class="lint-ignore">created</dfn></dt>
          <dd>
The date and time the proof was created is OPTIONAL and, if included, MUST be
specified as an [[XMLSCHEMA11-2]] `dateTimeStamp` string, either in Universal
Coordinated Time (UTC), denoted by a Z at the end of the value, or with a time
zone offset relative to UTC. A [=conforming processor=] MAY chose to consume
time values that were incorrectly serialized without an offset. Incorrectly
serialized time values without an offset are to be interpreted as UTC.
          </dd>

          <dt id="defn-proof-expires">expires</dt>
          <dd>
The `expires` property is OPTIONAL and, if present, specifies when the proof
expires. If present, it MUST be an [[XMLSCHEMA11-2]] `dateTimeStamp` string,
either in Universal Coordinated Time (UTC), denoted by a Z at the end of the
value, or with a time zone offset relative to UTC. A [=conforming processor=]
MAY chose to consume time values that were incorrectly serialized without an
offset. Incorrectly serialized time values without an offset are to be
interpreted as UTC.
          </dd>

          <dt id="defn-domain">domain</dt>
          <dd>
The `domain` property is OPTIONAL. It conveys one or more security domains in which the
proof is meant to be used. If specified, the associated value MUST be either a
string, or an unordered set of strings. A verifier SHOULD use the value to
ensure that the proof was intended to be used in the security domain in which
the verifier is operating. The specification of the `domain` parameter is useful
in challenge-response protocols where the verifier is operating from within a
security domain known to the creator of the proof. Example domain values
include: `domain.example` (DNS domain), `https://domain.example:8443`
(Web origin), `mycorp-intranet` (bespoke text string), and
`b31d37d4-dd59-47d3-9dd8-c973da43b63a` (UUID).
          </dd>

          <dt id="defn-challenge"><dfn>challenge</dfn></dt>
          <dd>
A [=string=] value that SHOULD be included in a proof if a `domain` is specified.
The value is used once for a particular [=domain=] and window of time. This
value is used to mitigate replay attacks. Examples of a challenge value include:
`1235abcd6789`, `79d34551-ae81-44ae-823b-6dadbab9ebd4`, and `ruby`.
          </dd>

          <dt><dfn class="lint-ignore">proofValue</dfn></dt>
          <dd>
A [=string=] value that expresses base-encoded binary data necessary to verify the
digital proof using the `verificationMethod` specified. The value MUST use a
header and encoding as described in Section
<a data-cite="CID#multibase-0">2.4 Multibase</a> of the
[[[CID]]] specification to express the binary data.
The contents of this value are determined by a specific cryptosuite and set
to the <em>proof value</em> generated by the <a href="#add-proof">Add Proof Algorithm</a>
for that cryptosuite. Alternative properties with different encodings specified by the
cryptosuite MAY be used, instead of this property, to encode the data necessary
to verify the digital proof.
          </dd>

          <dt><dfn class="lint-ignore">previousProof</dfn></dt>
          <dd>
The `previousProof` property is OPTIONAL. If present, it MUST be a string
value or an unordered list of string values. Each value identifies another
[=data integrity proof=], all of which MUST also verify for the current
proof to be considered verified. This property is used in Section
[[[#proof-chains]]].
          </dd>

          <dt><dfn class="lint-ignore">nonce</dfn></dt>
          <dd>
An OPTIONAL [=string=] value supplied by the proof creator. One use of this
field is to increase privacy by decreasing linkability that is the result
of deterministically generated signatures.
          </dd>

        </dl>

        <p>
A proof can be added to a JSON document like the following:
        </p>

        <pre class="example nohighlight" title="A simple JSON data document">
{
  "myWebsite": "https://hello.world.example/"
};
        </pre>

        <p>
The following proof secures the document above using the `eddsa-jcs-2022`
cryptography suite [[?DI-EDDSA]], which produces a verifiable digital proof by
transforming the input data using the JSON Canonicalization Scheme (JCS)
[[?RFC8785]] and then digitally signing it using an Edwards Digital Signature
Algorithm (EdDSA).
        </p>

        <pre class="example nohighlight"
        title="A simple signed JSON data document">
{
  "myWebsite": "https://hello.world.example/",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2023-03-05T19:23:24Z",
    "verificationMethod": "https://di.example/issuer#z6MkjLrk3gKS2nnkeWcm<wbr>cxiZPGskmesDpuwRBorgHxUXfxnG",
    "proofPurpose": "assertionMethod",
    "proofValue": "zQeVbY4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYV<wbr>8nQApmEcqaqA3Q1gVHMrXFkXJeV6doDwLWx"
  }
}
        </pre>

        <p>
Similarly, a proof can be added to a JSON-LD data document like the following:
        </p>

        <pre class="example nohighlight"
          title="A simple JSON-LD data document">
{
  "@context": {"myWebsite": "https://vocabulary.example/myWebsite"},
  "myWebsite": "https://hello.world.example/"
};
        </pre>

        <p>
The following proof secures the document above by using the `ecdsa-rdfc-2019`
cryptography suite [[?DI-ECDSA]], which produces a verifiable digital proof by
transforming the input data using the RDF Dataset Canonicalization Scheme
[[?RDF-CANON]] and then digitally signing it using the Elliptic Curve Digital
Signature Algorithm (ECDSA).
        </p>

        <pre class="example nohighlight"
        title="A simple signed JSON-LD data document">
{
  "@context": [
    {"myWebsite": "https://vocabulary.example/myWebsite"},
    "https://w3id.org/security/data-integrity/v2"
  ],
  "myWebsite": "https://hello.world.example/",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "ecdsa-rdfc-2019",
    "created": "2020-06-11T19:14:04Z",
    "verificationMethod": "https://ldi.example/issuer#zDnaepBuvsQ8cpsWrVK<wbr>w8fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
    "proofPurpose": "assertionMethod",
    "proofValue": "zXb23ZkdakfJNUhiTEdwyE598X7RLrkjnXEADLQZ7vZyUGXX8cyJZR<wbr>BkNw813SGsJHWrcpo4Y8hRJ7adYn35Eetq"
  }
}
        </pre>

        <p class="note" title="Representing time values to individuals">
This specification enables the expression of dates and times, such as through
the `created` and `expires` properties. This information might be indirectly
exposed to an individual if a proof is processed and is detected to be outside
an allowable time range. When displaying date and time values related to the
validity of cryptographic proofs, implementers are advised to respect the
<a data-cite="LTLI#locale" href="https://www.w3.org/TR/ltli/#locale">locale</a>
and local calendar preferences of the individual [[?LTLI]]. Conversion of
timestamps to local time values are expected to consider the time zone
expectations of the individual. See
<a data-cite="?VC-DATA-MODEL-2.0#representing-time"></a> for more details about
representing time values to individuals.
        </p>

        <pre class="example nohighlight"
        title="A data document with an attached proof that uses the 'expires' property">
{
  "@context": [
    {"myWebsite": "https://vocabulary.example/myWebsite"},
    "https://w3id.org/security/data-integrity/v2"
  ],
  "myWebsite": "https://hello.world.example/",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "ecdsa-rdfc-2019",
    "created": "2020-06-11T19:14:04Z",
    <span class="comment">// the proof expires a month after it was created</span>
    <span class="highlight">"expires": "2020-07-11T19:14:04Z"</span>,
    "verificationMethod": "https://ldi.example/issuer#zDnaepBuvsQ8cpsWrVK<wbr>w8fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
    "proofPurpose": "assertionMethod",
    "proofValue": "z98X7RLrkjnXEADJNUhiTEdwyE5GXX8cyJZRLQZ7vZyUXb23Zkdakf<wbr>RJ7adYY8hn35EetqBkNw813SGsJHWrcpo4"
  }
}
        </pre>

      <p>
The Data Integrity specification supports the concept of multiple
proofs in a single document. There are two types of multi-proof
approaches that are identified: Proof Sets (un-ordered) and Proof Chains
(ordered).
      </p>

      <section>
        <h3>Proof Sets</h3>
        <p>
A <dfn>proof set</dfn> is useful when the same data needs to be secured by
multiple entities, but where the order of proofs does not matter, such as in the
case of a set of signatures on a contract. A proof set, which has no order, is
represented by associating a set of proofs with the `proof` key in a document.
        </p>
        <pre class="example nohighlight" title="A proof set in a data document">
{
  "@context": [
    {"myWebsite": "https://vocabulary.example/myWebsite"},
    "https://w3id.org/security/data-integrity/v2"
  ],
  "myWebsite": "https://hello.world.example/",
  <span class="highlight">"proof": [{
    <span class="comment">// This is one of the proofs in the set</span>
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-rdfc-2022",
    "created": "2020-11-05T19:23:24Z",
    "verificationMethod": "https://ldi.example/issuer/1#z6MkjLrk3gKS2nnkeW<wbr>cmcxiZPGskmesDpuwRBorgHxUXfxnG",
    "proofPurpose": "assertionMethod",
    "proofValue": "z4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYVQeVbY8<wbr>nQAVHMrXFkXJpmEcqdoDwLWxaqA3Q1geV6"
  }, {
    <span class="comment">// This is the other proof in the set</span>
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-rdfc-2022",
    "created": "2020-11-05T13:08:49Z",
    "verificationMethod": "https://pfps.example/issuer/2#z6MkGskxnGjLrk3gK<wbr>S2mesDpuwRBokeWcmrgHxUXfnncxiZP",
    "proofPurpose": "assertionMethod",
    "proofValue": "z5QLBrp19KiWXerb8ByPnAZ9wujVFN8PDsxxXeMoyvDqhZ6Qnzr5CG9<wbr>876zNht8BpStWi8H2Mi7XCY3inbLrZrm95"
  }]</span>
}
        </pre>

      </section>

      <section>
        <h3>Proof Chains</h3>
        <p>
A <dfn>proof chain</dfn> is useful when the same data needs to be signed by
multiple entities and the order of when the proofs occurred matters, such as in
the case of a notary counter-signing a proof that had been created on a
document. A proof chain, where proof order needs to be preserved, is expressed
by providing at least one proof with an `id`, such as a UUID [[?RFC9562]], and
another proof with a `previousProof` value that identifies the previous proof.
        </p>
        <pre class="example nohighlight"
          title="A proof chain in a data document">
{
  "@context": [
    {"myWebsite": "https://vocabulary.example/myWebsite"},
    "https://w3id.org/security/data-integrity/v2"
],
  "myWebsite": "https://hello.world.example/",
  <span class="highlight">"proof": [{
    <span class="comment">// The 'id' value identifies this specific proof</span>
    "id": "urn:uuid:60102d04-b51e-11ed-acfe-2fcd717666a7",
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-rdfc-2022",
    "created": "2020-11-05T19:23:42Z",
    "verificationMethod": "https://ldi.example/issuer/1#z6MkjLrk3gKS2nnke<wbr>WcmcxiZPGskmesDpuwRBorgHxUXfxnG",
    "proofPurpose": "assertionMethod",
    "proofValue": "zVbY8nQAVHMrXFkXJpmEcqdoDwLWxaqA3Q1geV64oey5q2M3XKaxup<wbr>3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYVQe"
  }, {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-rdfc-2022",
    "created": "2020-11-05T21:28:14Z",
    "verificationMethod": "https://pfps.example/issuer/2#z6MkGskxnGjLrk3g<wbr>KS2mesDpuwRBokeWcmrgHxUXfnncxiZP",
    "proofPurpose": "assertionMethod",
    "proofValue": "z6Qnzr5CG9876zNht8BpStWi8H2Mi7XCY3inbLrZrm955QLBrp19Ki<wbr>WXerb8ByPnAZ9wujVFN8PDsxxXeMoyvDqhZ",
    <span class="comment">// The 'previousProof' value identifies which proof is verified before this one</span>
    "previousProof": "urn:uuid:60102d04-b51e-11ed-acfe-2fcd717666a7"
  }]</span>
}
        </pre>

      </section>

      <section>
        <h3>Proof Graphs</h3>

        <p>
When securing data in a document, it is important to clearly delineate the data
being protected, which is every graph expressed in the document except the
one containing the data associated with a securing mechanism, which is called
a <dfn class="export">proof graph</dfn>. Creating this separation enables the
processing algorithms to deterministically protect and verify a secured
document.
        </p>

        <p>
The information contained in an input document before a
[=data integrity proof=] is added to the document is expressed in one or more
graphs. To ensure that information from different [=data integrity proofs=] is not
accidentally co-mingled, the concept of a [=proof graph=] is used to encapsulate
each [=data integrity proof=]. Each value associated with the `proof` property of the
document identifies a separate graph, which is sometimes referred to as a
<dfn class="export">named graph</dfn>, of type
<dfn class="export">ProofGraph</dfn>, which contains a single [=data integrity
proof=].
        </p>

        <p>
Using these graphs has a concrete effect when performing JSON-LD processing, as
this properly separates statements expressed in one graph from those in another
graph. Implementers that limit their processing to other media types, such as
JSON, YAML, or CBOR, will need to keep this in mind if they merge data from one
document with data from another, such as when an `id` value string is the same
in both documents. It is important to not merge objects that seem to have similar
properties, when those objects do not have an `id` property and/or use a global
identifier type such as a URL, as without these, is not possible to tell whether
two such objects are expressing information about the same entity.
        </p>
      </section>

    </section>

      <section>
        <h3>Proof Purposes</h3>

        <p>
A proof that describes its purpose helps prevent it from being misused for some
other purpose. [=Proof purposes=] enable [=verifiers=] to know the
intent of the creator of a proof so a message cannot be accidentally abused for
another purpose. For example, a message signed for the purpose of merely making an
assertion (perhaps intended to be widely shared) being abused as a
message to authenticate to a service or take some action (such as invoking a
capability to do something).
        </p>

        <p>
It is important to note that [=proof purposes=] are a different mechanism from
the `key_ops` restrictions in [[[?RFC7517]]], the `KeyUsage` restriction in the
[[[?WEBCRYPTOAPI]]] and the [[[?RFC5280]]]. [=Proof purposes=] are expressions
on why a [=proof=] was created and its intended domain of usage whereas the
other mechanisms mentioned are intended to limit what a private key can be used
to do. A [=proof purpose=] "travels" with the [=proof=] while a key restriction
does not.
        </p>

        <p>
The following is a list of commonly used [=proof purpose=] values.
        </p>

        <dl>
          <dt><dfn class="external">authentication</dfn></dt>
          <dd>
Indicates that a given proof is only to be used for the purposes of an
authentication protocol.
          </dd>
          <dt><dfn class="external lint-ignore">assertionMethod</dfn></dt>
          <dd>
Indicates that a proof can only be used for making assertions, for example
signing a [=verifiable credential=].
          </dd>
          <dt><dfn class="external lint-ignore">keyAgreement</dfn></dt>
          <dd>
Indicates that a proof is used for for key agreement protocols, such as
Elliptic Curve Diffie Hellman key agreement used by popular encryption
libraries.
          </dd>
          <dt><dfn class="external lint-ignore">capabilityDelegation</dfn></dt>
          <dd>
Indicates that the proof can only be used for delegating capabilities. See the
Authorization Capabilities [[?ZCAP]] specification for more detail.
          </dd>
          <dt><dfn class="external lint-ignore">capabilityInvocation</dfn></dt>
          <dd>
Indicates that the proof can only be used for invoking capabilities. See the
Authorization Capabilities [[?ZCAP]] specification for more detail.
          </dd>
        </dl>

      </section>

      <section>
        <h2>Resource Integrity</h2>

        <p>
When a link to an external resource is included in a
[=conforming secured document=], it is desirable to know whether the resource
that is identified has changed since the proof was created. This applies to
cases where there is an external resource that is remotely retrieved as well as
to cases where the [=verifier=] might have a locally cached copy of the
resource.
        </p>
        <p>
To enable confirmation that a resource referenced by a [=conforming secured document=]
has not changed since the document was secured, an implementer MAY include a
property named <dfn class="lint-ignore">`digestMultibase`</dfn> in any object
that includes an `id` property. If present, the `digestMultibase` value MUST be
a single [=string=] value, or an [=list=] of [=string=] values, each of which is a
<a data-cite="CID#multibase">Multibase</a>-encoded
<a data-cite="CID#multihash">Multihash</a> value.
        </p>
        <p>
JSON-LD context authors are expected to add `digestMultibase` to contexts that
will be used in documents that refer to other resources and to include an
associated cryptographic digest. For example, the [[[?VC-DATA-MODEL-2.0]]] base
context (`https://www.w3.org/ns/credentials/v2`) includes the
`digestMultibase` property.
        </p>

        <p>
An example of a resource integrity protected object is shown below:
        </p>

        <pre class="example nohighlight"
          title="An integrity-protected image that is associated with an object">
{
  ...
  "image": {
    "id": "https://university.example.org/images/58473",
    <span class="highlight">"digestMultibase": "zQmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n"</span>
  },
  ...
}
        </pre>

        <p>
Implementers are urged to consult appropriate sources, such as the
<a href="https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf">
FIPS 180-4 Secure Hash Standard</a> and the
<a href="https://en.wikipedia.org/wiki/Commercial_National_Security_Algorithm_Suite">
Commercial National Security Algorithm Suite 2.0</a> to ensure that they are
choosing a hash algorithm that is appropriate for their use case.
        </p>

      </section>

      <section>
        <h2>Contexts and Vocabularies</h2>

        <p>
Implementations that perform JSON-LD processing MUST treat the following
JSON-LD context URLs as already resolved, where the resolved document matches
the corresponding hash values below:
        </p>

        <table class="simple">
          <thead>
            <th>Context URL and Hash</th>
          </thead>
          <tbody>
            <tr>
              <td style="white-space: nowrap;">
<strong>URL:</strong> https://w3id.org/security/data-integrity/v2<br>
<strong>SHA2-256 Digest:</strong> <code><span class="vc-hash"
data-hash-url="https://w3id.org/security/data-integrity/v2"
data-hash-format="openssl dgst -sha256" /></code>
              </td>
            </tr>
            <tr>
              <td style="white-space: nowrap;">
<strong>URL:</strong> https://w3id.org/security/multikey/v1<br>
<strong>SHA2-256 Digest:</strong> <code><span class="vc-hash"
data-hash-url="https://w3id.org/security/multikey/v1"
data-hash-format="openssl dgst -sha256" /></code>
              </td>
            </tr>
            <tr>
              <td style="white-space: nowrap;">
<strong>URL:</strong> https://w3id.org/security/jwk/v1<br>
<strong>SHA2-256 Digest:</strong> <code><span class="vc-hash"
data-hash-url="https://w3id.org/security/jwk/v1"
data-hash-format="openssl dgst -sha256" /></code>
              </td>
            </tr>
          </tbody>
        </table>

        <p>
It is possible to confirm the cryptographic digests listed above by running a
command like the following (replacing `&lt;DOCUMENT_URL>` with the appropriate
value) through a modern UNIX-like OS command line interface: `curl -sL -H
"Accept: application/ld+json" &lt;DOCUMENT_URL> | openssl dgst -sha256`
        </p>

        <p>
The security vocabulary terms that the JSON-LD contexts listed above resolve
to are in the <a href="https://w3id.org/security">https://w3id.org/security#</a>
namespace. That is, all security terms in this vocabulary are of the form
`https://w3id.org/security#TERM`, where `TERM` is the name of a term.
        </p>

        <p>
Implementations that perform RDF processing MUST treat
the JSON-LD serialization of the vocabulary URL as already dereferenced, where the dereferenced document matches
the corresponding hash value below.
        </p>

        <p class="note">
Beyond the security terms defined by this specification, the
<a href="https://w3id.org/security">https://w3id.org/security#</a> namespace
also includes the terms defined in the [[[CID]]] [[CID]]
specification, with the corresponding mappings in the context files listed above.
        </p>

        <p>
When dereferencing the
<a href="https://w3id.org/security">https://w3id.org/security#</a> URL,
the media type of the data that is returned depends on HTTP content negotiation. These are as follows:
        </p>

        <table class="simple">
          <thead>
            <tr>
              <th>Media Type</th>
              <th>Description and Hash</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>
application/ld+json
              </td>
              <td>
The vocabulary in JSON-LD format [[?JSON-LD11]].<br><br>

<strong>SHA2-256 Digest:</strong> <code><span class="vc-hash"
data-hash-url="https://w3c.github.io/vc-data-integrity/vocab/security/vocabulary.jsonld"
data-hash-format="openssl dgst -sha256" /></code>
              </td>
            </tr>
            <tr>
              <td>
text/turtle
              </td>
              <td>
The vocabulary in Turtle format [[?TURTLE]].<br><br>

<strong>SHA2-256 Digest:</strong> <code><span class="vc-hash"
data-hash-url="https://w3c.github.io/vc-data-integrity/vocab/security/vocabulary.ttl"
data-hash-format="openssl dgst -sha256" /></code>
              </td>
            </tr>
            <tr>
              <td>
text/html
              </td>
              <td>
The vocabulary in HTML+RDFa Format [[?HTML-RDFA]].<br><br>


<strong>SHA2-256 Digest:</strong> <code><span class="vc-hash"
data-hash-url="https://w3c.github.io/vc-data-integrity/vocab/security/vocabulary.html"
data-hash-format="openssl dgst -sha256" /></code>
              </td>
            </tr>
          </tbody>
        </table>

        <p>
It is possible to confirm the cryptographic digests listed above by running
a command like the following (replacing `&lt;MEDIA_TYPE>` and `&lt;DOCUMENT_URL>`
with the appropriate values) through a modern UNIX-like OS command line interface:
`curl -sL -H "Accept: &lt;MEDIA_TYPE>" &lt;DOCUMENT_URL> | openssl dgst -sha256`
        </p>

        <p>
Authors of application-specific vocabularies and specifications SHOULD ensure
that their JSON-LD context and vocabulary files are permanently cacheable
using the approaches to caching described above or a functionally equivalent
mechanism.
        </p>

        <p>
Implementations MAY load application-specific JSON-LD context files from the
network during development, but SHOULD permanently cache JSON-LD context files
used by [=conforming secured documents=] in production settings, to increase
their security and privacy characteristics. Goals of processing speed MAY be
achieved through caching approaches such as those described above or
functionally equivalent mechanisms.
        </p>
        <p>
Some applications, such as digital wallets, that are capable of holding arbitrary
[=verifiable credentials=] or other data-integrity-protected documents, from
any issuer and using any contexts, might need to be able to load externally
linked resources, such as JSON-LD context files, in production settings. This is
expected to increase user choice, scalability, and decentralized upgrades in the
ecosystem over time. Authors of such applications are advised to read the
security and privacy sections of this document for further considerations.
        </p>

        <p>
For further information regarding processing of JSON-LD contexts and
vocabularies, see <a data-cite="?VC-DATA-MODEL-2.0#base-context">Verifiable
Credentials v2.0: Base Context</a> and <a data-cite="?VC-DATA-MODEL-2.0#vocabularies">
Verifiable Credentials v2.0: Vocabularies</a>.
        </p>

        <section>
          <h3>Validating Contexts</h3>

          <p>
It is necessary to ensure that a consuming application has explicitly approved
of the types, and therefore the semantics, of input documents that it will
process. Not checking JSON-LD context values against known good values can lead
to security vulnerabilities, due to variance in the semantics that they convey.
Applications MUST use the algorithm in Section [[[#context-validation]]], or one
that achieves equivalent protections, to validate contexts in a [=conforming
secured document=]. Context validation MUST be run <em>after</em> running the
applicable algorithm in either Section [[[#verify-proof]]] or Section
[[[#verify-proof-sets-and-chains]]].
          </p>

          <p>
While the algorithm described in Section [[[#context-validation]]] provides one
way of checking context values, and one optional way of safely processing
unknown context values, implementers MAY use alternative approaches, or a
different ordering of the steps, that provide the same protections.
          </p>

          <p>
For example, if no JSON-LD processing is to occur, then, rather than performing
this check, an application could follow the guidance in whatever trusted
documentation is provided out of band for properly understanding the semantics
of that type of document.
          </p>

          <p>
Another approach would be to configure an application to use a JSON-LD Context
loader, sometimes referred to as a document loader, to use only local copies of
approved context files. This would guarantee that neither the context files nor
their cryptographic hashes would ever change, effectively resulting in the same
result as the algorithm in Section [[[#context-validation]]].
          </p>

          <p>
Another alternative approach, also effectively equivalent to the algorithm in
Section [[[#context-validation]]], would be for an application to keep a list of
well known context URLs and their associated approved cryptographic hashes,
without storing every context file locally. This would allow these contexts to
be safely loaded from the network without compromising the security expectations
of the application.
          </p>

          <p>
Yet another valid approach would be for a transmitting application to
<a data-cite="JSON-LD11-API#compaction-algorithm">compact</a> a document to
exactly what a receiving application requests, via a protocol such as one
requesting a [=verifiable presentation=], omitting additional sender-specific
context values that were used when securing the original document. As long as
the cryptography suite's verification algorithm provides a successful
verification result, such transformations are valid and would result in full
URLs for terms that were previously compacted by the omitted context. That is, a
term that was previously compacted to `foo` based on a sender-supplied context
that is unknown to a receiver (e.g., ``https://ontology.example/v1`) would
instead be "expanded" to a URL like `https://ontology.example#foo`, which would
then be "compacted" to the same URL, once the unknown context is omitted and the
JSON-LD compaction algorithm is applied by the receiving application.
          </p>

        </section>

        <section>
          <h3>Context Injection</h3>

          <p>
The `@context` property is used to ensure that implementations are using the
same semantics when terms in this specification are processed. For example, this
can be important when properties like `type` are processed and its value, such
as `DataIntegrityProof`, are used.
          </p>

          <p>
When an application is securing a document, if an `@context` property is not
provided in the document or the Data Integrity terms used in the document are
not mapped by existing values in the `@context` property, implementations SHOULD
inject or append an `@context` property with a value of
`https://w3id.org/security/data-integrity/v2` or one or more contexts with at
least the same declarations, such as the Verifiable Credential Data Model v2.0
context (`https://www.w3.org/ns/credentials/v2`).
          </p>

          <p>
Implementations that do not intend to use JSON-LD processing MAY choose to not
include an `@context` declaration at the top-level of the document. However, if
an `@context` declaration is not included, extensions (such as the addition of
new properties) related to this specification or corresponding cryptosuites
MUST NOT be made.
          </p>

        </section>

        <section>
          <h3>Securing Data Losslessly</h3>

          <p>
HTML processors are designed to continue processing if recoverable errors are
detected. JSON-LD processors operate in a similar manner. This design philosophy
was meant to ensure that developers could use only the parts of the JSON-LD
language that they find useful, without causing the processor to throw errors
on things that might not be important to the developer. Among other effects,
this philosophy led to JSON-LD processors being designed to not throw errors,
but rather warn developers, when encountering things such as undefined terms.
          </p>

          <p>
When converting from JSON-LD to an RDF Dataset, such as when canonicalizing a
document [[?RDF-CANON]], undefined terms and relative URLs can be dropped
silently. When values are dropped, they are not protected by a digital proof. This
creates a mismatch of expectations, where a developer, who is unaware of how
a JSON-LD processor works, might think that certain data was being secured,
and then be surprised to find that it was not, when no error was thrown.
This specification requires that any recoverable loss of data when
performing JSON-LD transformations result in an error, to avoid a mismatch
in the security expectations of developers.
          </p>

          <p>
Implementations that use JSON-LD processing, such as RDF Dataset
Canonicalization [[?RDF-CANON]], MUST throw an error, which SHOULD be
`DATA_LOSS_DETECTION_ERROR`, when data is dropped by a JSON-LD processor,
such as when an undefined term is detected in an input document.
          </p>

          <p>
Similarly, since [=conforming secured documents=] can be transferred from one
security domain to another, [=conforming processors=] that process the
[=conforming secured document=] cannot assume any particular base URL for
the document. When deserializing to RDF, implementations MUST ensure that the
base URL is set to null.
          </p>
        </section>

        <section>
          <h3>Datatypes</h3>

          <p>
This section defines datatypes that are used by this specification.
          </p>

        <section>
          <h4 id="cryptosuiteString">The `cryptosuiteString` Datatype</h3>

          <p>
This specification encodes cryptographic suite identifiers as enumerable
strings, which is useful in processes that need to efficiently encode such
strings, such as compression algorithms. In environments that support data types
for [=string=] values, such as RDF [[?RDF-CONCEPTS]], cryptographic identifier
content is indicated using a literal value whose datatype is set to
`https://w3id.org/security#cryptosuiteString`.
          </p>

          <p>
The `cryptosuiteString` datatype is defined as follows:
          </p>

          <dl>
            <dt>The URL denoting this datatype</dt>
            <dd>
`https://w3id.org/security#cryptosuiteString`
            </dd>
            <dt>The lexical space</dt>
            <dd>
The union of all cryptosuite strings, expressed using American Standard Code
for Information Interchange [[ASCII]] strings, that are defined by the
collection of all Data Integrity cryptosuite specifications.
            </dd>
            <dt>The value space</dt>
            <dd>
The union of all cryptosuite types that are expressed using the `cryptosuite`
property, as defined in Section [[[#dataintegrityproof]]].
            </dd>
            <dt>The lexical-to-value mapping</dt>
            <dd>
Any element of the lexical space is mapped to the result of parsing it into an
internal representation that uniquely identifies the cryptosuite type from all
other possible cryptosuite types.
            </dd>
            <dt>The canonical mapping</dt>
            <dd>
Any element of the value space is mapped to the corresponding string in the
lexical space.
            </dd>
          </dl>
        </section>

      </section>

    </section>

      <section>
        <h2>Relationship to Linked Data</h2>
        <p>
The term Linked Data is used to describe a recommended best practice for
exposing, sharing, and connecting information on the Web using standards, such
as URLs, to identify things and their properties. When information is presented
as Linked Data, other related information can be easily discovered and new
information can be easily linked to it. Linked Data is extensible in a
decentralized way, greatly reducing barriers to large scale integration.
        </p>

        <p>
With the increase in usage of Linked Data for a variety of applications, there
is a need to be able to verify the authenticity and integrity of Linked Data
documents. This specification adds authentication and integrity protection to
data documents through the use of mathematical proofs without sacrificing Linked
Data features such as extensibility and composability.
        </p>

        <p class="note" title="Use of Linked Data is an optional feature">
While  this specification provides mechanisms to digitally sign Linked Data, the
use  of Linked Data is not necessary to gain some of the advantages provided by
this specification.
        </p>

      </section>

      <section>
        <h2>Relationship to Verifiable Credentials</h2>

        <p>
Cryptographic suites that implement this specification can be used to secure
[=verifiable credentials=] and [=verifiable presentations=]. Implementers
that are addressing those use cases are cautioned that additional checks might
be appropriate when processing those types of documents.
        </p>

        <p>
There are some use cases where it is important to ensure that the
[=verification method=] used in a proof is associated with the
<a data-cite="?VC-DATA-MODEL-2.0#issuer">`issuer`</a> in a
<a data-cite="?VC-DATA-MODEL-2.0#dfn-verifiable-credential">
verifiable credential</a>, or the
<a data-cite="?VC-DATA-MODEL-2.0#dfn-holders">`holder`</a> in a
<a data-cite="?VC-DATA-MODEL-2.0#dfn-verifiable-presentation">
verifiable presentation</a>, during the process of
<a data-cite="?VC-DATA-MODEL-2.0#issuer-0">validation</a>. One
way to check for such an association is to ensure that the value of the
`controller` property of a proof's [=verification method=]
matches the URL value used to identify the
<a data-cite="?VC-DATA-MODEL-2.0#issuer">`issuer`</a> or
<a data-cite="?VC-DATA-MODEL-2.0#dfn-holders">`holder`</a>, respectively, and
that the verification method is expressed under a verification relationship that
is acceptable given the proof's purpose. This particular association indicates
that the
<a data-cite="?VC-DATA-MODEL-2.0#issuer">`issuer`</a> or
<a data-cite="?VC-DATA-MODEL-2.0#dfn-holders">`holder`</a>, respectively,
is the controller of the [=verification method=] used to verify
the proof.
        </p>

        <p>
Document authors and implementers are advised to understand the difference
between the validity period of a <a href="#proofs">proof</a>, which is expressed
using the <a href="#dfn-created">`created`</a> and <a
href="#defn-proof-expires">`expires`</a> properties, and the validity period of
a <a data-cite="?VC-DATA-MODEL-2.0#dfn-credential">credential</a>,
which is expressed using the
<a data-cite="?VC-DATA-MODEL-2.0#defn-validFrom">`validFrom`</a> and
<a data-cite="?VC-DATA-MODEL-2.0#defn-validUntil">`validUntil`</a> properties.
While these properties might sometimes express the same validity periods, at
other times they might not be aligned. When verifying a
<a href="#proofs">proof</a>, it is important to ensure that the time of interest
(which might be the current time or any other time) is within the
validity period for the proof (that is, between
<a href="#dfn-created">`created`</a> and
<a href="#defn-proof-expires">`expires`</a> ).
When <a data-cite="?VC-DATA-MODEL-2.0#validation">validating</a> a
[=verifiable credential=], it is important to ensure that the time of
interest is within the validity period for the
<a data-cite="?VC-DATA-MODEL-2.0#dfn-credential">credential</a> (that is,
betweeen
<a data-cite="?VC-DATA-MODEL-2.0#defn-validFrom">`validFrom`</a> and
<a data-cite="?VC-DATA-MODEL-2.0#defn-validUntil">`validUntil`</a>). Note that a
failure to validate either the validity period for the <a
href="#proofs">proof</a>, or the validity period for the
<a data-cite="?VC-DATA-MODEL-2.0#dfn-credential">credential</a>, might result
in accepting data that ought to have been rejected.
        </p>

        <p>
Finally, implementers are also urged to understand that there is a difference
between the revocation information associated with a [=verifiable credential=],
and the <a data-cite="CID#dfn-revoked">revocation</a>
and <a data-cite="CID#defn-vm-expires">expiration</a> times
for a [=verification method=]. The
<a data-cite="CID#dfn-revoked">revocation</a> and
<a data-cite="CID#defn-vm-expires">expiration</a> times for a
[=verification method=] are expressed using the `revocation` and `expires`
properties, respectively; are related to events such as a [=secret key=] being
compromised or expiring; and can provide timing information which might reveal
details about a controller, such as their security practices or when they might
have been compromised. The revocation information for a [=verifiable
credential=] is expressed using the `credentialStatus` property; is related
to events such as an individual losing the privilege that is granted by the
[=verifiable credential=]; and does not provide timing information, which
enhances privacy.
        </p>
      </section>

    </section>

    <section>
      <h2>Cryptographic Suites</h2>
      <p>
A [=data integrity proof=] is designed to be easy to use by developers and
therefore strives to minimize the amount of information one has to remember to
generate a proof. Often, just the [=cryptographic suite=] name (such as
`eddsa-rdfc-2022`) is required from developers to initiate the creation of a
proof. These [=cryptographic suite=]s are often created and reviewed by people
that have the requisite cryptographic training to ensure that safe combinations
of cryptographic primitives are used. This section specifies the requirements
for authoring cryptographic suite specifications.
      </p>

      <p>
The requirements for all data integrity cryptographic suite specifications are
as follows:
      </p>

      <ul>
        <li>
The specification MUST be published as a human-readable document at a URL.
        </li>
        <li>
The specification MUST identify a cryptographic suite `type` and any
parameters that can be used with the suite.
        </li>
        <li>
The specification MUST detail the [=transformation algorithms=] (if any),
parameters, and other necessary details, used to modify input data into the data
to be protected.
        </li>
        <li>
The specification MUST detail the [=hashing algorithms=]
parameters, and other necessary details used to perform cryptographic hashing to
the data to be protected.
        </li>
        <li>
The specification MUST detail the [=proof serialization algorithms=],
parameters, and other necessary details used to perform cryptographic protection
of the data.
        </li>
        <li>
The specification MUST detail the [=proof verification algorithms=],
parameters, and other necessary details used to perform cryptographic
verification of the data.
        </li>
        <li>
The specification MUST define a <dfn class="export" data-lt="cryptosuite
instantiation algorithm">data integrity cryptographic suite instantiation
algorithm</dfn> that accepts a set of options ([=map=] |options|) and returns a
[=cryptosuite instance=] ([=struct=] |cryptosuite|). This algorithm SHOULD be
listed in the [[[?VC-EXTENSIONS]]] document. A <dfn class="export"
data-local-lt="cryptosuite instance">data integrity cryptographic suite
instance</dfn> [=struct=] has the following [=struct/items=].
          <dl data-dfn-for="cryptosuite instance">
            <dt><dfn>createProof</dfn></dt>
            <dd>
An algorithm that takes an [=input document=] ([=map=]
|inputDocument|) and proof options ([=map=] |options|) as input, and
produces a [=data integrity proof=] ([=map=]) or an error.
            </dd>
            <dt><dfn>verifyProof</dfn></dt>
            <dd>
An algorithm that takes a [=secured data document=] ([=map=]
|securedDocument|) as input, and produces a <dfn>cryptosuite verification
result</dfn> or an error. The [=cryptosuite verification result=] is a
[=struct=] that contains the following [=struct/items=]:
              <dl data-dfn-for="cryptosuite verification result">
                <dt><dfn class="lint-ignore">verified</dfn></dt>
                <dd>
A [=boolean=] that is `true` if the verification succeeded, or `false`
otherwise.
                </dd>
                <dt><dfn class="lint-ignore">verifiedDocument</dfn></dt>
                <dd>
A [=map=] that represents the [=secured data document=] with the verified
proofs removed if [=cryptosuite verification result/verified=] is `true`, or
<a data-cite="INFRA#nulls">null</a> otherwise.
                </dd>
              </dl>
The structure MAY contain other implementation-specific information that is
useful for developers, such as debugging information. If an error is produced,
the verification process failed to complete. An error, such as a network error,
does not mean that a future attempt at verification would fail.
            </dd>
          </dl>
        </li>
        <li>
The specification MUST detail any known resource starvation attack that can
occur in an algorithm and provide testable mitigations against each attack.
        </li>
        <li>
The specification MUST contain a Security Considerations section detailing
security considerations specific to the cryptographic suite.
        </li>
        <li>
The specification MUST contain a Privacy Considerations section detailing
privacy considerations specific to the cryptographic suite.
        </li>
        <li>
The JSON-LD context associated with the cryptographic suite MUST have its terms
protected from unsafe redefinition, by use of the `@protected` keyword.
        </li>
      </ul>

      <p>
A [=cryptosuite instance=] is instantiated using a [=cryptosuite instantiation
algorithm=] and is made available to algorithms in an implementation-specific
manner. Implementations MAY use the [[[?VC-EXTENSIONS]]] document to discover
known [=cryptosuite instantiation algorithms=].
      </p>

      <section>
        <h3>DataIntegrityProof</h3>

        <p>
A number of [=cryptographic suites=] follow the same basic pattern when
expressing a [=data integrity proof=]. This section specifies that general
design pattern, a [=cryptographic suite=] type called a `DataIntegrityProof`,
which reduces the burden of writing and implementing [=cryptographic suites=]
through the reuse of design primitives and source code.
        </p>

        <p>
When specifing a [=cryptographic suite=] that utilizes this design pattern, the
`proof` value takes the following form:
        </p>

        <dl>
          <dt>type</dt>
          <dd>
The `type` property MUST contain the [=string=] `DataIntegrityProof`.
          </dd>
          <dt>cryptosuite</dt>
          <dd>
The value of the `cryptosuite` property MUST be a [=string=] that identifies the
[=cryptographic suite=]. If the processing environment supports [=string=]
subtypes, the subtype of the `cryptosuite` value MUST be the
`https://w3id.org/security#cryptosuiteString` subtype.
          </dd>
          <dt>proofValue</dt>
          <dd>
The `proofValue` property MUST be used, as specified in Section [[[#proofs]]].
          </dd>
        </dl>

        <p>
[=Cryptographic suite=] designers MUST use mandatory `proof` value properties
defined in Section [[[#proofs]]], and MAY define other properties specific to
their cryptographic suite.
        </p>

        <p class="note" title="Design Patterns of Legacy Cryptographic Suites">
One of the design patterns seen in Data Integrity cryptosuites from
2012 to 2020 was use of the `type` property to establish a specific type for a
cryptographic suite; the
<a href="https://www.w3.org/TR/vc-di-eddsa/#the-ed25519signature2020-suite">
Ed25519Signature2020 cryptographic suite</a> was one such specification. This
led to a greater burden on cryptographic suite implementations, where every new
cryptographic suite required specification of a new JSON-LD Context, resulting
in a sub-optimal developer experience. A streamlined version of this design
pattern emerged in 2020, such that a developer would only need to include a
single JSON-LD Context to support all modern cryptographic suites. This
encouraged more modern cryptosuites &mdash; such as the EdDSA Cryptosuites
[[?DI-EDDSA]] and the ECDSA Cryptosuites [[?DI-ECDSA]] &mdash; to be built
based on the streamlined pattern described in this section.
        <br><br>
To improve the developer experience, authors creating new Data Integrity
cryptographic suite specifications SHOULD use the modern pattern &mdash; where
the `type` is set to `DataIntegrityProof`; the `cryptosuite` property carries
the identifier for the cryptosuite; and any cryptosuite-specific cryptographic
data is encapsulated (i.e., not directly exposed as application layer data)
within `proofValue`. A list of cryptographic suite specifications that are
known to follow this pattern is provided in the
<a href="https://w3c.github.io/vc-extensions/#securing-mechanisms">
Securing Mechanisms section of the Verifiable Credentials Extensions</a>
document.
        </p>
      </section>

    </section>

    <section>
      <h2>Algorithms</h2>

      <p>
The algorithms defined below operate on documents represented as <dfn
data-cite="RFC8259#section-4">JSON objects</dfn>. This specification follows the
[[[JSON-LD11-API]]] specification in representing a JSON object as a [=map=].
An <dfn class="export">unsecured data document</dfn> is a [=map=] that contains
no proof values. An <dfn>input document</dfn> is an [=map=] that has not yet had
the current proof added to it, but it MAY contain a proof value that was added
to it by a previous process. A <dfn class="export">secured data document</dfn>
is a [=map=] that contains one or more proof values.
      </p>

      <p>
Implementers MAY implement reasonable defaults and safeguards in addition to the
algorithms below, to help mitigate developer error, excessive resource
consumption, newly discovered attack models against which there is a particular
protection, and other improvements. The algorithms provided below are the
minimum requirements for an interoperable implementation, and developers are
urged to include additional measures that could contribute to a safer and more
efficient ecosystem.
      </p>

      <section class="normative">
        <h3>Processing Model</h3>

        <p>
The processing model used by a [=conforming processor=] and its
application-specific software is described in this section. When software
is to ensure information is tamper-evident, it performs the following steps:
        </p>

        <ol>
          <li>
The software arranges the information into a document, such as a JSON or
JSON-LD document.
          </li>
          <li>
If the document is a JSON-LD document, the software selects one or more
JSON-LD Contexts and expresses them using the `@context` property.
          </li>
          <li>
The software selects one or more cryptography suites that meet the needs of
the use case, such as one that provides full, selective, or unlinkable
disclosure, using acceptable cryptographic key material.
          </li>
          <li>
The software uses the applicable algorithm(s) provided in Section [[[#add-proof]]]
or Section [[[#add-proof-set-chain]]] to add one or more proofs.
          </li>
        </ol>

        <p>
When software needs to use information that was transmitted to it using
a mechanism described by this specification, it performs the following steps:
        </p>

        <ol>
          <li>
The software transforms the incoming data into a document that can be understood
by the applicable algorithm provided in Section [[[#verify-proof]]] or Section
[[[#verify-proof-sets-and-chains]]].
          </li>
          <li>
The software uses JSON Schema or an equivalent mechanism to validate that the
incoming document follows an expected schema used by the application.
          </li>
          <li>
The software uses the applicable algorithm(s) provided in Section [[[#verify-proof]]]
or Section [[[#verify-proof-sets-and-chains]]] to verify the integrity of the
incoming document.
          </li>
          <li>
If the document is a JSON-LD document, the software uses the algorithm provided
in Section [[[#context-validation]]], or one providing equivalent protections,
to validate all JSON-LD Context values used in the document.
          </li>
        </ol>

      </section>

      <section class="normative">
        <h3>Add Proof</h3>

        <p>
The following algorithm specifies how a digital proof can be added to an [=input
document=], and can then be used to verify the output document's authenticity
and integrity. Required inputs are an [=input document=] ([=map=]
|inputDocument|), a [=cryptosuite instance=] ([=struct=] |cryptosuite|), and a
set of options ([=map=] |options|). Output is a [=secured data document=]
([=map=]) or an error. Whenever this algorithm encodes strings, it MUST use
UTF-8 encoding.
        </p>

        <ol class="algorithm">
          <li>
Let |proof| be the result of calling the [=cryptosuite instance/createProof=]
algorithm specified in |cryptosuite|.|createProof| with |inputDocument|
and |options| passed as a parameters. If the algorithm produces an error,
the error MUST be propagated and SHOULD convey the error type.
          </li>
          <li>
If one or more of the |proof|.|type|, |proof|.|verificationMethod|, and
|proof|.|proofPurpose| values is not set, an error MUST be raised and SHOULD
convey an error type of
<a href="#PROOF_GENERATION_ERROR">PROOF_GENERATION_ERROR</a>.
          </li>
          <li>
If |options| has a non-null |domain| [=struct/item=], it MUST be equal to
|proof|.|domain| or an error MUST be raised and SHOULD convey
an error type of <a href="#PROOF_GENERATION_ERROR">PROOF_GENERATION_ERROR</a>.
          </li>
          <li>
If |options| has a non-null |challenge| [=struct/item=], it MUST be equal to
|proof|.|challenge| or an error MUST be raised and SHOULD
convey an error type of
<a href="#PROOF_GENERATION_ERROR">PROOF_GENERATION_ERROR</a>.
          </li>
          <li>
Let |securedDataDocument| be a copy of |inputDocument|.
          </li>
          <li>
Set |securedDataDocument|.|proof| to the value of |proof|.
          </li>
          <li>
Return |securedDataDocument| as the [=secured data document=].
          </li>
        </ol>

      </section>
      <section>
        <h3>Add Proof Set/Chain</h3>
        <p>
The following algorithm specifies how to incrementally add a proof to a proof
set or proof chain starting with a secured document containing either a proof or
proof set/chain. Required inputs are a [=secured data document=] ([=map=]
|securedDocument|), a [=cryptographic suite=] ([=cryptosuite
instance=] |suite|), and a set of options ([=map=] |options|). Output is a new
[=secured data document=] ([=map=]). Whenever this algorithm encodes strings, it
MUST use UTF-8 encoding.
        </p>

        <ol class="algorithm">
          <li>
Let |proof| be set to |securedDocument|.|proof|. Let
|allProofs| be an empty list. If |proof| is a list, copy all
the elements of |proof| to |allProofs|. If |proof|
is an object add a copy of that object to |allProofs|.
          </li>
          <li>
Let the |inputDocument| be a copy of the |securedDocument|
with the |proof| attribute removed. Let |output| be a copy of
the |inputDocument|.
          </li>
          <li>
Let |matchingProofs| be an empty list.
          </li>
          <li>
If |options| has a `previousProof` [=struct/item=] that is a string, add the
element from |allProofs| with an `id` attribute matching `previousProof` to
|matchingProofs|. If a proof with `id` equal to `previousProof` does not exist in
|allProofs|, an error MUST be raised and SHOULD convey an error type of
<a href="#PROOF_GENERATION_ERROR">PROOF_GENERATION_ERROR</a>.
          </li>
          <li>
If |options| has a `previousProof` [=struct/item=] that is an array, add each
element from |allProofs| with an `id` attribute that matches an element of that
array. If any element of `previousProof` [=list=] has an `id` attribute that does
not match the `id` attribute of any element of |allProofs|, an error MUST be
raised and SHOULD convey an error type of
<a href="#PROOF_GENERATION_ERROR">PROOF_GENERATION_ERROR</a>.
          </li>
          <li>
Set |inputDocument|.|proof| to |matchingProofs|.
            <div class="note" title="This step protects the document and existing proofs">
              <p>
This step adds references to the [=named graphs=], as well as adding a copy of
<em>all</em> the claims contained in the [=proof graphs=]. The step is critical,
as it <q>binds</q> any matching proofs to the document prior to applying the
current proof. The |proof| value for the document will be updated in a later
step of this algorithm.
              </p>
            </div>
          </li>
          <li>
Run steps 1 through 6 of the algorithm in section [[[#add-proof]]], passing
|inputDocument|, |suite|, and |options|. If no exceptions are raised, append
the generated |proof| value to the |allProofs|; otherwise, raise the exception.
          </li>
          <li>
Set |output|.|proof| to the value of |allProofs|.
          </li>
          <li>
Return |output| as the new [=secured data document=].
          </li>
        </ol>
      </section>

      <section>
        <h3>Verify Proof</h3>

        <p>
The following algorithm specifies how to check the authenticity and integrity of
a [=secured data document=] by verifying its digital proof. The algorithm
takes as input:
        </p>

        <dl>
          <dt>|mediaType|</dt>
          <dd>
A [=MIME type|media type=] as defined in [[MIMESNIFF]]
          </dd>
          <dt>|documentBytes|</dt>
          <dd>
A [=byte sequence=] whose media type is |mediaType|
          </dd>
          <dt>|cryptosuite|</dt>
          <dd>
A [=cryptosuite instance=]
          </dd>
          <dt>|expectedProofPurpose|</dt>
          <dd>
An optional [=string=], used to ensure that the |proof| was generated by the
proof creator for the expected reason by the verifier. See [[[#proof-purposes]]]
for common values
          <dt>|domain|</dt>
          <dd>
An optional [=set=] of [=strings=], used by the proof creator to lock a proof to
a particular security domain, and used by the verifier to ensure that a proof is
not being used across different security domains
          </dd>
          <dt>|challenge|</dt>
          <dd>
An optional [=string=] [=challenge=], used by the verifier to ensure that an
attacker is not replaying previously created proofs
          </dd>
        </dl>

        <p>
This algorithm returns a <dfn>verification result</dfn>, a [=struct=] whose
[=struct/items=] are:
        </p>
        <dl data-dfn-for="verification result">
          <dt><dfn data-dfn-for="verification result">verified</dfn></dt>
          <dd>`true` or `false`</dd>
          <dt><dfn data-dfn-for="verification result">verifiedDocument</dfn></dt>
          <dd>
<a data-cite="INFRA#nulls">Null</a>, if [=verification result/verified=] is
`false`; otherwise, an [=input document=]
          </dd>
          <dt><dfn data-dfn-for="verification result">mediaType</dfn></dt>
          <dd>
<a data-cite="INFRA#nulls">Null</a>, if [=verification result/verified=] is
`false`; otherwise, a [=MIME type|media type=], which MAY include [=MIME
type/parameters=]
          </dd>
          <dt><dfn data-dfn-for="verification result" class="lint-ignore">warnings</dfn></dt>
          <dd>
a [=list=] of [=ProblemDetails=], which defaults to an empty [=list=]
          </dd>
          <dt><dfn data-dfn-for="verification result">errors</dfn></dt>
          <dd>
a [=list=] of [=ProblemDetails=], which defaults to an empty [=list=]
          </dd>
        </dl>

        <p>
When a step says "an error MUST be raised", it means that a [=verification
result=] MUST be returned with a [=verification result/verified=] value of
`false` and a non-empty [=verification result/errors=] list.
        </p>

        <ol class="algorithm">
          <li>
Let |securedDocument:map| be the result of running [=parse JSON bytes to an
Infra value=] on |documentBytes|.
          </li>
          <li>
If either |securedDocument| is not a [=map=] or |securedDocument|.|proof|
is not a [=map=], an error MUST be raised and SHOULD convey an error type of
<a href="https://www.w3.org/TR/VC-DATA-MODEL-2.0#PARSING_ERROR">
PARSING_ERROR</a>.
          </li>
          <li>
Let |proof:map| be |securedDocument|.|proof|.
          </li>
          <li>
If one or more of |proof|.|type|,
|proof|.|verificationMethod|, and
|proof|.|proofPurpose| does not [=map/exist=],
an error MUST be raised and SHOULD convey an error type of
<a href="#PROOF_VERIFICATION_ERROR">PROOF_VERIFICATION_ERROR</a>.
          </li>
          <li>
If |expectedProofPurpose| was given, and it does not match
|proof|.|proofPurpose|,
an error MUST be raised and SHOULD convey an error type of
<a href="#PROOF_VERIFICATION_ERROR">PROOF_VERIFICATION_ERROR</a>.
          </li>
          <li>
If |domain| was given, and it does not contain the same [=strings=] as
|proof|.|domain| (treating a single [=string=] as a [=set=] containing just
that [=string=]), an error MUST be raised and SHOULD convey an error type of <a
href="#INVALID_DOMAIN_ERROR">INVALID_DOMAIN_ERROR</a>.
          </li>
          <li>
If |challenge| was given, and it does not match
|proof|.|challenge|, an error MUST be raised and SHOULD
convey an error type of
<a href="#INVALID_CHALLENGE_ERROR">INVALID_CHALLENGE_ERROR</a>.
          </li>
          <li>
Let |cryptosuiteVerificationResult| be the result of running the
|cryptosuite|.[=cryptosuite instance/verifyProof=] algorithm with
|securedDocument| provided as input.
          </li>
          <li>
Return a [=verification result=] with [=struct/items=]:
            <dl data-link-for="verification result">
              <dt>[=verified=]</dt>
              <dd>|cryptosuiteVerificationResult|.|verified|</dd>
              <dt>[=verifiedDocument=]</dt>
              <dd>|cryptosuiteVerificationResult|.|verifiedDocument|</dd>
              <dt>[=mediaType=]</dt>
              <dd>|mediaType|</dd>
            </dl>
          </li>
        </ol>

      </section>
      <section>
        <h3>Verify Proof Sets and Chains</h3>
        <p>
In a [=proof set=] or [=proof chain=], a [=secured data document=] has a `proof`
attribute which contains a list of [=proofs=] (|allProofs|). The following
algorithm provides one method of checking the authenticity and integrity of a
[=secured data document=], achieved by verifying every proof in |allProofs|.
Other approaches are possible, particularly if it is only desired to verify a
subset of the proofs contained in |allProofs|. If another approach is taken to
verify only a subset of the proofs, then it is important to note that any proof
in that subset with a `previousProof` can only be considered verified if the
proofs it references are also considered verified.
        </p>
        <p>
Required input is a [=secured data document=] (|securedDocument|). A list of
[=verification results=] corresponding to each proof in |allProofs| is
generated, and a single combined [=verification result=] is returned as output.
Implementations MAY return any of the other [=verification result=]s and/or any
other metadata alongside the combined [=verification result=].
        </p>
        <ol class="algorithm">
          <li>
Set |allProofs| to </var>|securedDocument|.|proof|.
          </li>
          <li>
Set |verificationResults| to an empty list.
          </li>
          <li>
For each |proof| in |allProofs|, do the following steps:
            <ol class="algorithm">
              <li>
Let |matchingProofs| be an empty list.
              </li>
              <li>
If |proof| contains a `previousProof` attribute and the value of that
attribute is a [=string=], add the element from |allProofs| with an `id`
attribute value matching the value of `previousProof` to `matchingProofs`.
If a proof with `id` value equal to the value of `previousProof` does not
exist in |allProofs|, an error MUST be raised and SHOULD convey an error
type of
<a href="#PROOF_VERIFICATION_ERROR">PROOF_VERIFICATION_ERROR</a>. If the
`previousProof` attribute is a [=list=], add each element from |allProofs|
with an `id` attribute value that matches the value of an element of that
[=list=]. If any element of `previousProof` [=list=] has an `id` attribute
value that does not match the `id` attribute value of any element of
|allProofs|, an error MUST be raised and SHOULD convey an error type of
<a href="#PROOF_VERIFICATION_ERROR">PROOF_VERIFICATION_ERROR</a>.
              </li>
              <li>
Let |inputDocument| be a copy of |securedDocument| with the proof value
removed and then set |inputDocument|.|proof| to |matchingProofs|.

                <p class="note" title="Secure document and previous proofs">
See the note in Step 6 of Section [[[#add-proof-set-chain]]] to learn about
what document properties and previous proofs this step secures.
                </p>
              </li>
              <li>
Run steps 4 through 8 of the algorithm in section [[[#verify-proof]]] on
|inputDocument|; if no exceptions are raised, append |cryptosuiteVerificationResult|
to |verificationResults|.
                </li>
            </ol>
          </li>
          <li>
Set |successfulVerificationResults| to an empty list.
          </li>
          <li>
Let |combinedVerificationResult| be an empty struct. Set |combinedVerificationResult|.|status|
to `true`, |combinedVerificationResult|.|document| to `null`, and
|combinedVerificationResult|.|mediaType| to `null`.
          </li>
          <li>
For each |cryptosuiteVerificationResult| in |verificationResults|:
            <ol class="algorithm">
              <li>
If |cryptosuiteVerificationResult|.|verified| is `false`, set |combinedVerificationResult|.|verified|
to `false`.
              </li>
              <li>
Otherwise, set |combinedVerificationResult|.|document| to
|cryptosuiteVerificationResult|.|verifiedDocument|, set
|combinedVerificationResult|.|mediaType| to |cryptosuiteVerificationResult|.|mediaType|, and
append |cryptosuiteVerificationResult| to |successfulVerificationResults|.
              </li>
            </ol>
          </li>
          <li>
If |combinedVerificationResult|.|status| is `false`, set
|combinedVerificationResult|.|document| to `null` and
|combinedVerificationResult|.|mediaType| to `null`.
          </li>
          <li>
Return |combinedVerificationResult|, |successfulVerificationResults|.
          </li>
        </ol>
      </section>

      <section class="normative">
        <h3>Context Validation</h3>

        <p>
The following algorithm provides one mechanism that can be used to ensure that
an application understands the contexts associated with a document before it
executed business rules specific to the input in the document. For more
rationale related to this algorithm, see Section [[[#validating-contexts]]].
This algorithm takes inputs of a document ([=map=] |inputDocument|), a set of
known JSON-LD Contexts ([=list=] |knownContext|), and a boolean to
recompact when unknown contexts are detected ([=boolean=] |recompact|).
        </p>

        <p>
This algorithm returns a <dfn class="lint-ignore">context validation result</dfn>,
a [=struct=] whose [=struct/items=] are:
        </p>
        <dl data-dfn-for="context validation result">
          <dt><dfn data-dfn-for="context validation result">validated</dfn></dt>
          <dd>`true` or `false`</dd>
          <dt><dfn data-dfn-for="context validation result" class="lint-ignore">validatedDocument</dfn></dt>
          <dd>
<a data-cite="INFRA#nulls">Null</a>, if [=context validation result/validated=] is
`false`; otherwise, an [=input document=]
          </dd>
          <dt><dfn data-dfn-for="context validation result" class="lint-ignore">warnings</dfn></dt>
          <dd>
a [=list=] of [=ProblemDetails=], which defaults to an empty [=list=]
          </dd>
          <dt><dfn data-dfn-for="context validation result" class="lint-ignore">errors</dfn></dt>
          <dd>
a [=list=] of [=ProblemDetails=], which defaults to an empty [=list=]
          </dd>
        </dl>

        <p>
The context validation algorithm is as follows:
        </p>

        <ol class="algorithm">
          <li>
Set |result|.|validated| to `false`, |result|.|warnings| to an empty list,
|result|.|errors| to an empty list, |compactionContext| to an empty list;
and clone |inputDocument| to |result|.|validatedDocument|.
          </li>
          <li>
Let |contextValue| be the value of the `@context` property of |result|.|validatedDocument|,
which might be undefined.
          </li>
          <li>
If |contextValue| does not deeply equal |knownContext|, any subtree in
|result|.|validatedDocument| contains an `@context` property, or any URI in
|contextValue| dereferences to a JSON-LD Context file that does not match a
known good value or cryptographic hash, then perform the applicable action:
            <ol class="algorithm">
              <li>
If |recompact| is `true`, set |result|.|validatedDocument| to the result
of running the <a data-cite="JSON-LD11-API#compaction-algorithm">
JSON-LD Compaction Algorithm</a> with the |inputDocument| and
|knownContext| as inputs. If the compaction fails, add at least one error
to |result|.|errors|.
              </li>
              <li>
If |recompact| is not `true`, add at least one error to |result|.|errors|.
              </li>
            </ol>
          </li>
          <li>
If |result|.|errors| is empty, set |result|.|validated| to `true`; otherwise, set
|result|.|validated| to `false`, and remove the |document| property from |result|.
          </li>
          <li>
Return the value of |result|.
          </li>
        </ol>

        <p>
Implementations MAY include additional warnings or errors that enforce
further validation rules that are specific to the implementation or a
particular use case.
        </p>

      </section>

      <section class="normative">
        <h3>Processing Errors</h3>

        <p>
The algorithms described in this specification, as well as in various cryptographic
suite specifications, throw specific types of errors. Implementers might find
it useful to convey these errors to other libraries or software systems. This
section provides specific URLs and descriptions for the errors,
such that an ecosystem implementing technologies described by this
specification might interoperate more effectively when errors occur.
        </p>

        <p>
When exposing these errors through an HTTP interface, implementers SHOULD use
[[RFC9457]] to encode the error data structure as a <dfn>ProblemDetails</dfn>
[=map=]. If [[RFC9457]] is used:
        </p>

        <ul>
          <li>
The `type` value of the error object MUST be a URL that starts with the value
`https://w3id.org/security#` and ends with the value in the section listed
below.
          </li>
          <li>
The `title` value SHOULD provide a short but specific human-readable [=string=] for
the error.
          </li>
          <li>
The `detail` value SHOULD provide a longer human-readable [=string=] for the error.
          </li>
        </ul>

        <dl>
          <dt id="PROOF_GENERATION_ERROR">PROOF_GENERATION_ERROR</dt>
          <dd>
A request to generate a proof failed. See Section [[[#add-proof]]], and Section
[[[#add-proof-set-chain]]].
          </dd>
          <dt id="PROOF_VERIFICATION_ERROR">PROOF_VERIFICATION_ERROR</dt>
          <dd>
An error was encountered during proof verification. See Section [[[#verify-proof]]].
          </dd>
          <dt id="PROOF_TRANSFORMATION_ERROR">PROOF_TRANSFORMATION_ERROR </dt>
          <dd>
An error was encountered during the transformation process.
          </dd>
          <dt id="INVALID_DOMAIN_ERROR">INVALID_DOMAIN_ERROR</dt>
          <dd>
The `domain` value in a proof did not match the expected value. See Section
[[[#verify-proof]]].
          </dd>
          <dt id="INVALID_CHALLENGE_ERROR">INVALID_CHALLENGE_ERROR</dt>
          <dd>
The `challenge` value in a proof did not match the expected value. See Section
[[[#verify-proof]]].
          </dd>
        </dl>
      </section>
    </section>

    <section>
      <h2>Security Considerations</h2>
      <p>
The following section describes security considerations that developers
implementing this specification should be aware of in order to create secure
software.
      </p>

      <section>
        <h3>Versioning Cryptography Suites</h3>

        <p>
Cryptography secures information through the use of secrets. Knowledge of the
necessary secret makes it computationally easy to access certain information. The
same information can be accessed if a computationally-difficult, brute-force effort
successfully guesses the secret. All modern cryptography requires the
computationally difficult approach to remain difficult throughout time, which
does not always hold due to breakthroughs in science and mathematics. That is
to say that <em>Cryptography has a shelf life</em>.
        </p>
        <p>
This specification plans for the obsolescence of all cryptographic approaches by
asserting that whatever cryptography is in use today is highly likely to be
broken over time. Software systems have to be able to change the cryptography
in use over time in order to continue to secure information. Such changes might
involve increasing required secret sizes or modifications to the cryptographic
primitives used. However, some combinations of cryptographic parameters
might actually reduce security. Given these assumptions, systems need to be able to
distinguish different combinations of safe cryptographic parameters, also known
as cryptographic suites, from one another. When identifying or versioning
cryptographic suites, there are several approaches that can be taken which
include: parameters, numbers, and dates.
        </p>
        <p>
Parametric versioning specifies the particular cryptographic parameters that are
employed in a cryptographic suite. For example, one could use an identifier such
as `RSASSA-PKCS1-v1_5-SHA1`. The benefit to this scheme is that a well-trained
cryptographer will be able to determine all of the parameters in play by the
identifier. The drawback to this scheme is that most of the population that
uses these sorts of identifiers are not well trained and thus will not understand
that the previously mentioned identifier is a cryptographic suite that is no
longer safe to use. Additionally, this lack of knowledge might lead software
developers to generalize the parsing of cryptographic suite identifiers
such that any combination of cryptographic primitives becomes acceptable,
resulting in reduced security. Ideally, cryptographic suites are implemented
in software as specific, acceptable profiles of cryptographic parameters instead.
        </p>
        <p>
Numbered versioning might specify a major and minor version number such as
`1.0` or `2.1`. Numbered versioning conveys a specific order and suggests that
higher version numbers are more capable than lower version numbers. The benefit
of this approach is that it removes complex parameters that less expert
developers might not understand with a simpler model that conveys that an
upgrade might be appropriate. The drawback of this approach is that its not
clear if an upgrade is necessary, as software version number increases often
don't require an upgrade for the software to continue functioning. This can
lead to developers thinking their usage of a particular version is safe, when
it is not. Ideally, additional signals would be given to developers that use
cryptographic suites in their software that periodic reviews of those
suites for continued security are required.
        </p>
        <p>
Date-based versioning specifies a particular release date for a specific
cryptographic suite. The benefit of a date, such as a year, is that it is
immediately clear to a developer if the date is relatively old or new. Seeing
an old date might prompt the developer to go searching for a newer
cryptographic suite, where as a parametric or number-based versioning scheme
might not. The downside of a date-based version is that some cryptographic
suites might not expire for 5-10 years, prompting the developer to go
searching for a newer cryptographic suite only to not find one that is newer.
While this might be an inconvenience, it is one that results in safer
ecosystem behavior.
        </p>

      </section>

      <section>
        <h3>Protecting Application Developers</h3>

        <p>
Modern cryptographic algorithms provide a number of tunable parameters and
options to ensure that the algorithms can meet the varied requirements of different use cases.
For example, embedded systems have limited processing and memory environments
and might not have the resources to generate the strongest digital signatures
for a given algorithm. Other environments, like financial trading systems,
might only need to protect data for a day while the trade is occurring, while
other environments might need to protect data for multiple decades. To meet
these needs, cryptographic algorithm designers often provide multiple ways to
configure a cryptographic algorithm.
        </p>
        <p>
Cryptographic library implementers often take the specifications created by
cryptographic algorithm designers and specification authors and implement them
such that all options are available to the application developers that use their
libraries. This can be due to not knowing which combination of features a
particular application developer might need for a given cryptographic deployment.
All options are often exposed to application developers.
        </p>
        <p>
Application developers that use cryptographic libraries often do not have the
requisite cryptographic expertise and knowledge necessary to appropriately
select cryptographic parameters and options for a given application. This lack
of expertise can lead to an inappropriate selection of cryptographic parameters
and options for a particular application.
        </p>
        <p>
This specification sets the priority of constituencies to protect application
developers over cryptographic library implementers over cryptographic
specification authors over cryptographic algorithm designers. Given these
priorities, the following recommendations are made:
        </p>
        <ul>
          <li>
Cryptographic algorithm designers are advised [[?RFC7696]] to minimize the
number of options and parameters to as few as possible to ensure that
cryptographic library implementers have a more easily auditable security attack
surface for their software libraries.
          </li>
          <li>
Cryptographic specification authors are advised to, if possible, further
minimize the number of options and parameters to as few as possible to ensure
cryptographic agility while also keeping the auditable security
attack surface for downstream software libraries to a minimum.
          </li>
          <li>
Cryptographic library implementers are advised to, if possible, provide known
good combinations of options and parameters to application developers. There
would ideally be two pre-set default configurations for any algorithmic
class, such as Elliptic Curve Digital Signatures, with no ability
to fine tune parameters and options when using these pre-sets. Library options can be provided to
experts to fine tune their use of the library, use of those options by the general
application developer population is to be discouraged.
          </li>
          <li>
Cryptographic library implementers can provide deprecated and experimental
cryptographic functionality, but are advised to only do so when explicitly
requested by the developer, such as through a library option, and such that the
library produces warnings that deprecated or experimental cryptography has
been enabled for the application.
          </li>
          <li>
Application developers are advised to choose from a number of pre-set
cryptography library configurations and to avoid modifying cryptographic
options and parameters, or using experimental or deprecated cryptography.
          </li>
        </ul>

        <p>
The guidance above is meant to ensure that useful cryptographic options and
parameters are provided at the lower layers of the architecture while not
exposing those options and parameters to application developers who may not
fully understand the balancing benefits and drawbacks of each option.
        </p>

      </section>

      <section>
        <h3>Conventions for Naming Cryptography Suites</h3>
        <p>
Section [[[#versioning-cryptography-suites]]] emphasized the importance of
providing relatively easy to understand information concerning the timeliness of
particular cryptographic suite, while section
[[[#protecting-application-developers]]] further emphasized minimizing the
number of options to be specified. Indeed, section [[[#cryptographic-suites]]]
lists requirements for cryptographic suites which include detailed specification
of algorithm, transformation, hashing, and serialization. Hence, the name of the
cryptographic suite does not need to include all this detail, which implies the
<em>parametric versioning</em> mentioned in section
[[[#versioning-cryptography-suites]]] is neither necessary nor desirable.
        </p>
        <p>
The recommended naming convention for cryptographic suites is a
string composed of a signature algorithm identifier, separated by a hyphen from
an option identifier (if the cryptosuite supports incompatible
implementation options), followed by a hyphen and designation of the
approximate year that the suite was proposed.
        </p>
        <p>
For example, the [[?DI-EDDSA]] is based on EdDSA digital signatures, supports
two incompatible options based on canonicalization approaches, and was proposed
in roughly the year 2022, so it would have two different cryptosuite names:
<q>eddsa-rdfc-2022</q> and <q>eddsa-jcs-2022</q>.
        </p>
        <p>
Although the [[?DI-ECDSA]] is based on ECDSA digital signatures, supports the
same two incompatible canonicalization approaches as [[?DI-EDDSA]], and supports
two different levels of security (128 bit and 192 bit) via two alternative sets
of elliptic curves and hashes, it has only two cryptosuite names:
<q>ecdsa-rdfc-2019</q> and <q>ecdsa-jcs-2019</q>. The security level and corresponding
curves and hashes are determined from the multi-key format of the public key
used in validation.
        </p>
      </section>

      <section>
        <h3>Agility and Layering</h3>

        <p>
<dfn class="lint-ignore">Cryptographic agility</dfn> is a practice by which one designs
<em>frequently connected</em> information security systems to support
<em>switching between multiple cryptographic primitives and/or algorithms</em>. The primary
goal of cryptographic agility is to enable systems to rapidly adapt to new
cryptographic primitives and algorithms without making disruptive changes to the
systems' infrastructure. Thus, when a particular cryptographic primitive, such
as the SHA-1 algorithm, is determined to be no longer safe to use, systems can
be reconfigured to use a newer primitive via a simple configuration file change.
        </p>
        <p>
Cryptographic agility is most effective when the client and the server in
the information security system are in regular contact. However, when the
messages protected by a particular cryptographic algorithm are long-lived, as
with [=verifiable credentials=], and/or when the client (holder) might not be
able to easily recontact the server (issuer), then cryptographic agility does
not provide the desired protections.
        </p>
        <p>
<dfn class="lint-ignore">Cryptographic layering</dfn> is a practice where one
designs <em>rarely connected</em> information security systems to
<em>employ multiple primitives and/or algorithms at the same time</em>. The
primary goal of cryptographic layering is to enable systems to survive the
failure or one or more cryptographic algorithms or primitives without losing
cryptographic protection on the payload. For example, digitally signing a single
piece of information using RSA, ECDSA, and Falcon algorithms in parallel would
provide a mechanism that could survive the failure of two of these three digital
signature algorithms. When a particular cryptographic protection is compromised,
such as an RSA digital signature using 768-bit keys, systems can still utilize
the non-compromised cryptographic protections to continue to protect the
information. Developers are urged to take advantage of this feature for all
signed content that might need to be protected for a year or longer.
        </p>
        <p>
This specification provides for both forms of agility. It provides for
cryptographic agility, which allows one to easily switch from one algorithm to
another. It also provides for cryptographic layering, which allows one to
simultaneously use multiple cryptographic algorithms, typically in parallel,
such that any of those used to protect information can be used without reliance
on or requirement of the others, while still keeping the digital proof format
easy to use for developers.
        </p>
        <p>
        </p>
      </section>

      <section>
        <h3>Safer Abstractions</h3>

        <p>
A [=proof=] contains a `proofValue`, in which a number of parameters
related to a cryptographic proof can be embedded. For example,
the selective disclosure algorithms in the [[[?VC-DI-ECDSA]]] specification
include multiple cryptographic signatures in the `proofValue`, one for every
item that is selectively disclosable. This has been done to make the
technology easier and safer to use by application developers.
        </p>

        <p>
This specification urges specification authors to use a single value to abstract
information that is rarely needed by the application layer. Much like a `data:`
URL expressing an image encapsulates many of the image rendering parameters into
a single value, the `proofValue` property (and other similar properties)
abstracts information that is not useful to an application developer in order to
simplify identification of fields that <em>are</em> important to the application.
Abstracting information in this way leads to a data structure that is easier for
developers to work with while being less susceptible to, for instance, accidental
corruption due to a programming error that adds or removes a critical property,
negatively impacting the cryptographic layer.
        </p>

        <p>
The design of data integrity in this specification abstracts information that is
generally only useful to the cryptographic layer into a single property to ease
the burden on application developers and to enhance the security of the system.
        </p>
      </section>

      <section>
        <h3>Transformations</h3>

        <p>
At times, it is beneficial to transform the data being protected during the
cryptographic protection process. Such "in-line" transformation can enable a
particular type of cryptographic protection to be agnostic to the data format it
is carried in. For example, some Data Integrity cryptographic suites utilize RDF
Dataset Canonicalization [[?RDF-CANON]] which transforms the initial
representation into a canonical form [[?N-QUADS]] that is then serialized,
hashed, and digitally signed. As long as any syntax expressing the protected
data can be transformed into this canonical form, the digital signature can be
verified. This enables the same digital signature over the information to be
expressed in JSON, CBOR, YAML, and other compatible syntaxes without having to
create a cryptographic proof for every syntax.
        </p>
        <p>
Being able to express the same digital signature across a variety of syntaxes is
beneficial because systems often have native data formats with which they
operate. For example, some systems are written against JSON data, while others
are written against CBOR data. Without transformation, systems that process
their data internally as CBOR are required to store the digitally signed data
structures as JSON (or vice-versa). This leads to double-storing data and can
lead to increased security attack surface if the unsigned representation stored in
databases accidentally deviates from the signed representation. By using
transformations, the digital proof can live in the native data format to
help prevent otherwise undetectable database drift over time.
        </p>
        <p>
This specification is designed to avoid requiring the duplication of signed
information by utilizing "in-line" data transformations. Application developers are urged
to work with cryptographically protected data in the native data format for
their application and not separate storage of cryptographic proofs from the data
being protected. Developers are also urged to regularly confirm that the
cryptographically protected data has not been tampered with as it is written to
and read from application storage.
        </p>
        <p class="advisement">
Some transformations, such as RDF Dataset Canonicalization [[?RDF-CANON]], have
mitigations for input data sets that can be used by attackers to consume
excessive processing cycles. This class of attack is called
<a data-cite="?RDF-CANON#dataset-poisoning">dataset poisoning</a>, and all
modern RDF Dataset canonicalizers are required to detect these sorts of bad
inputs and halt processing. The test suites for RDF Dataset Canonicalization
includes such poisoned datasets to ensure that such mitigations exist in all
conforming implementations. Generally speaking, cryptographic suite
specifications that use transformations are required to mitigate these sorts of
attacks, and implementers are urged to ensure that the software libraries that
they use enforce these mitigations. These attacks are in the same general
category as any resource starvation attack, such as HTTP clients that
deliberately slow connections, thus starving connections on the server.
Implementers are advised to consider these sorts of attacks when implementing
defensive security strategies.
        </p>
      </section>

      <section>
        <h3>Protected Information</h3>

        <p>
The data that is protected by any [=data integrity proof=] is the
[=transformation|transformed data=]. [=transformation|Transformed data=]
is generated by a [=transformation algorithm=] that is specified by a
particular [=cryptosuite=]. This protection mechanism differs from some
more traditional digital signature mechanisms that do not perform any sort of
[=transformation=] on the input data. The benefits of [=transformation=] are
detailed in Section [[[#transformations]]].
        </p>

        <p>
For example, [=cryptosuites=] such as
<a data-cite="?VC-DI-ECDSA#ecdsa-jcs-2019">ecdsa-jcs-2019</a> and
<a data-cite="?VC-DI-EDDSA#eddsa-jcs-2022">eddsa-jcs-2022</a> use the
[[[?RFC8785]]] to [=transformation|transform=] the data to canonicalized JSON,
which is then cryptographically hashed and digitally signed. One benefit of this
approach is that adding or removing formatting characters that do not impact the
meaning of the information being signed, such as spaces, tabs, and newlines,
does not invalidate the digital signature. More traditional digital signature
mechanisms do not have this capability.
        </p>

        <p>
Other [=cryptosuites=] such as
<a data-cite="?VC-DI-ECDSA#ecdsa-rdfc-2019">ecdsa-rdfc-2019</a> and
<a data-cite="?VC-DI-EDDSA#eddsa-rdfc-2022">eddsa-rdfc-2022</a> use
[[[?RDF-CANON]]] to [=transformation|transform=] the data to canonicalized
N-Quads [[?N-QUADS]], which is then cryptographically hashed and digitally
signed. One benefit of this approach is that the cryptographic signature is
portable to a variety of different syntaxes, such as JSON, YAML, and CBOR,
without invalidating the signature. More traditional cryptographic signature
mechanisms do not have this capability.
        </p>

        <p>
Implementers and developers are urged to not trust information
that contains a [=data integrity proof=] unless the proof has been [=verified=]
and the verified data is provided in a return value from a software library
that has confirmed that all data returned has been successfully protected.
        </p>

      </section>

      <section>
        <h3>Data Opacity</h3>

        <p>
The inspectability of application data has effects on system efficiency and
developer productivity. When cryptographically protected application data, such
as base-encoded binary data, is not easily processed by application subsystems,
such as databases, it increases the effort of working with the cryptographically
protected information. For example, a cryptographically protected payload that
can be natively stored and indexed by a database will result in a simpler system
that:
        </p>

        <ul>
          <li>
benefits from utilizing existing industry-standard database features with no
changes to the protected information,
          </li>
          <li>
avoids the complexity of duplicating data where one copy of the data preserves
the message and digital signature, while the other copy only stores and indexes
the message and is what drives system behaviour,
          </li>
          <li>
avoids the complexity of bespoke solutions that have to structurally modify
the protected information, such as serializing and deserializing nested
digitally signed data that has multiple nested base-encoded payloads.
          </li>
        </ul>

        <p>
Similarly, a cryptographically protected payload that can be processed by
multiple upstream networked systems increases the ability to properly layer
security architectures. For example, if upstream systems do not have to
repeatedly decode the incoming payload, it increases the ability for a system to
distribute processing load by specializing upstream subsystems to actively
combat attacks. While a digital signature needs to always be checked before
taking substantive action, other upstream checks can be performed on transparent
payloads &mdash; such as identifier-based rate limiting, signature expiration
checking, or nonce/challenge checking &mdash; to reject obviously bad requests.
        </p>
        <p>
Additionally, if a developer is not able to easily view data in a system, the
ability to easily audit or debug system correctness is hampered. For example,
requiring application developers to cut-and-paste base-encoded application data
makes development more challenging and increases the chances that obvious bugs
will be missed because every message needs to go through a manually operated
base-decoding tool.
        </p>
        <p>
There are times, however, where the correct design decision is to make data
opaque. Data that does not need to be processed by other application subsystems,
as well as data that does not need to be modified or accessed by an application
developer, can be serialized into opaque formats. Examples include digital
signature values, cryptographic key parameters, and other data fields that only
need to be accessed by a cryptographic library and need not be modified by the
application developer. There are also examples where data opacity is appropriate
when the underlying subsystem does not expose the application developer to the
underlying complexity of the opaque data, such as databases that perform
encryption at rest. In these cases, the application developer continues to
develop against transparent application data formats while the database manages
the complexity of encrypting and decrypting the application data to and from
long-term storage.
        </p>
        <p>
This specification strives to provide an architecture where application data
remains in its native format and is not made opaque, while other cryptographic
data, such as digital signatures, are kept in their opaque binary encoded form.
Cryptographic suite implementers are urged to consider appropriate use of data
opacity when designing their suites, and to weigh the design trade-offs when
making application data opaque versus providing access to cryptographic data at
the application layer.
        </p>
      </section>

      <section>
        <h3>Verification Method Binding</h3>

        <p>
Implementers ensure that a [=verification method=] is bound to a particular
controller by going from the definition of the [=verification method=] to the
[=controlled identifier document=], and then ensuring that the [=controlled identifier document=] also
contains a reference to the [=verification method=]. This process is described
in the algorithm for
<a data-cite="?CID#retrieve-verification-method">
retrieving a verification method</a>.
        </p>
      </section>

      <section>
        <h3>Verification Relationship Validation</h3>

        <p>
When an implementation is <a href="#verify-proof">verifying a proof</a>, it is
imperative that it verify not only that the [=verification method=] used to
generate the proof is listed in the [=controlled identifier document=], but also that it
was intended to be used to generate the proof that is being verified. This process
is known as "verification relationship validation".
        </p>
        <p>
The process of validating a verification relationship is outlined in
Section
<a data-cite="CID#retrieve-verification-method">
3.3 Retrieve Verification Method</a> of the [[[CID]]]
specification.
        </p>
        <p>
This process is used to ensure that cryptographic material, such as a private
cryptographic key, is not misused by application to an unintended purpose. An
example of cryptographic material misuse would be if a private cryptographic
key meant to be used to issue a [=verifiable credential=] was instead used to
log into a website (that is, for authentication). Not checking a verification relationship
is dangerous because the restriction and protection profile for some
cryptographic material could be determined by its intended use. For example,
some applications could be trusted to use cryptographic material for only
one purpose, or some cryptographic material could be more protected,
such as through storage in a hardware security module in a data center
versus as an unencrypted file on a laptop.
        </p>
      </section>

      <section>
        <h3>Proof Purpose Validation</h3>

        <p>
When an implementation is <a href="#verify-proof">verifying a proof</a>, it is
imperative that it verify that the [=proof purpose=] match the intended use.
        </p>

        <p>
This process is used to ensure that proofs are not misused by an application for
an unintended purpose, as this is dangerous for the proof creator. An example of
misuse would be if a proof that stated its purpose was for securing assertions
in [=verifiable credentials=] was instead used for [=authentication=] to
log into a website. In this case, the proof creator attached proofs to any
number of [=verifiable credentials=] that they expected to be distributed to
an unbounded number of other parties. Any one of these parties could log into a
website as the proof creator if the website erroneously accepted such a proof as
[=authentication=] instead of its intended purpose.
        </p>

      </section>

      <section>
        <h3>Canonicalization Method Security</h3>

        <p>
The way in which a transformation, such as canonicalization, is performed can
affect the security characteristics of a system. Selecting the best
canonicalization mechanisms depends on the use case. Often,
the simplest mechanism that satisfies the desired security requirements
is the best choice. This section attempts to provide simple guidance to help
implementers choose between the two main canonicalization mechanisms referred to
in this specification, namely JSON Canonicalization Scheme [[RFC8785]] and
RDF Dataset Canonicalization [[RDF-CANON]].
        </p>
        <p>
If an application only uses JSON and does not depend on any form of RDF
semantics, then using a cryptography suite that uses JSON
Canonicalization Scheme [[RFC8785]] is an attractive approach.
        </p>
        <p>
If an application uses JSON-LD and needs to secure the semantics of
the document, then using a cryptography suite that
uses RDF Dataset Canonicalization [[RDF-CANON]] is an attractive
approach.
        </p>
        <p>
Implementers are also advised that other mechanisms that perform no
transformations are available, that secure the data by wrapping it in a
cryptographic envelope instead of embedding the proof in the data, such as
JWTs [[?RFC7519]] and CWTs [[?RFC8392]]. These approaches have simplicity
advantages in some use cases, at the expense of some of the benefits provided
by the approach detailed in this specification.
        </p>
      </section>

      <section>
        <h3>Canonicalization Method Correctness</h3>

        <p>
One of the algorithmic processes used by this specification is canonicalization,
which is a type of [=transformation=]. Canonicalization is the process of
taking information that might be expressed in a variety of semantically
equivalent ways as input, and expressing all output in a single way, called a
"canonical form".
        </p>
        <p>
The security of a resulting [=data integrity proof=] that utilizes
canonicalization is highly dependent on the correctness of the algorithm. For
example, if a canonicalization algorithm converts two inputs that have different
meanings into the same output, then the author's intentions can be
misrepresented to a [=verifier=]. This can be used as an attack vector by
adversaries.
        </p>
        <p>
Additionally, if semantically relevant information in an input is not present in
the output, then an attacker could insert such information into a message
without causing proof verification to fail. This is similar to another
transformation that is commonly used when cryptographically signing messages:
cryptographic hashing. If an attacker is able to produce the same cryptographic
hash from a different input, then the cryptographic hash algorithm is not
considered secure.
        </p>
        <p>
Implementers are strongly urged to ensure proper vetting of any canonicalization
algorithms to be used for [=transformation=] of input to a [=hashing=]
process. Proper vetting includes, at a minimum, association with a peer reviewed
mathematical proof of algorithm correctness; multiple implementations and vetting
by experts in a standards setting organization is preferred. Implementers are
strongly urged not to invent or use new mechanisms unless they have formal
training in information canonicalization and/or access to experts in the field
who are capable of producing a peer reviewed mathematical proof of algorithm
correctness.
        </p>
      </section>

      <section>
        <h3>Network Requests</h3>

        <p>
This specification is designed in such a way that no network requests are
required when verifying a proof on a [=conforming secured document=].
Readers might note, however, that <a href="#data-model">JSON-LD contexts</a>
and [=verification methods=] can contain URLs that might be retrieved
over a network connection. This concern exists for any URL that might be
loaded from the network during or after verification.
        </p>
        <p>
To the extent possible, implementers are urged to permanently or aggressively
cache such information to reduce the attack surface on an implementation that
might need to fetch such URLs over the network. For example, caching techniques
for <a href="#data-model">JSON-LD contexts</a> are described in Section
[[[#contexts-and-vocabularies]]], and some [=verification methods=], such as
`did:key` [[?DID-KEY]], do not need to be fetched from the network at all.
        </p>
        <p>
When it is not possible to use cached information, such as when a specific HTTP
URL-based instance of a [=verification method=] is encountered for the first
time, implementers are cautioned to use defensive measures to mitigate <a
href="https://en.wikipedia.org/wiki/Denial-of-service_attack">
denial-of-service attacks</a> during any process that might fetch a resource
from the network.
        </p>
      </section>

      <section>
        <h3>Other Security Considerations</h3>

        <p>
Since the technology to secure documents described by this specification is
generalized in nature, the security implications of its use might not be
immediately apparent to readers. To understand the sort of security
concerns one might need to consider in a complete software system, implementers
are urged to read about how this technology is used in the
[=verifiable credentials=] ecosystem [[?VC-DATA-MODEL-2.0]]; see the section
on <a data-cite="?VC-DATA-MODEL-2.0#security-considerations">
Verifiable Credential Security Considerations</a> for more information.
        </p>
      </section>

    </section>

    <section>
      <h2>Privacy Considerations</h2>
      <p>
The following section describes privacy considerations that developers
implementing this specification should be aware of in order to create
privacy enhancing software.
      </p>

      <section>
        <h3>Unlinkability</h3>

        <p>
When a digitally-signed payload contains data that is seen by multiple
verifiers, it becomes a point of correlation. An example of such data is a
shopping loyalty card number. Correlatable data can be used for tracking
purposes by verifiers, which can sometimes violate privacy expectations. The
fact that some data can be used for tracking might not be immediately apparent.
Examples of such correlatable data include, but are not limited to, a static
digital signature or a cryptographic hash of an image.
        </p>

        <p>
It is possible to create a digitally-signed payload that does not have any
correlatable tracking data while also providing some level of assurance that the
payload is trustworthy for a given interaction. This characteristic is called
<dfn class="lint-ignore">unlinkability</dfn> which ensures that no correlatable
data are used in a digitally-signed payload while still providing some level of
trust, the sufficiency of which has to be determined by each verifier.
        </p>

        <p>
It is important to understand that not all use cases require or even permit
unlinkability. There are use cases where linkability and correlation are
required due to regulatory or safety reasons, such as correlating organizations
and individuals that are shipping and storing hazardous materials. Unlinkability
is useful when there is an expectation of privacy for a particular interaction.
        </p>

        <p>
There are at least two mechanisms that can provide some level of unlinkability.
The first method is to ensure that no data value used in the message is ever
repeated in a future message. The second is to ensure that any repeated data
value provides adequate herd privacy such that it becomes practically impossible
to correlate the entity that expects some level of privacy in the interaction.
        </p>

        <p>
A variety of methods can be used to achieve unlinkability. These methods include
ensuring that a message is a single use bearer token with no information that
can be used for the purposes of correlation, using attributes that ensure an
adequate level of herd privacy, and the use of cryptosuites that enable the
entity presenting a message to regenerate new signatures while not compromising
the trust in the message being presented.
        </p>
      </section>

      <section>
        <h3>Selective Disclosure</h3>

        <p>
Selective disclosure is a technique that enables the recipient of a
previously-signed message (that is, a message signed by its creator) to reveal
only parts of the message without disturbing the verifiability of those
parts. For example, one might selectively disclose a digital driver's license for
the purpose of renting a car. This could involve revealing only the issuing
authority, license number, birthday, and authorized motor vehicle class from
the license. Note that in this case, the license number is correlatable
information, but some amount of privacy is preserved because the driver's
full name and address are not shared.
        </p>

        <p>
Not all software or cryptosuites are capable of providing selective disclosure.
If the author of a message wishes it to be selectively disclosable by its
recipient, then they need to enable selective disclosure on the specific
message, and both need to use a capable cryptosuite. The author might also make
it mandatory to disclose certain parts of the message. A recipient that wants to
selectively disclose partial content of the message needs to utilize software
that is able to perform the technique. An example of a cryptosuite that supports
selective disclosure is `bbs-2023`.
        </p>

        <p>
It is possible to selectively disclose information in a way that does not
preserve unlinkability. For example, one might want to disclose the inspection
results related to a shipment, which include the shipment identifier or lot
number, which might have to be correlatable due to regulatory requirements.
However, disclosure of the entire inspection result might not be required as
selectively disclosing just the pass/fail status could be deemed adequate. For
more information on disclosing information while preserving privacy, see Section
[[[#unlinkability]]].
        </p>
      </section>

      <section>
        <h3>Previous Proofs</h3>

        <p>
When using the `previousProof` feature defined in [[[#proof-chains]]],
implementations are required to digitally sign over one or more previous proofs,
so as to include them in the secured payload. This inevitably exposes
information related to each entity that added a previous proof.
        </p>
        <p>
At minimum, the [=verification method=] for the previous proof, such as a
public key, is seen by the creator of the next proof in a proof chain. This
can be a privacy concern if the creator of the previous proof did not intend
to be included in a proof chain, but is an inevitable outcome when
adding a non-repudiable digital signature to a document of any kind.
        </p>
        <p>
It is possible to use more advanced cryptographic mechanisms, such as a
<a href="https://en.wikipedia.org/wiki/Group_signature">group signature</a>,
to hide the identity of the signer of a message,
and it is also possible for a Data Integrity cryptographic suite
to mitigate this privacy concern.
        </p>
      </section>

      <section>
        <h3>Fingerprinting Network Requests</h3>

        <p>
Fingerprinting concerns exist for any URL that might be loaded from the network
during or after <a href="#verify-proof">proof verification</a>. This
specification is designed in such a way that no network requests are necessary
when verifying a proof on a [=conforming secured document=]. Readers might
note, however, that <a href="#data-model">JSON-LD contexts</a> and
[=verification methods=] can contain resource URLs that might be retrieved
over a network connection leading to fingerprinting concerns.
        </p>

        <p>
For example, creators of [=conforming secured documents=] might craft unique
per-document URLs for <a href="#data-model">JSON-LD contexts</a> and
[=verification methods=]. When verifying such a document, a verifier fetching
that information from the network would reveal their interest in the
[=conforming secured document=] to the creator of the document, which might lead
to a mismatch in privacy expectations for any entity that is not the creator of
the document.
        </p>

        <p>
Implementers are urged to follow the guidance in Section [[[#network-requests]]]
on URL caching and implementing defensively when fetching URLs from the network.
Usage of techniques such as
<a href="https://datatracker.ietf.org/doc/html/draft-ietf-ohai-ohttp">
Oblivious HTTP</a> to retrieve resources from the network, without revealing the
client that is making the request, are encouraged. Additionally, heuristics
might be used to determine whether creators of [=conforming secured documents=]
are using fingerprinting URLs in a way that might violate privacy expectations.
These heuristics could be used to display warnings to entities that might
process documents containing suspected fingerprinting URLs.
        </p>
      </section>

      <section>
        <h3>Canonicalization Method Privacy</h3>

        <p>
The way in which a transformation, namely canonicalization, is performed can
affect the privacy characteristics of a system. Selecting the best
canonicalization mechanism depends on the use case.
This section attempts to provide simple guidance to help
implementers pick between the two main canonicalization mechanisms referred to
in this specification, namely JSON Canonicalization Scheme [[RFC8785]] and
RDF Dataset Canonicalization [[RDF-CANON]], from a privacy perspective.
        </p>
        <p>
If an application does not require performing a selective disclosure of
information in a secured document, nor does it utilize JSON-LD, then JSON
Canonicalization Scheme [[RFC8785]] is an attractive approach.
        </p>
        <p>
If an application uses JSON-LD and might require selective disclosure
of information in a secured document, then using a cryptography suite that
uses RDF Dataset Canonicalization [[RDF-CANON]] is an attractive
approach.
        </p>
        <p>
Implementers are also advised that other selective disclosure mechanisms that
perform no transformations are available, that secure the data by wrapping it in a
cryptographic envelope instead of embedding the proof in the data, such as
SD-JWTs [[?SD-JWT]]. This approach has simplicity advantages in some use cases,
at the expense of some of the benefits provided by the approach detailed in
this specification.
        </p>
      </section>

      <section>
        <h3>Other Privacy Considerations</h3>

        <p>
Since the technology to secure documents described by this specification is
generalized in nature, the privacy implications of its use might not be
immediately apparent to readers. To understand the sort of privacy
concerns one might need to consider in a complete software system, implementers
are urged to read about how this technology is used in the
[=verifiable credentials=] ecosystem [[?VC-DATA-MODEL-2.0]]; see the section
on <a data-cite="?VC-DATA-MODEL-2.0#privacy-considerations">
Verifiable Credential Privacy Considerations</a> for more information.
        </p>
      </section>

    </section>

    <section>
      <h2>Accessibility Considerations</h2>
      <p>
The following section describes accessibility considerations that developers
implementing this specification are urged to consider in order to ensure that
their software is usable by people with different cognitive, motor, and visual
needs. As a general rule, this specification is used by system software and does
not directly expose individuals to information subject to accessibility
considerations. However, there are instances where individuals might be
indirectly exposed to information expressed by this specification and thus the
guidance below is provided for those situations.
      </p>

      <section>
        <h2>Presenting Time Values</h2>
        <p>
This specification enables the expression of dates and times related to the
validity period of cryptographic proofs. This information might be indirectly
exposed to an individual if a proof is processed and is detected to be outside
an allowable time range. When exposing these dates and times to an individual,
implementers are urged to take into account
<a data-cite="?VC-DATA-MODEL-2.0#representing-time">cultural normas and locales
when representing dates and times</a> in display software. In addition to these
considerations, presenting time values in a way that eases the cognitive burden
on the individual receiving the information is a suggested best practice.
        </p>
        <p>
For example, when conveying the expiration date for a particular set of
digitally signed information, implementers are urged to present the time of
expiration using language that is easier to understand rather than language that
optimizes for accuracy. Presenting the expiration time as "This ticket expired
three days ago." is preferred over a phrase such as "This ticket expired on July
25th 2023 at 3:43 PM." The former provides a relative time that is easier to
comprehend than the latter time, which requires the individual to do the
calculation in their head and presumes that they are capable of doing such a
calculation.
        </p>
      </section>

    </section>

    <section class="appendix informative">
      <h2>Understanding Proof Sets and Proof Chains</h2>
      <p>
Sections [[[#proof-sets]]] and [[[#proof-chains]]] describe how multiple proofs
can be expressed in a [=secured data document=]; that is, instead of a single
[=proof=] included in the [=secured data document=], one can express multiple
proofs in an [=list=] as shown in [[[#example-a-proof-set-in-a-data-document]]] and
[[[#example-a-proof-chain-in-a-data-document]]]. The elements of this [=list=] are
members of a [=proof set=] and, optionally, a [=proof chain=]. The purpose of
this section is to explain the intended use of each of these features and, in
particular, their differing security properties. These differing security
properties lead to differences in the processing in section
[[[#add-proof-set-chain]]].
      </p>
      <p>
This section represents [=secured data documents=], including their proofs, in
an abbreviated manner so that the important security properties can be
observed.
      </p>
      <p>
Consider a scenario with three signatories: a CEO, a CFO, and a VP of
Engineering. Each will need to have a public key and secret key pair for signing
a document. We denote the secret/public keys of each of these signatories by
<em>secretCEO/publicCEO</em>, <em>secretCFO/publicCFO</em>, and
<em>secretVPE/publicVPE</em>, respectively.
      </p>
      <p>
When constructing a [=proof set=] where each of the signatories signs an
|inputDocument| without concern, we construct a proof symbolically as:
      </p>
      <pre class="example nohighlight" title="Symbolic expression of how a proof is created">
{
  "type": "DataIntegrityProof",
  "cryptosuite": "eddsa-jcs-2022",
  "created": "2023-03-05T19:23:24Z",
  "proofPurpose": "assertionMethod",
  "verificationMethod": <code>publicCEO</code>,
  "proofValue": <strong>signature(<code>secretCEO</code>, <code>inputDocument</code>)</strong>
}
      </pre>
      <p>
Where <em>publicCEO</em> is used as a placeholder for a reference that resolves
to the CEO's public key and <strong>signature(`secretKey`,
`inputDocument`)</strong> denotes the computation of a digital signature
by a particular data integrity cryptosuite using a particular secret key over a
particular document. The `type`, `cryptosuite`, `created`, and `proofPurpose`
attributes do not factor into our discussion so we will omit them. In
particular, below we show all the proofs in a [=proof set=] on a document that
has been signed by the VP of Engineering, the CFO, and the CEO:
      </p>
      <pre class="example nohighlight" title="Symbolic expression of a proof set">
{
  <span class="comment">// Remainder of secured data document not shown (above)</span>
  "proof": [{
    "verificationMethod": <code>publicVPE</code>,
    "proofValue": <strong>signature(<code>secretVPE</code>, <code>inputDocument</code>)</strong>
  }, {
    "verificationMethod": <code>publicCFO</code>,
    "proofValue": <strong>signature(<code>secretCFO</code>, <code>inputDocument</code>)</strong>
  }, {
    "verificationMethod": <code>publicCEO</code>,
    "proofValue": <strong>signature(<code>secretCEO</code>, <code>inputDocument</code>)</strong>
  }]
}
      </pre>
      <p>
A [=holder=] or any other intermediary receiving a [=secured data document=]
containing a [=proof set=] is able to remove any of the `proof` values within
the set prior to passing it on to another entity and the [=secured data
document=] will still verify. This might or might not have been the intent. For
the signatories sending a birthday card to a valued employee, using a [=proof
set=] is probably fine. If we are trying to model a business process where
approvals ascend the company hierarchy, this would not be ideal, since any
intermediary could remove signatures from the [=proof set=] and still have it
verify; for instance, in the example below, it looks like the CFO and CEO
approved something without the VP of Engineering's concurrence.
      </p>
      <pre class="example nohighlight" title="Removal of a signature in a proof set">
{
  <span class="comment">// Remainder of secured data document not shown (above)</span>
  "proof": [{
    "verificationMethod": <code>publicCFO</code>,
    "proofValue": <strong>signature(<code>secretCFO</code>, <code>inputDocument</code>)</strong>
  }, {
    "verificationMethod": <code>publicCEO</code>,
    "proofValue": <strong>signature(<code>secretCEO</code>, <code>inputDocument</code>)</strong>
  }]
}
      </code></pre>
      <p>
It is possible to introduce a dependency between [=proofs=] in a [=proof set=]
by setting the `id` property of each proof such that another proof can reference
it. In other words, a <em>dependent proof</em> will be referenced by other
<em>relying proofs</em> by using the `previousProof` property. Such
<em>dependency chains</em> can have arbitrary depth. The <strong>intent</strong>
of such a [=proof chain=] is to model an approval chain in a business process or
a notary witnessing analog signatures.
      </p>
      <p>
The examples below demonstrate how a [=proof chain=] can be constructed when the
VP of Engineering signs off on the document first; based on the VP of
Engineering's signature and a review, the CFO then signs off on the document;
and finally, based on both prior signatures and a review, the CEO signs off on
the document. Since others will be referring to the VP of Engineering's
signature, we need to add an `id` to the proof. First the VP of
Engineering signs the [=input document=]:
      </p>
      <pre class="example nohighlight"
        title="Proof chain containing first proof with `id` property set">
{
  <span class="comment">// Remainder of secured data document not shown (above)</span>
  "proof": {
    <span class="highlight">"id": "urn:proof-1"</span>,
    "verificationMethod": <code>publicVPE</code>,
    "proofValue": <strong>signature(<code>secretVPE</code>, <code>inputDocument</code>)</strong>
  }
}
      </pre>
      <p>
Next, the CFO receives the document, verifies that the VP of Engineering signed
it, and signs it based on a review and on the signature of the VP of
Engineering. For this, we need to set up the [=proof chain=] by indicating a
dependency on the proof in the document just received. We do this by
setting the `previousProof` property of the second proof to the value
`urn:proof-1`, which "binds" the second proof to the first proof, which is
then signed. The following example shows how the dependency on the first proof
is created:
      </p>
      <pre class="example nohighlight" title="Proof chain containing two proofs">
{
  <span class="comment">// Remainder of secured data document not shown (above)</span>
  "proof": [{
    "id": "urn:proof-1",
    "verificationMethod": <code>publicVPE</code>,
    "proofValue": <strong>signature(<code>secretVPE</code>, <code>inputDocument</code>)</strong>
  }, {
    "id": "urn:proof-2",
    "verificationMethod": <code>publicCFO</code>,
    <span class="highlight">"previousProof": "urn:proof-1"</span>,
    "proofValue": <strong>signature(<code>secretCFO</code>, <code>inputDocumentWithProof1</code>)</strong>
  }]
}
      </pre>
      <p>
Now, when the CEO verifies the received [=secured data document=] with the
above [=proof chain=], they will check that the CFO signed based on the
signature of the VP of Engineering. First, they will check the proof with an
`id` property whose value is `urn:proof-1` against the public key of the VP of
Engineering. Note that this proof is over the original document.
      </p>
      <p>
Next, the CEO will check the proof with an `id` property whose value is
`urn:proof-2` against the public key of the CFO. However, to make sure that the
CFO signed the document with proof that the VP of Engineering had already
signed, we verify this proof over the combination of the document and
`urn:proof-1`. If verification is successful, the CEO signs, producing a proof
over the document which includes `urn:proof-1` and `urn:proof-2`. The final
[=proof chain=] looks like this:
      </p>
      <pre class="example nohighlight" title="Proof chain containing three proofs">
{
  <span class="comment">// Remainder of secured data document not shown (above)</span>
  "proof": [{
    "id": "urn:proof-1",
    "verificationMethod": <code>publicVPE</code>,
    "proofValue": <strong>signature(<code>secretVPE</code>, <code>inputDocument</code>)</strong>
  }, {
    "id": "urn:proof-2",
    "verificationMethod": <code>publicCFO</code>,
    "previousProof": "urn:proof-1",
    "proofValue": <strong>signature(<code>secretCFO</code>, <code>inputDocumentWithProof1</code>)</strong>
  }, {
    "id": "urn:proof-3",
    "verificationMethod": <code>publicCEO</code>,
    "previousProof": "urn:proof-2",
    "proofValue": <strong>signature(<code>secretCEO</code>, <code>inputDocumentWithProof2</code>)</strong>
  }]
}
      </pre>
      <p>
The recipient of this [=secured data document=] then validates it in a similar
way, checking each proof in the chain.
      </p>
    </section>

    <section class="appendix informative">
      <h2>Revision History</h2>

      <p>
This section contains the substantive changes that have been made to this
specification over time.
      </p>

      <p>
Changes since the
<a href="https://www.w3.org/TR/2024/CR-vc-data-integrity-20241219/">
Second Candidate Recommendation</a>:
      </p>

      <ul>
        <li>
Various editorial changes in algorithms and descriptions to improve readability.
        </li>
        <li>
Remove numerical error codes since implementations were not using them.
        </li>
        <li>
Update to use newly published [[[CID]]] specification references.
        </li>
      </ul>

      <p>
Changes since the
<a href="https://www.w3.org/TR/2023/CR-vc-data-integrity-20231121/">
First Candidate Recommendation</a>:
      </p>

      <ul>
        <li>
Various editorial changes in algorithms and descriptions to improve readability.
        </li>
        <li>
Moved Multikey definitions to controlled identifier document.
        </li>
        <li>
Unify error handling between all Data Integrity cryptosuites.
        </li>
        <li>
Ensure that the `created` proof option is not required and additional proof
options are included in the generated proof.
        </li>
        <li>
Add language related to context injection.
        </li>
        <li>
Update proof serialization format and algorithm arguments for
cryptosuite interfaces.
        </li>
      </ul>

      <p>
Changes since the
<a href="https://www.w3.org/TR/2022/WD-vc-data-integrity-20221110/">
First Public Working Draft</a>:
      </p>
      <ul>
        <li>
Added a section on proof purpose validation.
        </li>
        <li>
Refactored chained proof functionality.
        </li>
        <li>
Added the algorithm to retrieve a verification method.
        </li>
        <li>
Added `JsonWebKey` and `Multikey` definitions and context files.
        </li>
        <li>
Deprecated `Ed25519Signature2020` and moved into separate specification.
        </li>
        <li>
Updated Multibase and Multihash references and add text to normatively define
certain Multikey values.
        </li>
        <li>
Added Internationalization and Accessibility Considerations sections.
        </li>
        <li>
Added cryptographic hashes for context and vocabulary files and note that those
files are to be cached.
        </li>
        <li>
Added section on relationship to Linked Data and [=verifiable credentials=].
        </li>
        <li>
Added algorithms for proof sets and chains.
        </li>
        <li>
Added `nonce` and `expires` to proofs.
        </li>
        <li>
Added requirement to protect terms in JSON-LD mode.
        </li>
        <li>
Required cryptosuite specifications that do RDF canonicalization to abort when
poison graphs are detected.
        </li>
        <li>
Added section on how context injection is implemented.
        </li>
        <li>
Added error definitions with anchors to specification and vocabulary.
        </li>
        <li>
Added definitions for secret key expression.
        </li>
        <li>
Added `revoked` and `expires` to verification methods.
        </li>
        <li>
Updated proof `domain` property to allow for an array of values.
        </li>
        <li>
Added `cryptosuiteString` type to proofs to enable proof compression.
        </li>
        <li>
Added `digestMultibase` property and `multibase` data type for securing remote
content, and guidance on adding `digestMultibase` to contexts.
        </li>
        <li>
Narrowed date time values to use `dateTimeStamp`.
        </li>
        <li>
Ensure that base URL is set to null when processing as RDF.
        </li>
        <li>
Added requirement that `DataIntegrityProof` objects need to contain the `cryptosuite` property.
        </li>
      </ul>
    </section>

    <section class="informative">
      <h2>Acknowledgements</h2>

      <p>
Work on this specification has been supported by the Rebooting the Web of Trust
community facilitated by Christopher Allen, Shannon Appelcline, Kiara Robles,
Brian Weller, Betty Dhamers, Kaliya Young, Manu Sporny, Drummond Reed, Joe
Andrieu, Heather Vescent, Kim Hamilton Duffy, Samantha Chase, Andrew Hughes,
Will Abramson, Erica Connell and Eric Schuh. The participants in the
Internet Identity Workshop, facilitated by Phil Windley, Kaliya Young, Doc
Searls, and Heidi Nobantu Saul, also supported the refinement of this work
through numerous working sessions designed to educate about, debate on, and
improve this specification.
      </p>

      <p>
The Working Group also thanks our Chair, Brent Zundel, our ex-Chair, Kristina
Yasuda, as well as our W3C Staff Contact, Ivan Herman, for their expert
management and steady guidance of the group through the W3C standardization
process.
      </p>

      <p>
Portions of the work on this specification have been funded by the United States
Department of Homeland Security's Science and Technology Directorate under
contracts 70RSAT20T00000029, 70RSAT21T00000016, 70RSAT23T00000005,
70RSAT20T00000010/P00001, 70RSAT20T00000029, 70RSAT21T00000016/P00001,
70RSAT23T00000005, 70RSAT23C00000030, 70RSAT23R00000006, 70RSAT24T00000011, and
the National Science Foundation through NSF 22-572. The content of this
specification does not necessarily reflect the position or the policy of the
U.S. Government and no official endorsement should be inferred.
      </p>

      <p>
The Working Group would like to thank the following individuals for reviewing
and providing feedback on the specification (in alphabetical order by last name
or their GitHub handle if a name was not provided):
      </p>

      <p>
Will Abramson,
Mahmoud Alkhraishi,
Christopher Allen,
Joe Andrieu,
Bohdan Andriyiv,
George Aristy,
<a href="https://github.com/Anthony">Anthony</a>,
Greg Bernstein,
<a href="https://github.com/Bob420">Bob420</a>,
Sarven Capadisli,
Melvin Carvalho,
David Chadwick,
Gabe Cohen,
Matt Collier,
Sebastian Crane,
Kim Hamilton Duffy,
Snorre Lothar von Gohren Edwin,
Veikko Eeva,
Eric Elliott,
Raphael Flechtner,
Julien Fraichot,
Benjamin Goering,
Kyle Den Hartog,
Joseph Heenan,
Helge Krueger,
Ivan Herman,
Michael Herman,
Alen Horvat,
Anil John,
Andrew Jones,
Michael B. Jones,
Rieks Joosten,
Gregory K.,
Gregg Kellogg,
Filip Kolarik,
David I. Lehn,
Charles E. Lehner,
Christine Lemmer-Webber,
Eric Lim,
Dave Longley,
Tobias Looker,
Jer Miller,
<a href="https://github.com/nightpool">nightpool</a>,
Bert Van Nuffelen,
Luis Osta,
Nate Otto,
George J. Padayatti,
Addison Phillips,
Mike Prorock,
Brian Richter,
Anders Rundgren,
Eugeniu Rusu,
Markus Sabadello,
<a href="https://github.com/silverpill">silverpill</a>,
Wesley Smith,
Manu Sporny,
Orie Steele,
Patrick St-Louis,
Henry Story,
Oliver Terbu,
Ted Thibodeau Jr.,
John Toohey,
Mike Varley,
Jeffrey Yasskin,
Kristina Yasuda,
Benjamin Young,
Dmitri Zagidulin, and
Brent Zundel.
      </p>

    </section>

  </body>
</html>