Linked Data Signatures 1.0

Terminology

The following terms are used to describe concepts involved in the generation and verification of Linked Data digital signatures.

linked data document: A document comprised of Linked Data.
signed linked data document: A linked data document that has been digitally signed.
linked data signature: A set of attributes that represent a Linked Data digital signature and the parameters required to verify it.
signature options: A set of options that is included in the signature data. These options may be a domain, nonce, or other data that is specific to the signature format.
signature suite: 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.
public key: A cryptographic key that can be used to verify digital signatures created with a corresponding private key.
private key: A cryptographic key that can be used to generate digital signatures.
domain: A string value that specifies the operational domain of a digital signature. This may be an Internet domain name like 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 signature to restrict its use to particular target, identified by the specified domain.
canonicalization algorithm: An algorithm that takes an input document that has more than one possible representation and always transforms it into a canonical form. This process is sometimes also called normalization.
message digest algorithm: 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.
signature algorithm: 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.

Linked Data Signature Overview

A linked data signature is compromised 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]].

A linked data signature typically includes at least the following attributes:

type (required)
: A URI that identifies the digital signature suite that was used to create the signature. For example: LinkedDataSignature2015.
creator (required)
: 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 linked data document 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.
created (required)
: The string value of an [[!ISO8601]] combined date and time string generated by the Signature Algorithm.
domain (optional)
: A string value specifying the restricted domain of the signature.
nonce (optional, but strongly recommended)
: A string value that is included in the digital signature and MUST only be used once for a particular domain and window of time. This value is used to mitigate replay attacks.
signatureValue (required)
: The value of the signature value generated by the Signature Algorithm.

Since this specification is based on Linked Data, the terms type, creator, created, domain, nonce, and signatureValue above map to URLs. The vocabulary where these terms are defined is the [[SECURITY-VOCABULARY]].

A signature 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!",
  "signature": {
    "type": "LinkedDataSignature2015",
    "creator": "http://example.com/i/pat/keys/5",
    "created": "2011-09-23T20:21:34Z",
    "domain": "example.org",
    "nonce": "2bbgh3dgjg2302d-d2b3gi423d42",
    "signatureValue": "OGQzNGVkMzVm4NTIyZTkZDY...NmExMgoYzI43Q3ODIyOWM32NjI="
  }
}

The signature example above uses the LinkedDataSignature2015 signature suite to produce a verifiable digital signature.

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.

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 `LinkedDataSignature2015` 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.

Specify that linked data documents are syntax agnostic. Specify the URLs that property values like signature map to, for instance, in the security vocabulary.

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.

Add an explicit check on key type to prevent an attacker from selecting an algorithm that may abuse how the key is used/interpreted.

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.

Multiple Signatures

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.

Signature Sets

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 signature key in a document.

{
  "@context": "https://w3id.org/identity/v1",
  "title": "Hello World!",
  "signature": [{
    "type": "RsaSignature2015",
    "creator": "http://example.com/i/pat/keys/5",
    "created": "2011-09-23T20:21:34Z",
    "domain": "example.org",
    "nonce": "2bbgh3dgjg2302d-d2b3gi423d42",
    "signatureValue": "OGQzNGVkMzVm4NTIyZTkZDY...NmExMgoYzI43Q3ODIyOWM32NjI="
  }, {
    "type": "RsaSignature2015",
    "creator": "http://example.com/i/kelly/keys/7f3j",
    "created": "2011-09-23T20:24:12Z",
    "domain": "example.org",
    "nonce": "83jj4hd62j49gk38",
    "signatureValue": "zVm4NTIyZTkZDYOGQzNGVkM...3Q3ODIyOWM32NjINmExMgoYzI4="
  }]
}

Signature Chains

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 signatureChain key in a document.

{
  "@context": "https://w3id.org/identity/v1",
  "title": "Hello World!",
  "signatureChain": [{
    "type": "RsaSignature2015",
    "creator": "http://example.com/i/pat/keys/5",
    "created": "2011-09-23T20:21:34Z",
    "domain": "example.org",
    "nonce": "2bbgh3dgjg2302d-d2b3gi423d42",
    "signatureValue": "OGQzNGVkMzVm4NTIyZTkZDY...NmExMgoYzI43Q3ODIyOWM32NjI="
  }, {
    "type": "RsaSignature2015",
    "creator": "http://bank.example.com/notary/keys/7f3j",
    "created": "2011-09-23T20:24:12Z",
    "domain": "example.org",
    "nonce": "83jj4hd62j49gk38",
    "signatureValue": "yZTkZDYOGzNGVkMVm4NTIQz...M32NjINmExMDIyOWgoYzI43Q3O="
  }]
}

Signature Suites

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 signature suite name (e.g. LinkedDataSignature2015) 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.

This section details the cryptographic primitives that are available to signature suite developers.

At a minimum, a signature suite must have the following attributes:

id: A URL that identifies the signature suite. For example: https://w3id.org/security#LinkedDataSignature2015.
type: The value SignatureSuite.
canonicalizationAlgorithm: A URL that identifies the canonicalization algorithm to use on the document. For example: https://w3id.org/security#URDNA2015.
digestAlgorithm: A URL that identifies the message digest algorithm to use on the canonicalized document. For example: http://example.com/digests#sha512
signatureAlgorithm: A URL that identifies the signature algorithm to use on the data to be signed. For example: http://www.w3.org/2000/09/xmldsig#rsa-sha256

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

{
  "id": "https://w3id.org/security#LinkedDataSignature2015",
  "type": "SignatureSuite",
  "canonicalizationAlgorithm": "https://w3id.org/security#URDNA2015",
  "digestAlgorithm": "http://example.com/digests#sha512",
  "signatureAlgorithm": "http://www.w3.org/2000/09/xmldsig#rsa-sha256"
}

Algorithms

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

Signature Algorithm

The signature parameters should be included as headers and values in the data to be signed.

The following algorithm specifies how to create a digital signature that can be later used to verify the authenticity and integrity of a linked data document. A linked data document, document, signature options, options, and a private key, privateKey, are required inputs. The signature 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.

Create a copy of document, output.
Remove any signature nodes from the default graph in output.
Generate a canonicalized document by canonicalizing document according to a canonicalization algorithm (e.g. the URDNA2015 [[!RDF-DATASET-NORMALIZATION]] algorithm).
Create a value tbs that represents the data to be signed, and set it to the result of running the Create Verify Hash Algorithm, passing the information in options.
Digitally sign tbs using the privateKey and the the digital signature algorithm (e.g. RSASSA-PKCS1-v1_5 [[!PKCS1]]) and base-64 encode the resulting value. The resulting base-64 encoded string is the signatureValue.
Add a signature node to output containing a linked data signature using the appropriate type and signatureValue values as well as all of the data in the signature options (e.g. creator, created, and if given, any additional signature options such as nonce and domain).
Return output as the signed linked data document.

Signature Verification Algorithm

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

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.

Get the public key by dereferencing its URL identifier in the signature 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.
Let document be a copy of signed document.
Remove any signature nodes from the default graph in document and save it as signature.
Generate a canonicalized document by canonicalizing document according to the canonicalization algorithm (e.g. the URDNA2015 [[!RDF-DATASET-NORMALIZATION]] algorithm).
Create a value tbv that represents the data to be verified, and set it to the result of running the Create Verify Hash Algorithm, passing the information in signature.
Base-64 decode the signatureValue and pass it, tbv, and the public key to the signature algorithm (e.g. RSASSA-PKCS1-v1_5 [[!PKCS1]]). Return the resulting boolean value.

Create Verify Hash Algorithm

The following algorithm specifies how to create the data that is used to generate or verify a digital signature. It takes a canonicalized linked data document, canonicalized document, canonicalization algorithm, a message digest algorithm, and signature options, input options (by reference). The signature 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 message digest that can be used to generate or verify a digital signature.

Let options be a copy of input options.
If type, id, or signatureValue exists in options, remove the entry.
If created does not exist in options, 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: 2017-13-13T20:21:34Z.
Generate output by:
1. Creating a canonicalized options document by canonicalizing options according to the canonicalization algorithm (e.g. the URDNA2015 [[!RDF-DATASET-NORMALIZATION]] algorithm).
2. Hash canonicalized options document using the message digest algorithm (e.g. SHA-256) and set output to the result.
3. Hash canonicalized document using the message digest algorithm (e.g. SHA-256) and append it to output.
Hash output using the message digest algorithm (e.g. SHA-256) and replace it with the result.
Return output.

Introduction

Design Goals and Rationale