Compare text

Find the difference between two text files

Real-time diff

Unified diff

Collapse lines

Highlight change

Syntax highlighting

Tools

Untitled diff

Created 6 years agoDiff never expires

<!DOCTYPE html>

<html>

<head>

<title>Linked Data Signatures 1.0</title>

<title>Linked Data Proofs 1.0</title>

<!--

=== 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,

-->

var respecConfig = {

// specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.

specStatus: "CG-DRAFT",

// the specification's short name, as in http://www.w3.org/TR/short-name/

shortName: "ld-signatures",

shortName: "ld-proofs",

// if you wish the publication date to be other than today, set this

// publishDate: "2009-08-06",

// 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/ld-signatures/",

edDraftURI: "https://w3c.github.io/ld-proofs/",

// if this is a LCWD, uncomment and set the end of its review period

// lcEnd: "2009-08-05",

// 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: "Dave Longley", url: "http://digitalbazaar.com/",

company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" },

{ name: "Manu Sporny", url: "http://digitalbazaar.com/",

company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" }

// 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: "http://digitalbazaar.com/",

company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" },

{ name: "Manu Sporny", url: "http://digitalbazaar.com/",

company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" },

company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" }

{ name: "Christopher Allen", url: "http://www.lifewithalacrity.com/",

company: "Blockstream", companyURL: "https://blockstream.com/" }

// extend the bibliography entries

//localBiblio: webpayments.localBiblio,

// name of the WG

wg: "W3C Digital Verification Community Group",

// URI of the public WG page

wgURI: "https://www.w3.org/community/digital-verification/",

// name (with the @w3c.org) of the public mailing to which comments are due

wgPublicList: "public-digital-verification",

otherLinks: [{

key: "Source control",

data: [{

value: "https://github.com/w3c/ld-signatures/",

value: "https://github.com/w3c/ld-proofs/",

href: "https://github.com/w3c/ld-signatures/"

href: "https://github.com/w3c/ld-proofs/"

}]

}, {

key: "Issue Tracker",

data: [{

value: "https://github.com/w3c/ld-signatures/issues/",

value: "https://github.com/w3c/ld-proofs/issues/",

href: "https://github.com/w3c/ld-signatures/issues/"

href: "https://github.com/w3c/ld-proofs/issues/"

}]

}],

// 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: 4,

/*preProcess: [ webpayments.preProcess ],

alternateFormats: [ {uri: "diff-20111214.html", label: "diff to previous version"} ],

localBiblio: {

"RDF-DATASET-NORMALIZATION": {

title: "RDF Dataset Normalization",

href: "https://json-ld.github.io/normalization/spec/",

authors: ["David Longley", "Manu Sporny"],

status: "CGDRAFT",

publisher: "JSON-LD Community Group"

"LD-SIGNATURES": {

title: "Linked Data Proofs",

href: "https://w3c-dvcg.github.io/ld-proofs/",

authors: ["David Longley", "Manu Sporny"],

status: "CGDRAFT",

publisher: "Digital Verification Community Group"

"SECURITY-VOCABULARY": {

title: "Security Linked Data Vocabulary",

href: "https://web-payments.org/vocabs/security",

authors: ["Manu Sporny","David Longley"],

status: "CGDRAFT",

publisher: "Web Payments Community Group"

}

};

</script>

<style>

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, ".") ") "; }

</style>

</head>

<body>

<p>

This specification describes a mechanism for ensuring the authenticity and

integrity of Linked Data documents using digital signatures.

integrity of Linked Data documents using mathematical proofs.

</p>

</section>

<p>

This is an experimental specification and is undergoing regular revisions. It

is not fit for production deployment.

</p>

</section>

<h2>Introduction</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.

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

linked data documents through the use of public/private key cryptography

linked data documents through the use of mathematical proofs

without sacrificing Linked Data features such as extensibility and

composability.

</p>

</section>

<h2>Design Goals and Rationale</h2>

<p>

The Linked Data Signature specification achieves the following design goals:

The Linked Data Proofs specification achieves the following design goals:

</p>

<dl>

<dt>Simple for Developers</dt>

<dd>

The signature format is designed to be easy to use for developers that don't

The proof format is designed to be easy to use for developers that don't

have significant cryptography training. For example, <a>signature suite</a> identifiers

have significant cryptography training. For example, <a>cryptosuite</a>

are used instead of specific cryptographic parameters to ensure that it is

identifiers are used instead of specific cryptographic parameters to ensure

difficult to accidentally produce a weak digital signature.

that it is difficult to accidentally produce a weak digital proof.

</dd>

<dt>Syntax Agnostic</dt>

<dd>

The signature mechanism can be used across a variety of RDF data syntaxes such

The proof mechanism can be used across a variety of RDF data syntaxes such

as JSON-LD, N-Quads, and TURTLE, without the need to regenerate the signature.

as JSON-LD, N-Quads, and TURTLE, without the need to regenerate the proof.

</dd>

<dt>Agile</dt>

<dd>

Since digital signature suites may be compromised without warning due to

Since digital proof suites may be compromised without warning due to

technological advancements, it is important that suites can be easily and

quickly replaced. This specification provides algorithm agility while still

keeping the digital signature format easy for developers to understand.

keeping the digital proof format easy for developers to understand.

</dd>

<dt>Extensible</dt>

<dd>

Creating and deploying new signature suites is a fairly trivial undertaking

Creating and deploying new proof suites is a fairly trivial undertaking

to ensure that the signature format increases the rate of innovation in the

to ensure that the proof format increases the rate of innovation in the

digital signature space.

digital proof space.

</dd>

</dl>

</section>

<h2>Terminology</h2>

<p>

The following terms are used to describe concepts involved in the

generation and verification of Linked Data digital signatures.

generation and verification of Linked Data digital proofs.

</p>

<dl>

<dt><dfn>linked data document</dfn></dt>

<dd>

A document comprised of Linked Data.

</dd>

<dt><dfn>signed linked data document</dfn></dt>

<dd>

A <a>linked data document</a> that has been digitally signed.

</dd>

<dt><dfn>linked data signature</dfn></dt>

<dt><dfn>linked data proof</dfn></dt>

<dd>

A set of attributes that represent a Linked Data digital signature and

A set of attributes that represent a Linked Data digital proof and

the parameters required to verify it.

</dd>

<dt><dfn>signature options</dfn></dt>

<dt><dfn>proof options</dfn></dt>

<dd>

A set of options that is included in the signature data. These options may

A set of options that is included in the proof data. These options may

be a <a>domain</a>, <a>nonce</a>, or other data that is specific to the

signature format.

proof format.

</dd>

<dt><dfn>signature suite</dfn></dt>

<dt><dfn>proof suite</dfn></dt>

<dd>

A specified set of cryptographic primitives typically consisting of

a canonicalization algorithm, a message digest algorithm, and a signature

a canonicalization algorithm, a message digest algorithm, and a proof

algorithm that are bundled together by cryptographers for developers

for the purposes of safety and convenience.

</dd>

<dt><dfn>public key</dfn></dt>

<dd>

A cryptographic key that can be used to verify digital signatures created

A cryptographic key that can be used to verify digital proofs created

with a corresponding <a>private key</a>.

</dd>

<dt><dfn>private key</dfn></dt>

<dd>

A cryptographic key that can be used to generate digital signatures.

A cryptographic key that can be used to generate digital proofs.

</dd>

<dt><dfn>domain</dfn></dt>

<dd>

A string value that specifies the operational domain of a digital signature.

A string value that specifies the operational domain of a digital proof.

This may be an Internet domain name like <code>example.com</code>, a

ad-hoc value such as <code>mycorp-level3-access</code>, or a very

specific transaction value like <code>8zF6T$mqP</code>. A signer may

include a <a>domain</a> in its digital signature to restrict its use

include a <a>domain</a> in its digital proof to restrict its use

to particular target, identified by the specified <a>domain</a>.

</dd>

<dt><dfn>canonicalization algorithm</dfn></dt>

<dd>

An algorithm that takes an input document that has more than one possible

representation and always transforms it into a deterministic representation.

For example, alphabetically sorting a list of items is a type canonicalization.

This process is sometimes also called <em>normalization</em>.

</dd>

<dt><dfn>message digest algorithm</dfn></dt>

<dd>

An algorithm that takes an input message and produces a cryptographic

output message that is often many orders of magnitude smaller than the

input message. These algorithms are often 1) very fast, 2)

non-reversible, 3) cause the output to change significantly when even one

bit of the input message changes, and 4) make it infeasible to find two

different inputs for the same output.

</dd>

<dt><dfn>signature algorithm</dfn></dt>

<dt><dfn>proof algorithm</dfn></dt>

<dd>

An algorithm that takes an input message and produces an output value where the

receiver of the message can mathematically verify that the message has not

been modified in transit and came from someone possessing a particular secret.

</dd>

</dl>

</section>

<h2>Linked Data Signature Overview</h2>

<h2>Linked Data Proof Overview</h2>

<p>

A <a>linked data signature</a> is comprised of information about the

A <a>linked data proof</a> is comprised of information about the

signature, parameters required to verify it, and the signature value itself.

proof, parameters required to verify it, and the proof value itself.

All of this information is provided using Linked Data vocabularies such as the

[[!SECURITY-VOCABULARY]].

</p>

<p>

A <a>linked data signature</a> typically includes at least the

A <a>linked data proof</a> typically includes at least the

following attributes:

</p>

<dt>type (required)<dt>

<dd>

A URI that identifies the digital <a>signature suite</a> that was used to create the

A URI that identifies the digital <a>proof suite</a> that was used to create the

signature. For example: <code>RsaSignature2018</code>.</dd>

proof. For example: <code>RsaSignature2018</code>.</dd>

<dt>creator (required)<dt>

<dd>

A URI that identifies the public/private key pair associated with the

A URI that identifies the entity that created the

signature. The URI SHOULD be a URL that can be dereferenced to obtain a

proof such as a public/private key pair. The URI SHOULD be a URL that can be

dereferenced to obtain a

<a>linked data document</a> that contains a link identifying the entity that

owns the key pair. Dereferencing the entity link SHOULD result in a Linked Data

owns the proof material. Dereferencing the entity link SHOULD result in a

Linked Data

document that contains a link back to the URL identifier for the

public/private key pair, thereby proving ownership.

proof material, thereby proving ownership.

</dd>

<dt><dfn>created</dfn> (required)<dt>

<dd>

The string value of an [[!ISO8601]] combined date and time string generated

by the <a href="#signature-algorithm">Signature Algorithm</a>.

by the <a href="#proof-algorithm">Proof Algorithm</a>.

</dd>

<dt>domain (optional)<dt>

<dd>

A string value specifying the restricted <a>domain</a> of the signature.

A string value specifying the restricted <a>domain</a> of the proof.

</dd>

<dt><dfn>nonce</dfn> (optional, but strongly recommended)<dt>

<dd>

A string value that is included in the digital signature and MUST only be

A string value that is included in the digital proof and MUST only be

used once for a particular <a>domain</a> and window of time. This

value is used to mitigate replay attacks.

</dd>

<dt><dfn>signatureValue</dfn> (required)<dt>

<dt><dfn>proofValue</dfn> (required)<dt>

<dd>

The value of the <em>signature value</em> generated by the

The value of the <em>proof value</em> generated by the

<a href="#signature-algorithm">Signature Algorithm</a>.

<a href="#proof-algorithm">Proof Algorithm</a>.

</dd>

</dl>

Since this specification is based on Linked Data, the terms <code>type</code>,

<code>creator</code>, <code>created</code>, <code>domain</code>,

<code>nonce</code>, and <code>signatureValue</code> above

<code>nonce</code>, and <code>proofValue</code> above

map to URLs. The vocabulary where these terms are defined is the

[[SECURITY-VOCABULARY]].

</p>

<p>

A signature can be added to a Linked Data document like the following:

A proof can be added to a Linked Data document like the following:

</p>

{

"@context": "https://w3id.org/identity/v1",

"title": "Hello World!"

}

</pre>

<p>

by adding the parameters outlined in this section:

</p>

{

"@context": "https://w3id.org/identity/v1",

"title": "Hello World!",

"proof": {

"type": "RsaSignature2018",

"creator": "https://example.com/i/pat/keys/5",

"created": "2017-09-23T20:21:34Z",

"domain": "example.org",

"nonce": "2bbgh3dgjg2302d-d2b3gi423d42",

"proofValue": "eyJ0eXAiOiJK...gFWFOEjXk"

}

</pre>

<p>

The signature example above uses the <code>RsaSignature2018</code>

The proof example above uses the <code>RsaSignature2018</code>

<a>signature suite</a> to produce a verifiable digital signature.

<a>proof suite</a> to produce a verifiable digital proof.

</p>

<div class="issue">Create a separate section detailing an optional mechanism

for authenticating public key ownership via bi-directional links. How

to establish trust in key owner entities is out of scope but examples can

be given.</div>

<div class="issue">Specify algorithm agility mechanisms (additional attributes

from the security vocab can be used to indicate other signing and hash

algorithms). Rewrite algorithms to be parameterized on this basis and

move `RsaSignature2018` definition to a single supported

mechanism; specify its identifier as a URL. In order to make it easy to

specify a variety of combinations of algorithms, introduce a core

type `LinkedDataSignature` that allows for easy filtering/discover of

type `LinkedDataProof` that allows for easy filtering/discover of

signature nodes, but that type on its own doesn't specify any default

proof nodes, but that type on its own doesn't specify any default

signature or hash algorithms, those must be given via other properties in the

proof or hash algorithms, those must be given via other properties in the

nodes.</div>

<div class="issue">Add a note indicating that this specification should not

be construed to indicate that public key owners should be restricted to a

single public key or that systems that use this spec and involve real people

should identify each person as only ever being a single entity rather than

perhaps N entities with M keys. There are no such restrictions and in many

cases those kinds of restrictions are ill-advised due to privacy

considerations.</div>

<div class="issue">Add an explicit check on key type to prevent an

attacker from selecting an algorithm that may abuse how the key is

used/interpreted.</div>

<div class="issue">Add a note indicating that selective disclosure signature

<div class="issue">Add a note indicating that selective disclosure proof

mechanisms can be compatible with Linked Data Signatures; for example,

mechanisms can be compatible with Linked Data Proofs; for example,

an algorithm could produce a merkle tree from a canonicalized set of

N-Quads and then sign the root hash. Disclosure would involve including

the merkle paths for each N-Quad that is to be revealed. This mechanism

would merely consume the normalized output differently (this, and the

proof mechanism would be modifications to this core spec). It may also

be necessary to generate signature parameters such as a private key/seed

be necessary to generate proof parameters such as a private key/seed

that can be used along with an algorithm to deterministically generate

nonces that are concatenated with each N-Quad to prevent rainbow

table or similar attacks.</div>

</section>

<h2>Multiple Signatures</h2>

<h2>Multiple Proofs</h2>

<p>

The Linked Data Signatures specification supports the concept of multiple

The Linked Data Proofs specification supports the concept of multiple

signatures in a single document. There are two types of multi-signature

proofs in a single document. There are two types of multi-proof

approaches that are identified: Signature Sets and Signature Chains.

approaches that are identified: Proof Sets and Proof Chains.

</p>

<h3>Signature Sets</h3>

<h3>Proof Sets</h3>

<p>

A signature set is useful when the same data needs to be signed by multiple

A proof set is useful when the same data needs to be secured by multiple

entities, but where the order of signatures does not matter,

entities, but where the order of proofs does not matter,

such as in the case of a set of signatures on a contract. A signature set,

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 signatures

which has no order, is represented by associating a set of proofs

with the <code>signature</code> key in a document.

with the <code>proof</code> key in a document.

</p>

{

"@context": "https://w3id.org/identity/v1",

"title": "Hello World!",

"proof": [{

"type": "RsaSignature2018",

"creator": "https://example.com/i/pat/keys/5",

"created": "2017-09-23T20:21:34Z",

"domain": "example.org",

"nonce": "2bbgh3dgjg2302d-d2b3gi423d42",

"proofValue": "eyJ0eXAiOiJK...gFWFOEjXk"

}, {

"type": "RsaSignature2018",

"creator": "https://example.com/i/kelly/keys/7f3j",

"created": "2017-09-23T20:24:12Z",

"domain": "example.org",

"nonce": "83jj4hd62j49gk38",

"proofValue": "eyiOiJJ0eXAK...EjXkgFWFO"

}]

}

</pre>

</section>

<h3>Signature Chains</h3>

<h3>Proof Chains</h3>

<p>

A signature chain is useful when the same data needs to be signed by

A proof chain is useful when the same data needs to be signed by

multiple entities and the order of when the signatures occurred matters,

multiple entities and the order of when the proofs occurred matters,

such as in the case of a notary counter-signing a signature that had been

such as in the case of a notary counter-signing a proof that had been

created on a document. A signature chain, where order must be preserved, is

created on a document. A proof chain, where order must be preserved, is

represented by associating an ordered list of signatures with the

represented by associating an ordered list of proofs with the

<code>signatureChain</code> key in a document.

<code>proofChain</code> key in a document.

</p>

{

"@context": "https://w3id.org/identity/v1",

"title": "Hello World!",

"proofChain": [{

"type": "RsaSignature2018",

"creator": "http://example.com/i/pat/keys/5",

"created": "2017-09-23T20:21:34Z",

"domain": "example.org",

"nonce": "2bbgh3dgjg2302d-d2b3gi423d42",

"proofValue": "eyiOiJKJ0eXA...OEjgFWFXk"

}, {

"type": "RsaSignature2018",

"creator": "http://bank.example.com/notary/keys/7f3j",

"created": "2017-09-23T20:24:12Z",

"domain": "example.org",

"nonce": "83jj4hd62j49gk38",

"proofValue": "eyiOiJJ0eXAK...EjXkgFWFO"

}]

}

</pre>

</section>

<h2>Signature Suites</h2>

<h2>Proof Suites</h2>

<p>

A Linked Data Signature is designed to be easy to use by developers and

A Linked Data 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 signature. Often, just the <a>signature suite</a> name (e.g.

to generate a proof. Often, just the <a>proof suite</a> name (e.g.

<code>RsaSignature2018</code>) is required

from developers to initiate the creation of a signature. These signature

from developers to initiate the creation of a proof. These proof

suites are often created or reviewed by people that have the requisite

cryptographic training to ensure that safe combinations of cryptographic

primitives are used.

</p>

<p>

This section details the cryptographic primitives that are available to

<a>signature suite</a> developers.

<a>proof suite</a> developers.

</p>

<p>

At a minimum, a <a>signature suite</a> must have the

At a minimum, a <a>proof suite</a> must have the

following attributes:

</p>

<dd>

A URL that identifies the <a>signature suite</a>.

A URL that identifies the <a>proof suite</a>.

For example: <code>https://w3id.org/security#RsaSignature2018</code>.

</dd>

<dd>

The value <code>SignatureSuite</code>.

The value <code>ProofSuite</code>.

</dd>

<dt>canonicalizationAlgorithm</dt>

<dd>

A URL that identifies the <a>canonicalization algorithm</a> to use on the

<var>document</var>. For example:

<code>https://w3id.org/security#GCA2015</code>.

</dd>

<dt>digestAlgorithm</dt>

<dd>

A URL that identifies the <a>message digest algorithm</a> to use on the

<var>canonicalized document</var>. For example:

<code>https://www.ietf.org/assignments/jwa-parameters#SHA256</code>

</dd>

<dt>signatureAlgorithm</dt>

<dt>proofAlgorithm</dt>

<dd>

A URL that identifies the <a>signature algorithm</a> to use on the

A URL that identifies the <a>proof algorithm</a> to use on the

<var>data to be signed</var>. For example:

<code>https://www.ietf.org/assignments/jwa-parameters#RS256</code>

</dd>

</dl>

<p>

A complete example of a <a>signature suite</a> is shown in the next example:

A complete example of a <a>proof suite</a> is shown in the next example:

</p>

{

"id": "https://w3id.org/security#RsaSignature2018",

"type": "SignatureSuite",

"type": "ProofSuite",

"canonicalizationAlgorithm": "https://w3id.org/security#GCA2015",

"digestAlgorithm": "https://www.ietf.org/assignments/jwa-parameters#SHA256",

"proofAlgorithm": "https://www.ietf.org/assignments/jws-parameters#RSASSA-PSS"

}

</pre>

</section>

<h2>Algorithms</h2>

<p>

The algorithms defined below are generalized in that they require a specific

<a>canonicalization algorithm</a>, <a>message digest algorithm</a>, and

<a>signature algorithm</a> to be used to achieve the algorithm's intended

<a>proof algorithm</a> to be used to achieve the algorithm's intended

outcome.

</p>

<h3>Signature Algorithm</h3>

<h3>Proof Algorithm</h3>

<div class="issue">The signature parameters should be included as headers

<div class="issue">The proof parameters should be included as headers

and values in the data to be signed.</div>

<p>

The following algorithm specifies how to create a digital signature that can

The following algorithm specifies how to create a digital proof that can

be later used to verify the authenticity and integrity of a

<a>linked data document</a>. A <a>linked data document</a>,

<var>document</var>, <a>signature options</a>, <var>options</var>,

<var>document</var>, <a>proof options</a>, <var>options</var>,

and a <a>private key</a>, <var>privateKey</var>, are required inputs.

The <a>signature options</a> MUST contain an identifier for the

The <a>proof options</a> MUST contain an identifier for the

public/private key pair, <var>creator</var>, and an ISO8601 combined date and

time string, <var>created</var>, containing the current date and time,

accurate to at least one second, in Universal Time Code format. A <a>nonce</a>

and a <a>domain</a> may also be specified in the <var>options</var>. A

<a>signed linked data document</a> is produced as output. Whenever this

algorithm encodes strings, it MUST use UTF-8 encoding.

</p>

<li>

Create a copy of <var>document</var>, hereafter referred to as <var>output</var>.

</li>

<li>

Generate a <var>canonicalized document</var> by canonicalizing

<var>document</var> according to a <a>canonicalization algorithm</a>

(e.g. the <em>GCA2015</em> [[!RDF-DATASET-NORMALIZATION]] algorithm).

</li>

<li>

Create a value <var>tbs</var> that represents the data to be signed, and

set it to the result of running the

<a href="#create-verify-hash-algorithm">Create Verify Hash Algorithm</a>,

passing the information in <var>options</var>.

</li>

<li>

Digitally sign <var>tbs</var> using the <var>privateKey</var> and the

the <var>digital signature algorithm</var> (e.g. JSON Web Signature using

the <var>digital proof algorithm</var> (e.g. JSON Web Proof using

<em>RSASSA-PKCS1-v1_5</em> algorithm). The resulting string is the

<a>signatureValue</a>.

<a>proofValue</a>.

</li>

<li>

Add a <code>signature</code> node to <var>output</var> containing

Add a <code>proof</code> node to <var>output</var> containing

a <a>linked data signature</a> using the appropriate

a <a>linked data proof</a> using the appropriate

<var>type</var> and <a>signatureValue</a> values as well as

<var>type</var> and <a>proofValue</a> values as well as

all of the data in the <var>signature options</var> (e.g.

all of the data in the <var>proof options</var> (e.g.

<var>creator</var>, <var>created</var>, and if given, any additional signature

<var>creator</var>, <var>created</var>, and if given, any additional proof

options such as <a>nonce</a> and <a>domain</a>).

</li>

<li>

Return <var>output</var> as the <a>signed linked data document</a>.

</li>

</ol>

</section>

<h3>Signature Verification Algorithm</h3>

<h3>Proof Verification Algorithm</h3>

This algorithm is highly specific to digital signatures and needs to be

generalized to other proof mechanisms such as Equihash.

</p>

<p>

The following algorithm specifies how to check the authenticity and

integrity of a <a>signed linked data document</a> by verifying its

digital signature. This algorithm takes a

digital proof. This algorithm takes a

<a>signed linked data document</a>, <var>signed document</var> and

outputs a <code>true</code> or <code>false</code> value based on whether or

not the digital signature on <var>signed document</var> was verified. Whenever

not the digital proof on <var>signed document</var> was verified. Whenever

this algorithm encodes strings, it MUST use UTF-8 encoding.

</p>

<div class="issue">Specify how the public key can be obtained (through

some out-of-band process and passed in or it can be retrieved by

derefencing its URL identifier, etc.</div>

<li>

Get the <a>public key</a> by dereferencing its

Get the <a>public key</a> by dereferencing its URL identifier in

the <code>proof</code> node of the default graph of

<var>signed document</var>. Confirm that the <a>li

Saved diffs

Original text

Open file


<!DOCTYPE html>
<html>
  <head>
    <title>Linked Data Signatures 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-common' class='remove'></script>
    <script type="text/javascript" class="remove">
      var respecConfig = {
          // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
          specStatus:           "CG-DRAFT",

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

          // if you wish the publication date to be other than today, set this
          // publishDate:  "2009-08-06",

          // 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/ld-signatures/",

          // if this is a LCWD, uncomment and set the end of its review period
          // lcEnd: "2009-08-05",

          // 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: "Dave Longley", url: "http://digitalbazaar.com/",
                company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" },
              { name: "Manu Sporny", url: "http://digitalbazaar.com/",
                company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" }
          ],

          // 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: "http://digitalbazaar.com/",
                company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" },
              { name: "Manu Sporny", url: "http://digitalbazaar.com/",
                company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" },
              { name: "Christopher Allen", url: "http://www.lifewithalacrity.com/",
                company: "Blockstream", companyURL: "https://blockstream.com/" }
          ],

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

          // name of the WG
          wg:           "W3C Digital Verification Community Group",

          // URI of the public WG page
          wgURI:        "https://www.w3.org/community/digital-verification/",

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

          otherLinks: [{
            key: "Source control",
            data: [{
              value: "https://github.com/w3c/ld-signatures/",
              href: "https://github.com/w3c/ld-signatures/"
            }]
          }, {
            key: "Issue Tracker",
            data: [{
              value: "https://github.com/w3c/ld-signatures/issues/",
              href: "https://github.com/w3c/ld-signatures/issues/"
            }]
          }],

          // 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: 4,
          /*preProcess: [ webpayments.preProcess ],
          alternateFormats: [ {uri: "diff-20111214.html", label: "diff to previous version"} ],
          */
          localBiblio:  {
            "RDF-DATASET-NORMALIZATION": {
              title:    "RDF Dataset Normalization",
              href:     "https://json-ld.github.io/normalization/spec/",
              authors:  ["David Longley", "Manu Sporny"],
              status:   "CGDRAFT",
              publisher:  "JSON-LD Community Group"
            },
            "SECURITY-VOCABULARY": {
              title:    "Security Linked Data Vocabulary",
              href:     "https://web-payments.org/vocabs/security",
              authors:  ["Manu Sporny","David Longley"],
              status:   "CGDRAFT",
              publisher:  "Web Payments Community Group"
          }
        }
      };
    </script>
    <style>
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, ".") ") "; }
    </style>
  </head>
  <body>
    <section id='abstract'>
      <p>
This specification describes a mechanism for ensuring the authenticity and
integrity of Linked Data documents using digital signatures.
      </p>
    </section>

    <section id='sotd'>
      <p>
This is an experimental specification and is undergoing regular revisions. It
is not fit for production deployment.
      </p>
    </section>

    <section>
      <h2>Introduction</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.

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
linked data documents through the use of public/private key cryptography
without sacrificing Linked Data features such as extensibility and
composability.
      </p>
    </section>

    <section>
      <h2>Design Goals and Rationale</h2>

      <p>
The Linked Data Signature specification achieves the following design goals:
      </p>

      <dl>
        <dt>Simple for Developers</dt>
        <dd>
The signature format is designed to be easy to use for developers that don't
have significant cryptography training. For example, <a>signature suite</a> identifiers
are used instead of specific cryptographic parameters to ensure that it is
difficult to accidentally produce a weak digital signature.
        </dd>

        <dt>Syntax Agnostic</dt>
        <dd>
The signature mechanism can be used across a variety of RDF data syntaxes such
as JSON-LD, N-Quads, and TURTLE, without the need to regenerate the signature.
        </dd>
        <dt>Agile</dt>
        <dd>
Since digital signature suites may be compromised without warning due to
technological advancements, it is important that suites can be easily and
quickly replaced. This specification provides algorithm agility while still
keeping the digital signature format easy for developers to understand.
        </dd>
        <dt>Extensible</dt>
        <dd>
Creating and deploying new signature suites is a fairly trivial undertaking
to ensure that the signature format increases the rate of innovation in the
digital signature space.
        </dd>

      </dl>

    </section>

    <section>
      <h2>Terminology</h2>
      <p>
The following terms are used to describe concepts involved in the
generation and verification of Linked Data digital signatures.
      </p>

      <dl>
        <dt><dfn>linked data document</dfn></dt>
        <dd>
A document comprised of Linked Data.
        </dd>
        <dt><dfn>signed linked data document</dfn></dt>
        <dd>
A <a>linked data document</a> that has been digitally signed.
        </dd>
        <dt><dfn>linked data signature</dfn></dt>
        <dd>
A set of attributes that represent a Linked Data digital signature and
the parameters required to verify it.
        </dd>
        <dt><dfn>signature options</dfn></dt>
        <dd>
A set of options that is included in the signature data. These options may
be a <a>domain</a>, <a>nonce</a>, or other data that is specific to the
signature format.
        </dd>
        <dt><dfn>signature suite</dfn></dt>
        <dd>
A specified set of cryptographic primitives typically consisting of
a canonicalization algorithm, a message digest algorithm, and a signature
algorithm that are bundled together by cryptographers for developers
for the purposes of safety and convenience.
        </dd>
        <dt><dfn>public key</dfn></dt>
        <dd>
A cryptographic key that can be used to verify digital signatures created
with a corresponding <a>private key</a>.
        </dd>
        <dt><dfn>private key</dfn></dt>
        <dd>
A cryptographic key that can be used to generate digital signatures.
        </dd>
        <dt><dfn>domain</dfn></dt>
        <dd>
A string value that specifies the operational domain of a digital signature.
This may be an Internet domain name like <code>example.com</code>, a
ad-hoc value such as <code>mycorp-level3-access</code>, or a very
specific transaction value like <code>8zF6T$mqP</code>. A signer may
include a <a>domain</a> in its digital signature to restrict its use
to particular target, identified by the specified <a>domain</a>.
        </dd>
        <dt><dfn>canonicalization algorithm</dfn></dt>
        <dd>
An algorithm that takes an input document that has more than one possible
representation and always transforms it into a deterministic representation.
For example, alphabetically sorting a list of items is a type canonicalization.
This process is sometimes also called <em>normalization</em>.
        </dd>
        <dt><dfn>message digest algorithm</dfn></dt>
        <dd>
An algorithm that takes an input message and produces a cryptographic
output message that is often many orders of magnitude smaller than the
input message. These algorithms are often 1) very fast, 2)
non-reversible, 3) cause the output to change significantly when even one
bit of the input message changes, and 4) make it infeasible to find two
different inputs for the same output.
        </dd>
        <dt><dfn>signature algorithm</dfn></dt>
        <dd>
An algorithm that takes an input message and produces an output value where the
receiver of the message can mathematically verify that the message has not
been modified in transit and came from someone possessing a particular secret.
        </dd>
      </dl>

    </section>

    <section>
      <h2>Linked Data Signature Overview</h2>

      <p>
A <a>linked data signature</a> is comprised of information about the
signature, parameters required to verify it, and the signature value itself.
All of this information is provided using Linked Data vocabularies such as the
[[!SECURITY-VOCABULARY]].
      </p>

      <p>
        A <a>linked data signature</a> typically includes at least the
        following attributes:
      </p>

      <dl style="margin-left: 1em;">
        <dt>type (required)<dt>
        <dd>
A URI that identifies the digital <a>signature suite</a> that was used to create the
signature. For example: <code>RsaSignature2018</code>.</dd>
        <dt>creator (required)<dt>
        <dd>
A URI that identifies the public/private key pair associated with the
signature. The URI SHOULD be a URL that can be dereferenced to obtain a
<a>linked data document</a> that contains a link identifying the entity that
owns the key pair. Dereferencing the entity link SHOULD result in a Linked Data
document that contains a link back to the URL identifier for the
public/private key pair, thereby proving ownership.
        </dd>
        <dt><dfn>created</dfn> (required)<dt>
        <dd>
The string value of an [[!ISO8601]] combined date and time string generated
by the <a href="#signature-algorithm">Signature Algorithm</a>.
        </dd>
        <dt>domain (optional)<dt>
        <dd>
A string value specifying the restricted <a>domain</a> of the signature.
        </dd>
        <dt><dfn>nonce</dfn> (optional, but strongly recommended)<dt>
        <dd>
A string value that is included in the digital signature and MUST only be
used once for a particular <a>domain</a> and window of time. This
value is used to mitigate replay attacks.
        </dd>
        <dt><dfn>signatureValue</dfn> (required)<dt>
        <dd>
The value of the <em>signature value</em> generated by the
<a href="#signature-algorithm">Signature Algorithm</a>.
        </dd>
      </dl>

      <p class="note">
Since this specification is based on Linked Data, the terms <code>type</code>,
<code>creator</code>, <code>created</code>, <code>domain</code>,
<code>nonce</code>, and <code>signatureValue</code> above
map to URLs. The vocabulary where these terms are defined is the
[[SECURITY-VOCABULARY]].
      </p>


      <p>
A signature can be added to a Linked Data document like the following:
      </p>

      <pre class="example highlight" title="A simple Linked Data document">
{
  "@context": "https://w3id.org/identity/v1",
  "title": "Hello World!"
}
      </pre>

      <p>
by adding the parameters outlined in this section:
      </p>

      <pre class="example highlight" title="A simple signed Linked Data document">
{
  "@context": "https://w3id.org/identity/v1",
  "title": "Hello World!",
  "proof": {
    "type": "RsaSignature2018",
    "creator": "https://example.com/i/pat/keys/5",
    "created": "2017-09-23T20:21:34Z",
    "domain": "example.org",
    "nonce": "2bbgh3dgjg2302d-d2b3gi423d42",
    "proofValue": "eyJ0eXAiOiJK...gFWFOEjXk"
  }
}
      </pre>

      <p>
The signature example above uses the <code>RsaSignature2018</code>
<a>signature suite</a> to produce a verifiable digital signature.
      </p>

<div class="issue">Create a separate section detailing an optional mechanism
for authenticating public key ownership via bi-directional links. How
to establish trust in key owner entities is out of scope but examples can
be given.</div>

<div class="issue">Specify algorithm agility mechanisms (additional attributes
from the security vocab can be used to indicate other signing and hash
algorithms). Rewrite algorithms to be parameterized on this basis and
move `RsaSignature2018` definition to a single supported
mechanism; specify its identifier as a URL. In order to make it easy to
specify a variety of combinations of algorithms, introduce a core
type `LinkedDataSignature` that allows for easy filtering/discover of
signature nodes, but that type on its own doesn't specify any default
signature or hash algorithms, those must be given via other properties in the
nodes.</div>

<div class="issue">Add a note indicating that this specification should not
be construed to indicate that public key owners should be restricted to a
single public key or that systems that use this spec and involve real people
should identify each person as only ever being a single entity rather than
perhaps N entities with M keys. There are no such restrictions and in many
cases those kinds of restrictions are ill-advised due to privacy
considerations.</div>

<div class="issue">Add an explicit check on key type to prevent an
attacker from selecting an algorithm that may abuse how the key is
used/interpreted.</div>

<div class="issue">Add a note indicating that selective disclosure signature
mechanisms can be compatible with Linked Data Signatures; for example,
an algorithm could produce a merkle tree from a canonicalized set of
N-Quads and then sign the root hash. Disclosure would involve including
the merkle paths for each N-Quad that is to be revealed. This mechanism
would merely consume the normalized output differently (this, and the
proof mechanism would be modifications to this core spec). It may also
be necessary to generate signature parameters such as a private key/seed
that can be used along with an algorithm to deterministically generate
nonces that are concatenated with each N-Quad to prevent rainbow
table or similar attacks.</div>

    </section>

    <section>
      <h2>Multiple Signatures</h2>
      <p>
The Linked Data Signatures specification supports the concept of multiple
signatures in a single document. There are two types of multi-signature
approaches that are identified: Signature Sets and Signature Chains.
      </p>

      <section>
        <h3>Signature Sets</h3>
        <p>
A signature set is useful when the same data needs to be signed by multiple
entities, but where the order of signatures does not matter,
such as in the case of a set of signatures on a contract. A signature set,
which has no order, is represented by associating a set of signatures
with the <code>signature</code> key in a document.
        </p>
        <pre class="example highlight" title="A signature set in a Linked Data document">
{
  "@context": "https://w3id.org/identity/v1",
  "title": "Hello World!",
  "proof": [{
    "type": "RsaSignature2018",
    "creator": "https://example.com/i/pat/keys/5",
    "created": "2017-09-23T20:21:34Z",
    "domain": "example.org",
    "nonce": "2bbgh3dgjg2302d-d2b3gi423d42",
    "proofValue": "eyJ0eXAiOiJK...gFWFOEjXk"
  }, {
    "type": "RsaSignature2018",
    "creator": "https://example.com/i/kelly/keys/7f3j",
    "created": "2017-09-23T20:24:12Z",
    "domain": "example.org",
    "nonce": "83jj4hd62j49gk38",
    "proofValue": "eyiOiJJ0eXAK...EjXkgFWFO"
  }]
}
        </pre>

      </section>

      <section>
        <h3>Signature Chains</h3>
        <p>
A signature chain is useful when the same data needs to be signed by
multiple entities and the order of when the signatures occurred matters,
such as in the case of a notary counter-signing a signature that had been
created on a document. A signature chain, where order must be preserved, is
represented by associating an ordered list of signatures with the
<code>signatureChain</code> key in a document.
        </p>
        <pre class="example highlight" title="A signature chain in a Linked Data document">
{
  "@context": "https://w3id.org/identity/v1",
  "title": "Hello World!",
  "proofChain": [{
    "type": "RsaSignature2018",
    "creator": "http://example.com/i/pat/keys/5",
    "created": "2017-09-23T20:21:34Z",
    "domain": "example.org",
    "nonce": "2bbgh3dgjg2302d-d2b3gi423d42",
    "proofValue": "eyiOiJKJ0eXA...OEjgFWFXk"
  }, {
    "type": "RsaSignature2018",
    "creator": "http://bank.example.com/notary/keys/7f3j",
    "created": "2017-09-23T20:24:12Z",
    "domain": "example.org",
    "nonce": "83jj4hd62j49gk38",
    "proofValue": "eyiOiJJ0eXAK...EjXkgFWFO"
  }]
}
        </pre>

      </section>

    </section>

    <section>
      <h2>Signature Suites</h2>

      <p>
A Linked Data Signature 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 signature. Often, just the <a>signature suite</a> name (e.g.
<code>RsaSignature2018</code>) is required
from developers to initiate the creation of a signature. These signature
suites are often created or reviewed by people that have the requisite
cryptographic training to ensure that safe combinations of cryptographic
primitives are used.
      </p>
      <p>
This section details the cryptographic primitives that are available to
<a>signature suite</a> developers.
      </p>

      <p>
        At a minimum, a <a>signature suite</a> must have the
        following attributes:
      </p>

      <dl style="margin-left: 1em;">
        <dt>id</dt>
        <dd>
A URL that identifies the <a>signature suite</a>.
For example: <code>https://w3id.org/security#RsaSignature2018</code>.
        </dd>
        <dt>type</dt>
        <dd>
The value <code>SignatureSuite</code>.
        </dd>
        <dt>canonicalizationAlgorithm</dt>
        <dd>
A URL that identifies the <a>canonicalization algorithm</a> to use on the
<var>document</var>. For example:
<code>https://w3id.org/security#GCA2015</code>.
        </dd>
        <dt>digestAlgorithm</dt>
        <dd>
A URL that identifies the <a>message digest algorithm</a> to use on the
<var>canonicalized document</var>. For example:
<code>https://www.ietf.org/assignments/jwa-parameters#SHA256</code>
        </dd>
        <dt>signatureAlgorithm</dt>
        <dd>
A URL that identifies the <a>signature algorithm</a> to use on the
<var>data to be signed</var>. For example:
<code>https://www.ietf.org/assignments/jwa-parameters#RS256</code>
        </dd>
      </dl>

      <p>
A complete example of a <a>signature suite</a> is shown in the next example:
      </p>

      <pre class="example highlight">
{
  "id": "https://w3id.org/security#RsaSignature2018",
  "type": "SignatureSuite",
  "canonicalizationAlgorithm": "https://w3id.org/security#GCA2015",
  "digestAlgorithm": "https://www.ietf.org/assignments/jwa-parameters#SHA256",
  "proofAlgorithm": "https://www.ietf.org/assignments/jws-parameters#RSASSA-PSS"
}
      </pre>
    </section>

    <section>
      <h2>Algorithms</h2>

      <p>
The algorithms defined below are generalized in that they require a specific
<a>canonicalization algorithm</a>, <a>message digest algorithm</a>, and
<a>signature algorithm</a> to be used to achieve the algorithm's intended
outcome.
      </p>

      <section>
        <h3>Signature Algorithm</h3>

<div class="issue">The signature parameters should be included as headers
and values in the data to be signed.</div>

        <p>
The following algorithm specifies how to create a digital signature that can
be later used to verify the authenticity and integrity of a
<a>linked data document</a>. A <a>linked data document</a>,
<var>document</var>, <a>signature options</a>, <var>options</var>,
and a <a>private key</a>, <var>privateKey</var>, are required inputs.
The <a>signature options</a> MUST contain an identifier for the
public/private key pair, <var>creator</var>, and an ISO8601 combined date and
time string, <var>created</var>, containing the current date and time,
accurate to at least one second, in Universal Time Code format. A <a>nonce</a>
and a <a>domain</a> may also be specified in the <var>options</var>. A
<a>signed linked data document</a> is produced as output. Whenever this
algorithm encodes strings, it MUST use UTF-8 encoding.
        </p>

        <ol class="algorithm">
          <li>
Create a copy of <var>document</var>, hereafter referred to as <var>output</var>.
          </li>
          <li>
Generate a <var>canonicalized document</var> by canonicalizing
<var>document</var> according to a <a>canonicalization algorithm</a>
(e.g. the <em>GCA2015</em> [[!RDF-DATASET-NORMALIZATION]] algorithm).
        </li>
          <li>
Create a value <var>tbs</var> that represents the data to be signed, and
set it to the result of running the
<a href="#create-verify-hash-algorithm">Create Verify Hash Algorithm</a>,
passing the information in <var>options</var>.
          </li>
          <li>
Digitally sign <var>tbs</var> using the <var>privateKey</var> and the
the <var>digital signature algorithm</var> (e.g. JSON Web Signature using
<em>RSASSA-PKCS1-v1_5</em> algorithm). The resulting string is the
<a>signatureValue</a>.
          </li>
          <li>
Add a <code>signature</code> node to <var>output</var> containing
a <a>linked data signature</a> using the appropriate
<var>type</var> and <a>signatureValue</a> values as well as
all of the data in the <var>signature options</var> (e.g.
<var>creator</var>, <var>created</var>, and if given, any additional signature
options such as <a>nonce</a> and <a>domain</a>).
          </li>
          <li>
Return <var>output</var> as the <a>signed linked data document</a>.
          </li>
        </ol>

      </section>

      <section>
        <h3>Signature Verification Algorithm</h3>
        <p>
The following algorithm specifies how to check the authenticity and
integrity of a <a>signed linked data document</a> by verifying its
digital signature. This algorithm takes a
<a>signed linked data document</a>, <var>signed document</var> and
outputs a <code>true</code> or <code>false</code> value based on whether or
not the digital signature on <var>signed document</var> was verified. Whenever
this algorithm encodes strings, it MUST use UTF-8 encoding.
        </p>

<div class="issue">Specify how the public key can be obtained (through
some out-of-band process and passed in or it can be retrieved by
derefencing its URL identifier, etc.</div>

        <ol class="algorithm">
          <li>
Get the <a>public key</a> by dereferencing its URL identifier in
the <code>signature</code> node of the default graph of
<var>signed document</var>. Confirm that the <a>linked data document</a>
that describes the <a>public key</a> specifies its owner and that its
owner's URL identifier can be dereferenced to reveal a bi-directional link back
to the key. Ensure that the key's owner is a trusted entity before proceeding
to the next step.
          </li>
          <li>
Let <var>document</var> be a copy of <var>signed document</var>.
          </li>
          <li>
Remove any <code>signature</code> nodes from the default graph in
<var>document</var> and save it as <var>signature</var>.
          </li>
          <li>
Generate a <var>canonicalized document</var> by canonicalizing
<var>document</var> according to the <a>canonicalization algorithm</a>
(e.g. the </var><em>GCA2015</em> [[!RDF-DATASET-NORMALIZATION]] algorithm).
          </li>
          <li>
Create a value <var>tbv</var> that represents the data to be verified, and
set it to the result of running the
<a href="#create-verify-hash-algorithm">Create Verify Hash Algorithm</a>,
passing the information in <var>signature</var>.
          </li>
          <li>
Pass the <a>signatureValue</a>, <var>tbv</var>,
and the <a>public key</a> to the <a>signature algorithm</a>
(e.g. JSON Web Signature using <em>RSASSA-PKCS1-v1_5</em> algorithm).
Return the resulting boolean value.
          </li>
        </ol>
      </section>

      <section>
        <h3>Create Verify Hash Algorithm</h3>
        <p>
The following algorithm specifies how to create the data that is used
to generate or verify a digital signature. It takes a canonicalized
<a>linked data document</a>, <var>canonicalized document</var>,
<a>canonicalization algorithm</a>, a <a>message digest algorithm</a>, and
<a>signature options</a>, <var>input options</var> (by reference).
The <a>signature options</a> MUST contain an identifier for the
public/private key pair, <var>creator</var>, and an ISO8601 combined date and
time string, <var>created</var>, containing the current date and time,
accurate to at least one second, in Universal Time Code format. A <a>nonce</a>
and a <a>domain</a> may also be specified in the <var>options</var>.
Its output is a data that can be used to generate or verify a
digital signature (it is usually further hashed as part of the
verification or signing process).
        </p>

        <ol class="algorithm">
          <li>
Let <var>options</var> be a copy of <var>input options</var>.
          </li>
          <li>
If <code>type</code>, <code>id</code>, or <code>signatureValue</code>
exists in <var>options</var>, remove the entry.
          </li>
          <li>
If <var>created</var> does not exist in <var>options</var>, add an
entry with a value that is an ISO8601 combined date and
time string containing the current date and time accurate to at least one
second, in Universal Time Code format. For example:
<code>2017-11-13T20:21:34Z</code>.
          </li>
          <li>
Generate <var>output</var> by:
            <ol class="algorithm">
              <li>
Creating a <var>canonicalized options document</var> by canonicalizing
<var>options</var> according to the <a>canonicalization algorithm</a>
(e.g. the <em>GCA2015</em> [[!RDF-DATASET-NORMALIZATION]] algorithm).
              </li>
              <li>
Hash <var>canonicalized options document</var> using the
<a>message digest algorithm</a> (e.g. SHA-256) and set <var>output</var>
to the result.
              </li>
              <li>
Hash <var>canonicalized document</var> using the <a>message digest algorithm</a>
(e.g. SHA-256) and append it to <var>output</var>.
              </li>
            </ol>
          </li>
          <li>
<div class="issue">This last step needs further clarification. Signing
implementations usually automatically perform their own integrated
hashing of an input message, i.e. signing algorithms are a combination
of a raw signing mechanism and a hashing mechanism such as
RS256 (RSA + SHA-256). Current implementations of RSA-based
Linked Data Signature suites therefore do not perform this last step
before passing the data to a signing algorithm as it will be performed
internally. The Ed25519Signature2018 algorithm also does not perform
this last step -- and, in fact, uses SHA-512 internally. In short,
this last step should better communicate that the 64 bytes produced
from concatenating the SHA-256 of the canonicalized options with the
SHA-256 of the canonicalized document are passed into the signing
algorithm with a presumption that the signing algorithm will include
hashing of its own.</div>
Note: It is presumed that the 64-byte <var>output</var> will be used
in a signing algorithm that includes its own hashing algorithm, such
as RS256 (RSA + SHA-256) or EdDsa (Ed25519 which uses SHA-512).
          </li>
          <li>
Return <var>output</var>.
          </li>
        </ol>
      </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>

<div class="issue">TODO: We need to add a complete list of security
considerations.</div>
    </section>

    <section class="appendix">
      <h2>GraphSignature2012</h2>
      <p>A previous version of this specification has light deployment. For
        purposes of identification, the algorithm is identified as
        <a href="">GraphSignature2012</a> and its algorithms differ from the
        stated algorithm in the following ways:</p>

<div class="issue">Specify GraphSignature2012 differences.</div>

      <!--
      <ul>
        <li>
        </li>
      </ul> -->

    </section>

  </body>
</html>

Changed text

Open file


<!DOCTYPE html>
<html>
  <head>
    <title>Linked Data Proofs 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-common' class='remove'></script>
    <script type="text/javascript" class="remove">
      var respecConfig = {
          // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
          specStatus:           "CG-DRAFT",

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

          // if you wish the publication date to be other than today, set this
          // publishDate:  "2009-08-06",

          // 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/ld-proofs/",

          // if this is a LCWD, uncomment and set the end of its review period
          // lcEnd: "2009-08-05",

          // 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: "Dave Longley", url: "http://digitalbazaar.com/",
                company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" },
              { name: "Manu Sporny", url: "http://digitalbazaar.com/",
                company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" }
          ],

          // 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: "http://digitalbazaar.com/",
                company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" },
              { name: "Manu Sporny", url: "http://digitalbazaar.com/",
                company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" }
          ],

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

          // name of the WG
          wg:           "W3C Digital Verification Community Group",

          // URI of the public WG page
          wgURI:        "https://www.w3.org/community/digital-verification/",

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

          otherLinks: [{
            key: "Source control",
            data: [{
              value: "https://github.com/w3c/ld-proofs/",
              href: "https://github.com/w3c/ld-proofs/"
            }]
          }, {
            key: "Issue Tracker",
            data: [{
              value: "https://github.com/w3c/ld-proofs/issues/",
              href: "https://github.com/w3c/ld-proofs/issues/"
            }]
          }],

          // 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: 4,
          /*preProcess: [ webpayments.preProcess ],
          alternateFormats: [ {uri: "diff-20111214.html", label: "diff to previous version"} ],
          */
          localBiblio:  {
            "RDF-DATASET-NORMALIZATION": {
              title:    "RDF Dataset Normalization",
              href:     "https://json-ld.github.io/normalization/spec/",
              authors:  ["David Longley", "Manu Sporny"],
              status:   "CGDRAFT",
              publisher:  "JSON-LD Community Group"
            },
            "LD-SIGNATURES": {
              title:    "Linked Data Proofs",
              href:     "https://w3c-dvcg.github.io/ld-proofs/",
              authors:  ["David Longley", "Manu Sporny"],
              status:   "CGDRAFT",
              publisher:  "Digital Verification Community Group"
            },
            "SECURITY-VOCABULARY": {
              title:    "Security Linked Data Vocabulary",
              href:     "https://web-payments.org/vocabs/security",
              authors:  ["Manu Sporny","David Longley"],
              status:   "CGDRAFT",
              publisher:  "Web Payments Community Group"
          }
        }
      };
    </script>
    <style>
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, ".") ") "; }
    </style>
  </head>
  <body>
    <section id='abstract'>
      <p>
This specification describes a mechanism for ensuring the authenticity and
integrity of Linked Data documents using mathematical proofs.
      </p>
    </section>

    <section id='sotd'>
      <p>
This is an experimental specification and is undergoing regular revisions. It
is not fit for production deployment.
      </p>
    </section>

    <section>
      <h2>Introduction</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.

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
linked data documents through the use of mathematical proofs
without sacrificing Linked Data features such as extensibility and
composability.
      </p>
    </section>

    <section>
      <h2>Design Goals and Rationale</h2>

      <p>
The Linked Data Proofs specification achieves the following design goals:
      </p>

      <dl>
        <dt>Simple for Developers</dt>
        <dd>
The proof format is designed to be easy to use for developers that don't
have significant cryptography training. For example, <a>cryptosuite</a>
identifiers are used instead of specific cryptographic parameters to ensure
that it is difficult to accidentally produce a weak digital proof.
        </dd>

        <dt>Syntax Agnostic</dt>
        <dd>
The proof mechanism can be used across a variety of RDF data syntaxes such
as JSON-LD, N-Quads, and TURTLE, without the need to regenerate the proof.
        </dd>
        <dt>Agile</dt>
        <dd>
Since digital proof suites may be compromised without warning due to
technological advancements, it is important that suites can be easily and
quickly replaced. This specification provides algorithm agility while still
keeping the digital proof format easy for developers to understand.
        </dd>
        <dt>Extensible</dt>
        <dd>
Creating and deploying new proof suites is a fairly trivial undertaking
to ensure that the proof format increases the rate of innovation in the
digital proof space.
        </dd>

      </dl>

    </section>

    <section>
      <h2>Terminology</h2>
      <p>
The following terms are used to describe concepts involved in the
generation and verification of Linked Data digital proofs.
      </p>

      <dl>
        <dt><dfn>linked data document</dfn></dt>
        <dd>
A document comprised of Linked Data.
        </dd>
        <dt><dfn>signed linked data document</dfn></dt>
        <dd>
A <a>linked data document</a> that has been digitally signed.
        </dd>
        <dt><dfn>linked data proof</dfn></dt>
        <dd>
A set of attributes that represent a Linked Data digital proof and
the parameters required to verify it.
        </dd>
        <dt><dfn>proof options</dfn></dt>
        <dd>
A set of options that is included in the proof data. These options may
be a <a>domain</a>, <a>nonce</a>, or other data that is specific to the
proof format.
        </dd>
        <dt><dfn>proof suite</dfn></dt>
        <dd>
A specified set of cryptographic primitives typically consisting of
a canonicalization algorithm, a message digest algorithm, and a proof
algorithm that are bundled together by cryptographers for developers
for the purposes of safety and convenience.
        </dd>
        <dt><dfn>public key</dfn></dt>
        <dd>
A cryptographic key that can be used to verify digital proofs created
with a corresponding <a>private key</a>.
        </dd>
        <dt><dfn>private key</dfn></dt>
        <dd>
A cryptographic key that can be used to generate digital proofs.
        </dd>
        <dt><dfn>domain</dfn></dt>
        <dd>
A string value that specifies the operational domain of a digital proof.
This may be an Internet domain name like <code>example.com</code>, a
ad-hoc value such as <code>mycorp-level3-access</code>, or a very
specific transaction value like <code>8zF6T$mqP</code>. A signer may
include a <a>domain</a> in its digital proof to restrict its use
to particular target, identified by the specified <a>domain</a>.
        </dd>
        <dt><dfn>canonicalization algorithm</dfn></dt>
        <dd>
An algorithm that takes an input document that has more than one possible
representation and always transforms it into a deterministic representation.
For example, alphabetically sorting a list of items is a type canonicalization.
This process is sometimes also called <em>normalization</em>.
        </dd>
        <dt><dfn>message digest algorithm</dfn></dt>
        <dd>
An algorithm that takes an input message and produces a cryptographic
output message that is often many orders of magnitude smaller than the
input message. These algorithms are often 1) very fast, 2)
non-reversible, 3) cause the output to change significantly when even one
bit of the input message changes, and 4) make it infeasible to find two
different inputs for the same output.
        </dd>
        <dt><dfn>proof algorithm</dfn></dt>
        <dd>
An algorithm that takes an input message and produces an output value where the
receiver of the message can mathematically verify that the message has not
been modified in transit and came from someone possessing a particular secret.
        </dd>
      </dl>

    </section>

    <section>
      <h2>Linked Data Proof Overview</h2>

      <p>
A <a>linked data proof</a> is comprised of information about the
proof, parameters required to verify it, and the proof value itself.
All of this information is provided using Linked Data vocabularies such as the
[[!SECURITY-VOCABULARY]].
      </p>

      <p>
        A <a>linked data proof</a> typically includes at least the
        following attributes:
      </p>

      <dl style="margin-left: 1em;">
        <dt>type (required)<dt>
        <dd>
A URI that identifies the digital <a>proof suite</a> that was used to create the
proof. For example: <code>RsaSignature2018</code>.</dd>
        <dt>creator (required)<dt>
        <dd>
A URI that identifies the entity that created the
proof such as a public/private key pair. The URI SHOULD be a URL that can be
dereferenced to obtain a
<a>linked data document</a> that contains a link identifying the entity that
owns the proof material. Dereferencing the entity link SHOULD result in a
Linked Data
document that contains a link back to the URL identifier for the
proof material, thereby proving ownership.
        </dd>
        <dt><dfn>created</dfn> (required)<dt>
        <dd>
The string value of an [[!ISO8601]] combined date and time string generated
by the <a href="#proof-algorithm">Proof Algorithm</a>.
        </dd>
        <dt>domain (optional)<dt>
        <dd>
A string value specifying the restricted <a>domain</a> of the proof.
        </dd>
        <dt><dfn>nonce</dfn> (optional, but strongly recommended)<dt>
        <dd>
A string value that is included in the digital proof and MUST only be
used once for a particular <a>domain</a> and window of time. This
value is used to mitigate replay attacks.
        </dd>
        <dt><dfn>proofValue</dfn> (required)<dt>
        <dd>
The value of the <em>proof value</em> generated by the
<a href="#proof-algorithm">Proof Algorithm</a>.
        </dd>
      </dl>

      <p class="note">
Since this specification is based on Linked Data, the terms <code>type</code>,
<code>creator</code>, <code>created</code>, <code>domain</code>,
<code>nonce</code>, and <code>proofValue</code> above
map to URLs. The vocabulary where these terms are defined is the
[[SECURITY-VOCABULARY]].
      </p>


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

      <pre class="example highlight" title="A simple Linked Data document">
{
  "@context": "https://w3id.org/identity/v1",
  "title": "Hello World!"
}
      </pre>

      <p>
by adding the parameters outlined in this section:
      </p>

      <pre class="example highlight" title="A simple signed Linked Data document">
{
  "@context": "https://w3id.org/identity/v1",
  "title": "Hello World!",
  "proof": {
    "type": "RsaSignature2018",
    "creator": "https://example.com/i/pat/keys/5",
    "created": "2017-09-23T20:21:34Z",
    "domain": "example.org",
    "nonce": "2bbgh3dgjg2302d-d2b3gi423d42",
    "proofValue": "eyJ0eXAiOiJK...gFWFOEjXk"
  }
}
      </pre>

      <p>
The proof example above uses the <code>RsaSignature2018</code>
<a>proof suite</a> to produce a verifiable digital proof.
      </p>

<div class="issue">Create a separate section detailing an optional mechanism
for authenticating public key ownership via bi-directional links. How
to establish trust in key owner entities is out of scope but examples can
be given.</div>

<div class="issue">Specify algorithm agility mechanisms (additional attributes
from the security vocab can be used to indicate other signing and hash
algorithms). Rewrite algorithms to be parameterized on this basis and
move `RsaSignature2018` definition to a single supported
mechanism; specify its identifier as a URL. In order to make it easy to
specify a variety of combinations of algorithms, introduce a core
type `LinkedDataProof` that allows for easy filtering/discover of
proof nodes, but that type on its own doesn't specify any default
proof or hash algorithms, those must be given via other properties in the
nodes.</div>

<div class="issue">Add a note indicating that this specification should not
be construed to indicate that public key owners should be restricted to a
single public key or that systems that use this spec and involve real people
should identify each person as only ever being a single entity rather than
perhaps N entities with M keys. There are no such restrictions and in many
cases those kinds of restrictions are ill-advised due to privacy
considerations.</div>

<div class="issue">Add an explicit check on key type to prevent an
attacker from selecting an algorithm that may abuse how the key is
used/interpreted.</div>

<div class="issue">Add a note indicating that selective disclosure proof
mechanisms can be compatible with Linked Data Proofs; for example,
an algorithm could produce a merkle tree from a canonicalized set of
N-Quads and then sign the root hash. Disclosure would involve including
the merkle paths for each N-Quad that is to be revealed. This mechanism
would merely consume the normalized output differently (this, and the
proof mechanism would be modifications to this core spec). It may also
be necessary to generate proof parameters such as a private key/seed
that can be used along with an algorithm to deterministically generate
nonces that are concatenated with each N-Quad to prevent rainbow
table or similar attacks.</div>

    </section>

    <section>
      <h2>Multiple Proofs</h2>
      <p>
The Linked Data Proofs specification supports the concept of multiple
proofs in a single document. There are two types of multi-proof
approaches that are identified: Proof Sets and Proof Chains.
      </p>

      <section>
        <h3>Proof Sets</h3>
        <p>
A proof set 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 <code>proof</code> key in a document.
        </p>
        <pre class="example highlight" title="A proof set in a Linked Data document">
{
  "@context": "https://w3id.org/identity/v1",
  "title": "Hello World!",
  "proof": [{
    "type": "RsaSignature2018",
    "creator": "https://example.com/i/pat/keys/5",
    "created": "2017-09-23T20:21:34Z",
    "domain": "example.org",
    "nonce": "2bbgh3dgjg2302d-d2b3gi423d42",
    "proofValue": "eyJ0eXAiOiJK...gFWFOEjXk"
  }, {
    "type": "RsaSignature2018",
    "creator": "https://example.com/i/kelly/keys/7f3j",
    "created": "2017-09-23T20:24:12Z",
    "domain": "example.org",
    "nonce": "83jj4hd62j49gk38",
    "proofValue": "eyiOiJJ0eXAK...EjXkgFWFO"
  }]
}
        </pre>

      </section>

      <section>
        <h3>Proof Chains</h3>
        <p>
A proof chain 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 order must be preserved, is
represented by associating an ordered list of proofs with the
<code>proofChain</code> key in a document.
        </p>
        <pre class="example highlight" title="A proof chain in a Linked Data document">
{
  "@context": "https://w3id.org/identity/v1",
  "title": "Hello World!",
  "proofChain": [{
    "type": "RsaSignature2018",
    "creator": "http://example.com/i/pat/keys/5",
    "created": "2017-09-23T20:21:34Z",
    "domain": "example.org",
    "nonce": "2bbgh3dgjg2302d-d2b3gi423d42",
    "proofValue": "eyiOiJKJ0eXA...OEjgFWFXk"
  }, {
    "type": "RsaSignature2018",
    "creator": "http://bank.example.com/notary/keys/7f3j",
    "created": "2017-09-23T20:24:12Z",
    "domain": "example.org",
    "nonce": "83jj4hd62j49gk38",
    "proofValue": "eyiOiJJ0eXAK...EjXkgFWFO"
  }]
}
        </pre>

      </section>

    </section>

    <section>
      <h2>Proof Suites</h2>

      <p>
A Linked Data 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 <a>proof suite</a> name (e.g.
<code>RsaSignature2018</code>) is required
from developers to initiate the creation of a proof. These proof
suites are often created or reviewed by people that have the requisite
cryptographic training to ensure that safe combinations of cryptographic
primitives are used.
      </p>
      <p>
This section details the cryptographic primitives that are available to
<a>proof suite</a> developers.
      </p>

      <p>
        At a minimum, a <a>proof suite</a> must have the
        following attributes:
      </p>

      <dl style="margin-left: 1em;">
        <dt>id</dt>
        <dd>
A URL that identifies the <a>proof suite</a>.
For example: <code>https://w3id.org/security#RsaSignature2018</code>.
        </dd>
        <dt>type</dt>
        <dd>
The value <code>ProofSuite</code>.
        </dd>
        <dt>canonicalizationAlgorithm</dt>
        <dd>
A URL that identifies the <a>canonicalization algorithm</a> to use on the
<var>document</var>. For example:
<code>https://w3id.org/security#GCA2015</code>.
        </dd>
        <dt>digestAlgorithm</dt>
        <dd>
A URL that identifies the <a>message digest algorithm</a> to use on the
<var>canonicalized document</var>. For example:
<code>https://www.ietf.org/assignments/jwa-parameters#SHA256</code>
        </dd>
        <dt>proofAlgorithm</dt>
        <dd>
A URL that identifies the <a>proof algorithm</a> to use on the
<var>data to be signed</var>. For example:
<code>https://www.ietf.org/assignments/jwa-parameters#RS256</code>
        </dd>
      </dl>

      <p>
A complete example of a <a>proof suite</a> is shown in the next example:
      </p>

      <pre class="example highlight">
{
  "id": "https://w3id.org/security#RsaSignature2018",
  "type": "ProofSuite",
  "canonicalizationAlgorithm": "https://w3id.org/security#GCA2015",
  "digestAlgorithm": "https://www.ietf.org/assignments/jwa-parameters#SHA256",
  "proofAlgorithm": "https://www.ietf.org/assignments/jws-parameters#RSASSA-PSS"
}
      </pre>
    </section>

    <section>
      <h2>Algorithms</h2>

      <p>
The algorithms defined below are generalized in that they require a specific
<a>canonicalization algorithm</a>, <a>message digest algorithm</a>, and
<a>proof algorithm</a> to be used to achieve the algorithm's intended
outcome.
      </p>

      <section>
        <h3>Proof Algorithm</h3>

<div class="issue">The proof parameters should be included as headers
and values in the data to be signed.</div>

        <p>
The following algorithm specifies how to create a digital proof that can
be later used to verify the authenticity and integrity of a
<a>linked data document</a>. A <a>linked data document</a>,
<var>document</var>, <a>proof options</a>, <var>options</var>,
and a <a>private key</a>, <var>privateKey</var>, are required inputs.
The <a>proof options</a> MUST contain an identifier for the
public/private key pair, <var>creator</var>, and an ISO8601 combined date and
time string, <var>created</var>, containing the current date and time,
accurate to at least one second, in Universal Time Code format. A <a>nonce</a>
and a <a>domain</a> may also be specified in the <var>options</var>. A
<a>signed linked data document</a> is produced as output. Whenever this
algorithm encodes strings, it MUST use UTF-8 encoding.
        </p>

        <ol class="algorithm">
          <li>
Create a copy of <var>document</var>, hereafter referred to as <var>output</var>.
          </li>
          <li>
Generate a <var>canonicalized document</var> by canonicalizing
<var>document</var> according to a <a>canonicalization algorithm</a>
(e.g. the <em>GCA2015</em> [[!RDF-DATASET-NORMALIZATION]] algorithm).
        </li>
          <li>
Create a value <var>tbs</var> that represents the data to be signed, and
set it to the result of running the
<a href="#create-verify-hash-algorithm">Create Verify Hash Algorithm</a>,
passing the information in <var>options</var>.
          </li>
          <li>
Digitally sign <var>tbs</var> using the <var>privateKey</var> and the
the <var>digital proof algorithm</var> (e.g. JSON Web Proof using
<em>RSASSA-PKCS1-v1_5</em> algorithm). The resulting string is the
<a>proofValue</a>.
          </li>
          <li>
Add a <code>proof</code> node to <var>output</var> containing
a <a>linked data proof</a> using the appropriate
<var>type</var> and <a>proofValue</a> values as well as
all of the data in the <var>proof options</var> (e.g.
<var>creator</var>, <var>created</var>, and if given, any additional proof
options such as <a>nonce</a> and <a>domain</a>).
          </li>
          <li>
Return <var>output</var> as the <a>signed linked data document</a>.
          </li>
        </ol>

      </section>

      <section>
        <h3>Proof Verification Algorithm</h3>
        <p class="issue">
This algorithm is highly specific to digital signatures and needs to be
generalized to other proof mechanisms such as Equihash.
        </p>

        <p>
The following algorithm specifies how to check the authenticity and
integrity of a <a>signed linked data document</a> by verifying its
digital proof. This algorithm takes a
<a>signed linked data document</a>, <var>signed document</var> and
outputs a <code>true</code> or <code>false</code> value based on whether or
not the digital proof on <var>signed document</var> was verified. Whenever
this algorithm encodes strings, it MUST use UTF-8 encoding.
        </p>

<div class="issue">Specify how the public key can be obtained (through
some out-of-band process and passed in or it can be retrieved by
derefencing its URL identifier, etc.</div>

        <ol class="algorithm">
          <li>
Get the <a>public key</a> by dereferencing its URL identifier in
the <code>proof</code> node of the default graph of
<var>signed document</var>. Confirm that the <a>linked data document</a>
that describes the <a>public key</a> specifies its owner and that its
owner's URL identifier can be dereferenced to reveal a bi-directional link back
to the key. Ensure that the key's owner is a trusted entity before proceeding
to the next step.
          </li>
          <li>
Let <var>document</var> be a copy of <var>signed document</var>.
          </li>
          <li>
Remove any <code>proof</code> nodes from the default graph in
<var>document</var> and save it as <var>proof</var>.
          </li>
          <li>
Generate a <var>canonicalized document</var> by canonicalizing
<var>document</var> according to the <a>canonicalization algorithm</a>
(e.g. the </var><em>GCA2015</em> [[!RDF-DATASET-NORMALIZATION]] algorithm).
          </li>
          <li>
Create a value <var>tbv</var> that represents the data to be verified, and
set it to the result of running the
<a href="#create-verify-hash-algorithm">Create Verify Hash Algorithm</a>,
passing the information in <var>proof</var>.
          </li>
          <li>
Pass the <a>proofValue</a>, <var>tbv</var>,
and the <a>public key</a> to the <a>proof algorithm</a>
(e.g. JSON Web Proof using <em>RSASSA-PKCS1-v1_5</em> algorithm).
Return the resulting boolean value.
          </li>
        </ol>
      </section>

      <section>
        <h3>Create Verify Hash Algorithm</h3>

        <p class="issue">
This algorithm is too specific to digital signatures and needs to be
generalized for algorithms such as Equihash.
        </p>
        <p>
The following algorithm specifies how to create the data that is used
to generate or verify a digital proof. It takes a canonicalized
<a>linked data document</a>, <var>canonicalized document</var>,
<a>canonicalization algorithm</a>, a <a>message digest algorithm</a>, and
<a>proof options</a>, <var>input options</var> (by reference).
The <a>proof options</a> MUST contain an identifier for the
public/private key pair, <var>creator</var>, and an ISO8601 combined date and
time string, <var>created</var>, containing the current date and time,
accurate to at least one second, in Universal Time Code format. A <a>nonce</a>
and a <a>domain</a> may also be specified in the <var>options</var>.
Its output is a data that can be used to generate or verify a
digital proof (it is usually further hashed as part of the
verification or signing process).
        </p>

        <ol class="algorithm">
          <li>
Let <var>options</var> be a copy of <var>input options</var>.
          </li>
          <li>
If <code>type</code>, <code>id</code>, or <code>proofValue</code>
exists in <var>options</var>, remove the entry.
          </li>
          <li>
If <var>created</var> does not exist in <var>options</var>, add an
entry with a value that is an ISO8601 combined date and
time string containing the current date and time accurate to at least one
second, in Universal Time Code format. For example:
<code>2017-11-13T20:21:34Z</code>.
          </li>
          <li>
Generate <var>output</var> by:
            <ol class="algorithm">
              <li>
Creating a <var>canonicalized options document</var> by canonicalizing
<var>options</var> according to the <a>canonicalization algorithm</a>
(e.g. the <em>GCA2015</em> [[!RDF-DATASET-NORMALIZATION]] algorithm).
              </li>
              <li>
Hash <var>canonicalized options document</var> using the
<a>message digest algorithm</a> (e.g. SHA-256) and set <var>output</var>
to the result.
              </li>
              <li>
Hash <var>canonicalized document</var> using the <a>message digest algorithm</a>
(e.g. SHA-256) and append it to <var>output</var>.
              </li>
            </ol>
          </li>
          <li>
<div class="issue">This last step needs further clarification. Signing
implementations usually automatically perform their own integrated
hashing of an input message, i.e. signing algorithms are a combination
of a raw signing mechanism and a hashing mechanism such as
RS256 (RSA + SHA-256). Current implementations of RSA-based
Linked Data Proof suites therefore do not perform this last step
before passing the data to a signing algorithm as it will be performed
internally. The Ed25519Proof2018 algorithm also does not perform
this last step -- and, in fact, uses SHA-512 internally. In short,
this last step should better communicate that the 64 bytes produced
from concatenating the SHA-256 of the canonicalized options with the
SHA-256 of the canonicalized document are passed into the signing
algorithm with a presumption that the signing algorithm will include
hashing of its own.</div>
Note: It is presumed that the 64-byte <var>output</var> will be used
in a signing algorithm that includes its own hashing algorithm, such
as RS256 (RSA + SHA-256) or EdDsa (Ed25519 which uses SHA-512).
          </li>
          <li>
Return <var>output</var>.
          </li>
        </ol>
      </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>

<div class="issue">TODO: We need to add a complete list of security
considerations.</div>
    </section>

  </body>
</html>