This specification describes a mechanism for ensuring the authenticity and integrity of Linked Data documents using mathematical proofs.
This is an experimental specification and is undergoing regular revisions. It is not fit for production deployment.
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.
The Linked Data Proofs specification achieves the following design goals:
The following terms are used to describe concepts involved in the generation and verification of Linked Data digital proofs.
example.com
, a
ad-hoc value such as mycorp-level3-access
, or a very
specific transaction value like 8zF6T$mqP
. A signer may
include a domain in its digital proof to restrict its use
to particular target, identified by the specified domain.
A linked data proof 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]].
A linked data proof typically includes at least the following attributes:
RsaSignature2018
.
Since this specification is based on Linked Data, the terms type
,
creator
, created
, domain
,
nonce
, and proofValue
above
map to URLs. The vocabulary where these terms are defined is the
[[SECURITY-VOCABULARY]].
A proof can be added to a Linked Data document like the following:
{ "@context": "https://w3id.org/identity/v1", "title": "Hello World!" }
by adding the parameters outlined in this section:
{ "@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" } }
The proof example above uses the RsaSignature2018
proof suite to produce a verifiable digital proof.
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.
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 proof
key in a 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" }] }
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
proofChain
key in a 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" }] }
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 proof suite name (e.g.
RsaSignature2018
) 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.
This section details the cryptographic primitives that are available to proof suite developers.
At a minimum, a proof suite must have the following attributes:
https://w3id.org/security#RsaSignature2018
.
ProofSuite
.
https://w3id.org/security#GCA2015
.
https://www.ietf.org/assignments/jwa-parameters#SHA256
https://www.ietf.org/assignments/jwa-parameters#RS256
A complete example of a proof suite is shown in the next example:
{ "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" }
The algorithms defined below are generalized in that they require a specific canonicalization algorithm, message digest algorithm, and proof algorithm to be used to achieve the algorithm's intended outcome.
The following algorithm specifies how to create a digital proof that can be later used to verify the authenticity and integrity of a linked data document. A linked data document, document, proof options, options, and a private key, privateKey, are required inputs. The proof options MUST contain an identifier for the public/private key pair, creator, and an ISO8601 combined date and time string, created, containing the current date and time, accurate to at least one second, in Universal Time Code format. A nonce and a domain may also be specified in the options. A signed linked data document is produced as output. Whenever this algorithm encodes strings, it MUST use UTF-8 encoding.
proof
node to output containing
a linked data proof using the appropriate
type and proofValue values as well as
all of the data in the proof options (e.g.
creator, created, and if given, any additional proof
options such as nonce and domain).
This algorithm is highly specific to digital signatures and needs to be generalized to other proof mechanisms such as Equihash.
The following algorithm specifies how to check the authenticity and
integrity of a signed linked data document by verifying its
digital proof. This algorithm takes a
signed linked data document, signed document and
outputs a true
or false
value based on whether or
not the digital proof on signed document was verified. Whenever
this algorithm encodes strings, it MUST use UTF-8 encoding.
proof
node of the default graph of
signed document. Confirm that the linked data document
that describes the public key 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.
proof
nodes from the default graph in
document and save it as proof.
This algorithm is too specific to digital signatures and needs to be generalized for algorithms such as Equihash.
The following algorithm specifies how to create the data that is used to generate or verify a digital proof. It takes a canonicalized linked data document, canonicalized document, canonicalization algorithm, a message digest algorithm, and proof options, input options (by reference). The proof options MUST contain an identifier for the public/private key pair, creator, and an ISO8601 combined date and time string, created, containing the current date and time, accurate to at least one second, in Universal Time Code format. A nonce and a domain may also be specified in the options. 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).
type
, id
, or proofValue
exists in options, remove the entry.
2017-11-13T20:21:34Z
.
The following section describes security considerations that developers implementing this specification should be aware of in order to create secure software.