ReShare

Scalable Reliability for Data Sharing on the Web

W3C Member Submission

More details about this document
This version:
https://www.w3.org/Submission/2023/SUBM-reshare-20230501/
Latest published version:
https://www.w3.org/Submission/reshare/
Latest editor's draft:
https://w3id.org/reshare/spec/authors-draft/
History:
Commit history
Editor:
Stefan Decker (Fraunhofer Institute for Applied Information Technology)
Authors:
Simon Mangel (Computer Science 5, RWTH Aachen University)
Lars Gleim (Computer Science 5, RWTH Aachen University)
Jan Pennekamp (Communication and Distributed Systems, RWTH Aachen University)
Feedback:
GitHub ReShare-DTC/reshare-w3c-member-submission (pull requests, new issue, open issues)

Copyright © 2022 Fraunhofer Institute for Applied Information Technology. This document is available under the W3C Document License. See the W3C Intellectual Rights Notice and Legal Disclaimers for additional information.

Abstract

The ReShare system constitutes a uniform approach to ensure accountable and trustworthy data sharing and collaboration in Open Data ecosystems based on Digital Transmission Contracts (DTCs). DTCs are bilaterally signed digital records immutably certifying the data and context of a data transmission without the typical overhead of distributed ledger technologies. By leveraging open Web technologies, a simple and common cryptography architecture, and a bilateral signature paradigm, the system promises superior performance and scalability to common approaches such as manual records management or blockchain-based solutions while providing immutability and fraud protection guarantees sufficient for a variety of use cases, such as data accountability and liability assurance in aircraft manufacturing. In this document, we specify (1) the structure and representations of DTCs, (2) the ReShare ontology used to embed DTCs into the Semantic Web, and (3) the protocol and necessary mechanisms to create and verify DTCs.

Status of This Document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

By publishing this document, W3C acknowledges that the Submitting Members have made a formal Submission request to W3C for discussion. Publication of this document by W3C indicates no endorsement of its content by W3C, nor that W3C has, is, or will be allocating any resources to the issues addressed by it. This document is not the product of a chartered W3C group, but is published as potential input to the W3C Process. A W3C Team Comment has been published in conjunction with this Member Submission. Publication of acknowledged Member Submissions at the W3C site is one of the benefits of W3C Membership. Please consult the requirements associated with Member Submissions of section 3.3 of the W3C Patent Policy. Please consult the complete list of acknowledged W3C Member Submissions.

1. Introduction

This section is non-normative.

Information sharing between parties on the Internet is omnipresent. However, there is a severe lack of efficient and scalable methods to prove the existence, contents, and context of a data transfer.

Especially in the context of data-driven business models, data trustworthiness and reliability are extremely important to minimize data quality-related risks in the business model. Therefore, an approach, which is able to guarantee both of these properties in the context of data sharing, and scale up to the future needs w.r.t. data throughput, is needed. The relevance of inter-organizational data sharing is stressed by the vision of an Internet of Production (IoP), where open data sharing approaches leverage cross-domain collaboration, resulting in a multitude of benefits for all participants [TowardsIoP].

In this document, we describe ReShare (Reliable Data Sharing through Digital Transmission Contracts). ReShare provides data integrity, authenticity, and immutability in data exchanges between two parties through digital contracting using on-demand bilateral signatures. By establishing an irrefutable commitment by the two parties to the data transmission, data trustworthiness, and reliability emerge.

ReShare is a unified solution for the Web, built from open Web technology, and adresses an important research gap. That is, ReShare is both highly scalable, and does not rely on pre-existing trust relations, which both are essential requirements in the context of the Web.

ReShare employs signature-based strong data immutability to be feasible as a unified solution for the Web. Further, the design provides a system which is flexible to the payload (i.e., the shared data to be made trustworthy and reliable), and therefore supports any Web resource or content, including plain text, Linked Data payloads, JSON, and binary data, amongst other formats.

The structure of this document is as follows: In Section 3. A Primer to Data Sharing, we introduce the relevant terminology and outline typical data sharing scenarios motivating the need for scalable immutability, authenticity, and integrity. In Section 4. Digital Transmission Contracts (DTCs), we describe the paradigm and structure of Digital Transmission Contracts (DTCs), which are at the core of ReShare. After that, we propose the ReShare ontology in Section 5. The ReShare Ontology, which is used to define the semantics of DTCs in the context of Linked Data. Finally, we describe the generation and verification mechanisms needed to process DTCs in Section 6. DTC Generation & Verification.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

3. A Primer to Data Sharing

This section is non-normative.

For a formal understanding of data sharing and its applications, Section 3.1 Background gives an introduction to data sharing, and Section 3.2 Terminology formalizes the used terminology. In Section 3.3 Example Scenario, we introduce a use case scenario which we use throughout the remainder of the document for clarifications and examples.

3.1 Background

Data sharing is a central concept of the Web. In recent years, fueled by developments in data-driven business and industries, challenges of fitting the process of data sharing to more advanced requirements, such as trustworthiness and reliability, have emerged.

As the source of data used in industrial collaborations often is external, it has no inherent trustworthiness compared to self-produced data. This increases the risk of legal and safety issues for the data user, as the liability for incidents caused by the data cannot immediately be attributed to its source.

Solving the challenges of data trustworthiness and reliability has been shown to enable a variety of novel business models based on data-driven decision making [OEZER-TRUST], where the data sharing process is made transparent to the data users through the ability to reliably trace the provenance of data. Further, data sharing in inter-organizational collaborations has been shown to provide the basis for benefits such as cost reductions, increased profit margins, and general improvements in product quality and safety [TowardsIoP].

The Challenge of Data Trustworthiness

Wherever corrupted or forged data imposes a relevant risk, the user should carefully assess the trustworthiness of its data. That is, users need some rationale for trusting the authenticity and correctness of data. This rationale may be a strong trust relationship with the data source, some form of digital proof of authenticity and integrity, or even the result of manual data curation.

The Challenge of Data Reliability

Especially in safety-critical environments, the data user might need confidence in the reliability of data, i.e., that the data itself is valuable and usable beyond its initial use, i.e., it should keep its initial value to the user. One relevant aspect of data reliability is that the data source cannot easily repudiate the state of the shared data later, neither by forging contradicting data, nor by repudiating the earlier data transmission at all.

Similar as for data trustworthiness, some kind of rationale for this reliability is necessary, e.g., a strong pre-existing trust relationship with the data source, or some kind of mechanism to notice adversaries by the data source and solve the resulting conflicts.

Relevance of the Web

The Web is a prime candidate to enable reliable data sharing as it is commonly used to exchange information between different stakeholders. As the importance of Open Data increases steadily, a system for trustworthy and reliable data sharing built using open Web standards and technology can both profit from the inherent data sharing capabilities of the Web, and facilitate integration into an Open Data paradigm.

Existing approaches to trustworthy and reliable data sharing, such as mutually trusted mediators and distributed ledgers, might be applicable to small-scale use cases with either pre-existing trust relations or low requirements to system scalability. However, Web-scaled systems have specific, more challenging needs. First, the possible limitation of a trust assumption in a system would severely limit its potential, as common trust in a central mediator can hardly be assumed in a global network such as the Web. Second, existing no-trust solutions, such as manual data curation and even distributed ledger technology, do not meet tomorrow's needs toward scalability for efficient usage on the whole Web.

3.2 Terminology

This section is non-normative.

In the following, we introduce the necessary terminology used throughout the document.

3.2.1 Concepts

This section is non-normative.

While the presented terms and concepts may have different definitions in practice, ReShare builds on the terminology introduced in the following.

data sharing
Data sharing denotes a process in which one party, the sender, grants a second party (or group of parties), the receiver (or receivers), access to a set of data. The data is then transmitted from the sender to the receiver as a data transmission.
trustworthiness
(Data) trustworthiness denotes the subjective judgment of the data correctness by the data user. The term correctness here includes integrity and authenticity, but is not limited to it. Rather, it covers the complete data pipeline, and thus, for example, also considers errors in measurement, inaccuracies, or intentional forgery or manipulation by the (authentic) data source.
reliability
Data reliability denotes the guarantees available to a data user to prove aspects of data correctness before, at, and after the initial use of the data.
immutability

We define data to be immutable if it can be uniquely referenced, and that reference always refers to exactly the same data at any point in time. This directly implicates that once published, data cannot be manipulated afterward without assigning a different identifier.

We further differentiate between weak and strong data immutability:

  • In a weak data immutability system, an identifier scheme defines how data can be created and published in an immutable manner. However, such a system does not protect against misuse of the immutability scheme, and has no in-built mechanisms to immediately notice or resolve misuses.
  • In a strong immutability system, any action violating the immutability property leads to an inconsistent state of the system. The system provides mechanisms to both recognize such inconsistencies, and resolve them to a consistent state. Therefore, at any point in time, one can unambiguously determine the correct state of any immutable data point.
    Note

    It is unclear whether a perfect strong immutability system can practically exist. Most systems striving at providing strong data immutability come with practical assumptions and limitations. For example, the consensus state of a distributed consensus mechanism can be determined with a high probability, but not with full certainty. Furthermore, if a large proportion of the participants of a consensus network collude, the immutability guarantee cannot hold.

3.2.2 Process and Agents of Data Sharing

This section is non-normative.

IRI
An Internationalized Resource Identifier (IRI) [RFC3987] is a globally unique identifier in the form of a sequence of characters from the Universal Character Set, as defined in Internationalized Resource Identifiers (IRIs).
sender
Denotes the sending party in a data transmission. This term is always used in the context of a data transmission and refers to the direction of dataflow. Each sender has an associated globally unique identifier in the form of an IRI. Means by which this IRI can unambiguously identify a party are further discussed in Section A.2 Identity Management.
receiver
Denotes the receiving party in a data transmission. This term is always used in the context of a data transmission and refers to the direction of dataflow. Each sender has an associated globally unique identifier in the form of an IRI. Means by which this IRI can unambiguously identify a party are further discussed in Section A.2 Identity Management.
resource
A data point or object which can be uniquely identified through an IRI.
fact

An immutable revision of a resource, uniquely and persistently referenced through an IRI specific to the revision. This implies that given the IRI, the data identified by the IRI cannot be altered. In this context, the persistent IRI of a fact can also be referred to as a FactID.

Note

The term originated from FactDAG, a formalization model of data interoperability which was proposed in a research paper by Gleim et al. [FactDAG], where it denotes a data point that was explicitly made immutable by means of a revisioning system.

3.3 Example Scenario

This section is non-normative.

We employ an example scenario of inter-organizational data sharing in aircraft manufacturing to clarify the concepts and terminology introduced above.

Setup

This example considers the supplier-manufacturer relation in the highly-regulated and safety-critical process of aircraft engineering.

Three parties are involved in the scenario: Two part suppliers, A-Corp and B-Tech, as well as a manufacturer C-Aviation, which assembles the final product (here: aircraft).

In this simple scenario, both A-Corp and B-Tech supply parts (wings and propellers) to C-Aviation. Additionally, besides a flow of physical products, a dataflow exists in parallel. The data might include relevant production data, conformance certificates, etc.

In this dataflow, A-Corp and B-Tech are the senders, and C-Aviation is the receiver.

Further, the precision of the placement of a certain rivet used in a wing by A-Corp might be a resource as part of the production data shared with C-Aviation. By using a revision identifier, e.g., the timestamp of measurement, the resource can be lifted to an immutable resource revision, i.e., a fact.

The scenario, including the flow of physical goods and data, is visualized below.

Example scenario in aircraft manufacturing.

Figure 1 The example scenario in aircraft manufacturing. Besides a physical dataflow of the suppliers (A and B) to the manufacturer (C), production data is shared with C.

Trustworthiness & Reliability through Common Methods

Data shared between the parties is used in processes such as production and audits, which are critical for product safety. Thus, it is extremely important that C-Aviation assesses the trustworthiness and reliability of the data. These properties can reduce the risk of data-caused damage or shift liability for said damage to the suppliers.

To establish a common ground of trustworthiness and reliability, C-Aviation agrees upon a conformance agreement in the form of a paper-based contract with its suppliers. This practice naturally is a labor-intensive process, as such documents have to be created, sent between the companies, and archived physically. Here, the data storage layer comprises physical archives, where the paper-based contracts are stored.

After describing the concept of DTCs in the following, we will discuss an application to this scenario together with corresponding benefits in Section 4.2 Application to the Example Scenario

4. Digital Transmission Contracts (DTCs)

4.1 Mutual Commitment through Bilateral Signatures

This section is non-normative.

DTCs leverage digital signatures to create strong data immutability within a defined scope, which we further describe below. DTCs deviate from the common paradigm of document signatures by enforcing the signatures to be created during data transmission, thus allowing to involve a second party, the receiver, in the signature process.

For a clear differentiation, we can classify common uses of signatures into one of the following two paradigms:

pre-created signatures
Also known as document signatures, are signatures that are created by the data source (or publisher) and are not bound to a specific transmission. Thus, such signatures can be efficiently created on publication and only need to be created once in the lifetime of the document. This type of signatures is usually used on data platforms, document stores, etc.
on-demand signatures
Also known as message signatures, are signatures that are specific to a single data transmission or communication process. Therefore, On-demand signatures cannot be pre-computed in most cases, as they are bound to that specific transmission or communication process. On-demand signatures are commonly used to establish authenticity and non-repudiation in messaging and communication protocols, e.g., OpenPGP [RFC4880].
Note

The terms of pre-created and on-demand signatures are not canonical, as a clear differentiation between these signature paradigms can rarely be found in literature.

DTCs are linked to a specific data transmission and comprise a signature by both the sender and the receiver. Therefore, the signatures cannot be pre-computed during publishing, i.e., they are on-demand signatures.

Because the receiver signs the state of the data, the sender alone cannot forge a valid DTC by itself. Therefore, as long as sender and receiver do not collude to forge rogue signature pairs, the valid DTC can unambiguously be determined by the pair of valid signatures by both parties. Thus, this approach provides strong data immutability under the assumption of no inter-party collusion.

While the assumption of no inter-party collusion may seem limiting at first, it still covers a substantial set of use cases, i.e., inter-party conflicts of sender and receiver. Thus, DTCs can be applied wherever sender and receiver do not trust each other and want to have mutual proof of the data sharing process. In our example from Section 3.3 Example Scenario, this assumption covers a variety of possible scenarios, including proving data authenticity in liability conflicts and creating secure and non-repudiable product conformance and quality certificates between C-Aviation and the two suppliers.

If the receiver would not sign the DTC, the sender could create signatures for arbitrary data. If a rogue sender would now sign different versions of the same fact, the correct version of the fact would become ambiguous, thus violating the data immutability.

In the example from Section 3.3 Example Scenario, the production data of a propeller supplied by B-Tech may hint at a production fault that leads to an incident with the respective airplane. During the incident inspection and liability process, B-Tech might now supply corrected data together with valid certificates and thereby claim that the supplied parts were not faulty to the best of their knowledge. The data immutability is violated in this case, as one cannot unambiguously determine the original version of B-Tech's production data.

4.2 Application to the Example Scenario

This section is non-normative.

In Section 3.3 Example Scenario, we introduced an exemplary scenario from the aviation industry. The original process relied on costly and management-intensive paper-based contracting and archiving methods.

If the concept of DTCs is applied to the exemplary data sharing process, substantial parts of the system can be implemented digitally. These parts comprise of

  • the contracts, in which an agreement about the data transmission is made, including the signatures by both parties, and
  • the storage system for storing and archiving the transmission contracts.

The application of DTCs within the data sharing process is visualized below.

Application of DTCs to the example scenario in aviation.

Figure 2 The application of DTCs to the example scenario in the aviation industry. DTCs (1) are certified by sender and receiver, (2) secure the transmitted data, and (3) are stored (longtime) in digital secure storage systems.

In the example scenario, a DTC is linked to all three layers of the data sharing process:

  1. Physical layer:
    The parties A-Corp and C-Aviation both certify (1) the DTC by adding a digital signature. Both parties are linked to their physical identities by a public key certificate (see Section 4.3 DTC Data Structure for details). Further, the production data produced by factories is secured in the DTC (2).
  2. Data Storage layer:
    Both parties can store the DTC to profit from its benefits in later situations, including audits and liability conflicts. In the example of aircraft manufacturing, the parties are even required legally to securely store the contracts for several years.
  3. Dataflow layer:
    The DTC itself is constructed in parallel to the underlying production data transmission in a generation handshake (see Section 6.1 DTC Generation Handshake for details).

4.3 DTC Data Structure

DTCs have a defined object structure. Its components are defined as contract fields.

In the following, we define the content and substructure of the contract fields. All fields not explicitly marked as optional MUST be present in any valid DTC. A valid DTC MUST NOT contain any fields which are not specified below.

Note

To disambiguate between the terms defined in Section 3.2 Terminology and the contract fields above, contract fields are always typeset as red-orange monospace font, e.g., sender vs sender).

baseIRI

The base IRI which can be used to uniquely identify the DTC.

The base IRI is selected by the sender or receiver during the DTC generation handshake (see Section 6.1 DTC Generation Handshake) and is used as both the IRI for the DTC itself, as well as an IRI prefix for its subcomponents in the JSON-LD representation (see Section 4.4.2 JSON-LD)

The base IRI SHOULD end with a # delimiter, i.e., the "#" ifragment part, where ifragment is empty, such that the sub-IRIs assigned in the JSON-LD representation (Section 4.4.2 JSON-LD) use the ifragment part to identify the subcomponent.

sender

Identity of the sender, i.e., the sender's IRI and a public key certificate. The IRI uniquely links the DTC to the sender, and the public key certificate contains the public key needed to verify the sender's signature contained in senderSig.

The sender field has the following subcomponents:

authID
The IRI of the sender. SHOULD be related to the public key certificate contained in the cert field. A discussion on linking the certificate to the authority IRI can be found in Section A.2 Identity Management.
cert
An X.509 public key certificate or certificate chain of the sender. The verification of the certificate (chain) requires a shared trust anchor (e.g., a commonly trusted root CA).
type
"X509"/"X509-single" for a single X.509 certificate, "PKCS7"/"X509-PKCS7-chain" for a certificate chain bundled into a PKCS #7 message [RFC2315]. These two types MUST be implemented. While we do not specify other types in this document, this field can be used to implement different certificate types in future extensions.
encoding
Encoding of the certificate. Always set to "base64", which refers to the certificate (chain) in DER notation encoded using Base64 [RFC4648]. The purpose of this field is both for the data structure to be self-describing and to allow for possible extensions of other encodings.
receiver

Identity of the receiver, i.e., an IRI and a public key certificate. The IRI uniquely links the DTC to the receiver, and the public key certificate contains the public key needed to verify the receiver's signature contained in receiverSig.

The substructure is equivalent to the sender field.

senderSig

The contract signature created by the sender according to Section 4.5.3 Signature Creation.

The senderSig field has the following subcomponents:

sig
The signature data, encoded as a string according to the encoding field (see below).
type
The signature type used. MUST always be set to "urn:oid:1.2.840.113549.1.1.10", which is the Object Identifier (OID) [RFC3061] of the RSASSA-PSS signature scheme as defined in PKCS #1 v2.2 [RFC8017]. We use the URN Namespace of Object Identifiers [RFC3001] to make the identifier interpretable as an IRI. The purpose of this field is both for the data structure to be self-describing and to allow for possible extensions of other signature schemes.
encoding
Encoding of the signature data. MUST always be set to "base64", specifying that the signature value is encoded using Base64 [RFC4648] according to Section 4.5.3 Signature Creation. The purpose of this field is both for the data structure to be self-describing and to allow for possible extensions of other encodings.
receiverSig
Contract signature created by the receiver. Analogous to senderSig.
facts

A set of one or more fact checksums.

This field binds the DTC to the state of the transmitted data by including fact checksums, which are implemented using cryptographic hash functions.

Any implementation SHOULD interpret this field as an unordered list. Whenever a canonical representation is needed, the set MUST be transformed into an ordered list by sorting the elements lexicographically by factID in the UTF-8 encoding [RFC3629] (e.g., see Section 4.5.2 Pre-Processing).

A single fact checksum has the following subcomponents:

factID
The IRI of the fact. MUST be unique in the set of facts.
requestedID
(Optional) During the DTC generation mechanism (cf. Section 6.1 DTC Generation Handshake), the sender MAY update the IRI in factID (e.g., in order to provide a persistent fact IRI for long-term referenceability). In this case, this field contains the IRI which was originally requested.
Note

The procedure of updating the factID is included to support factID negotiation. Example scenarios:

  • The receiver does not know the revision ID, which transforms a resource to a fact by means of an immutable revisioning scheme, and thus only requests the latest revision of a resource. The sender adds the latest revision ID to the factID to identify an immutable fact.
  • The receiver uses a deprecated fact identification scheme. The sender can transform the deprecated factID into a new one.
<alg>

The checksum, created by hashing a serialization of the fact.

The hash algorithm MUST be specified through the field name, i.e., <alg> MUST be replaced by one of the supported algorithms listed below.

The hash values MUST be encoded as a hexadecimal string, i.e., using digits and the letters a-f or A-F. The encoding SHOULD use lowercase letters.

The supported hash algorithms are cryptographic hash functions, so that an attacker cannot forge data that collides with the checksum. Such a vulnerability could lead to misuse of existing DTCs, or ambiguity w.r.t. the verifiability of the underlying data.

Currently supported algorithms:

serialization
A serialization identifier. In this document, we specify a baseline set of serialization identifiers. Every implementation MUST be able to interpret these serialization identifiers. Extensions to these identifiers MAY be specified in the future.
  • "binary": A (trivial) binary representation of the fact
  • "string": A (trivial) string representation of the fact
  • "canonical_json": A representation of the fact as canonicalized JSON according to the JSON Canonicalization Scheme (JCS) [RFC8785].
  • "URDNA2015": The Linked Data associated with a fact, serialized as normalized N-Quads [N-Quads] according to the URDNA2015 algorithm.
    Note

    We recognize that Linked Data canonicalization is an open issue, and the specification of the specified algorithm is at a draft status. As the algorithm is not a direct component of ReShare, and we argue for an extensible serialization identifier scheme, we consider this remark to be tolerable.

A trivial serialization of a given resource MUST be interpretable without the need to perform any transformations. E.g., if the fact is a JPEG image, the binary serialization (identified by the "binary" identifier) can be considered trivial, as JPEG is a binary file format and does not need to be transformed. A JSON document, however, cannot be trivially serialized as a binary object without transformations, as the choice of the character set, the canonicalization scheme, etc. are ambiguous.
senderCustomContent/receiverCustomContent

(Optional) DTC fields that MAY be used to add custom content or metadata to a DTC as a JSON object.

If one of these fields is present, it MUST contain exactly one JSON object (i.e., enclosed by curly brackets).

timestamp
A timestamp that binds the DTC to the time of transmission. Specifically, it binds to the point in time during DTC generation, where one of the two involved parties adds the fact checksums to the DTC. The timestamp is encoded as a string in the Internet date/time format [RFC3339], which is a profile of ISO 8601 [ISO8601].

4.4 DTC Representations

By default, DTCs are represented as JSON [RFC8259]. To make DTCs interpretable as Linked Data, we further define an associated JSON-LD [JSON-LD11] context. We deem JSON the default representation, as it can be transformed to the JSON-LD representation without context by the procedure defined below, and thus reduces the overhead in storage and transmission of (partial) DTCs.

Any implementation MUST support the creation, validation, and interpretation of the JSON DTC representation, which we describe in Section 4.4.1 JSON.

Implementations MAY support the transformations from and to JSON-LD. In this case, these transformations MUST be implemented according to Section 4.4.2 JSON-LD.

4.4.1 JSON

We define a default JSON representation for DTCs. Every contract field is represented by a root-level submember of a JSON object. The content of each field and sub-field is described above in Section 4.3 DTC Data Structure.

To specify the structure of the JSON representation of a DTC, we build upon the specification of JSON Schema [JSON-SCHEMA][JSON-SCHEMA-VALIDATION]. While we recognize that this specification is still in a draft state, we find this tolerable due to the nature of this document being a member submission. We further specifically use the 2020-12 version of the draft of JSON Schema to avoid ambiguities.

We define three schemas: The schema for a partial DTC, the schema for a complete DTC, and the schema for a partial DTC, where only the two signatures may be missing. The two latter schemas extend the partial DTC schema by requiring the fields to be present.

For a JSON representation of a DTC to be syntactically valid, a JSON schema validator implemented according to the 2020-12 version of JSON schema MUST successfully test the JSON representation to the JSON schema of a complete DTC.

In the following, we give an example of a complete DTC as a JSON object, according to the descriptions above. The contract contains four fact checksums (in facts), where the fact itself could trivially be serialized as a string. The public key certificates (in sender and receiver) are single X.509 certificates directly signed by an imaginary root CA.

Example 1: Example DTC (JSON) (non-normative) 
{
  "baseIRI": "https://example.com/contracts/2021-09-24/134",
  "sender": {
    "type": "X509",
    "encoding": "base64",
    "cert": "MIIEkTCCAnmgAwIBAgIUTpTAugWv4ZYQX9nk2zETfVcMi38wDQYJKoZIhvcNAQELBQAwTDELMAkGA1UEBhMCREUxEzARBgNVBAgMClNvbWUtU3RhdGUxEzARBgNVBAoMCkV4YW1wbGUgQ0ExEzARBgNVBAMMCkV4YW1wbGUgQ0EwHhcNMjEwNDE1MjExMTExWhcNMjIwNDE1MjExMTExWjAzMR0wGwYDVQQKDBRFeGFtcGxlIGNoYWluIGNlcnQgMTESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvw8C6sqLUVSOwFPbZsqS/1cL/+7aaaxVPwXs7TjPVombwNLyJW8yPyyQLbsTN5evVCpNdzciYc9Nhh77AYrqCiOsZBb7hu/PMqNqDvU2FAHeTH9KZ1PSpsOdgzG4i9widL6FBKGrxvlyj0G5ztQoGtymJFdmQ8K/ZN2W5Bi27H24UgITO+mX5MGmzFfyib7bDnvNqZUMJEgpSGt+jUf/7pMtuQqusrE1bfg5vvCbHIPHx2KXqzQEjNiioDafzKjIY2NSakis1AZe+J46o/Za0L8TUMXPvO1nSX4VMm9w5Qqf8auKdlUnT7fVqGKxQvPgX/JM/ksduZqZdTE1giWDgQIDAQABo4GDMIGAMB0GA1UdDgQWBBQtTnbTodwlQnP0QXA2VRv6DBWgzzAfBgNVHSMEGDAWgBR+/85DLJ8v0EP1y6kv/I9XPsHQ5TAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwEwDQYJKoZIhvcNAQELBQADggIBAG47hxcjEY6kXojCadK15iW5t6P2p2NCfXpymeRuVaHiI7hhMwQEPymGqXZe0MKUKaRxb9BssG9UvndJw7PWdLx55Y498dgEVXWp7UWUg+VmLxE0wrS+7odJ6ZwsSTPhlgQVF3y9SOP18UX1Iy+ipkdPVbeiQB2QJOYLdxj3h26a/BevyWJU7jTbZO9fNX3FlopyQbB64QPJKJyQiYrT1td7lOcreyBJUS2e5p+hifW/ukxHQ9QtfN+mE/MlnUSHar6LgXPX3AoiVKc14L5E7jRHLDCvFWO1PfVCsS6RWIKdoWsEUytDnMYLHb2TmMJWQf8S69BLyqgEhKXNS9hZceGr32jM9O6TepYKZNH5A1QLjZcuHHKUAzXMjM9loNLra/VGcqrMTdZYautGl8EdEURqE063qDd+Hsp3Vqw0iALQHcbEb6R1b2o5dIrczo+PINTSvnFv+4GyqznXEYjcueLrR/R6kE9GNOiPUxpont+0s1JCAKPaaZk97Z09ldtD47rPQLQgWopDadVOm3Gu9+ef7uqqpJw9+q384mqgw4P1Yws6aVkXLdvh8MCXcMEYi2AeQVCCZv2CjAh8CZQC+0P2JtkhWlCxPoSDk4jbm6koCxcpL3CRcc5LtTTrev5+Mi0oDMiLzx09GNls3SQzdKdP9PM+Y7E7y4Xi2LW3FtoG",
    "authID": "http://example.com/sender"
  },
  "receiver": {
    "type": "X509",
    "encoding": "base64",
    "cert": "MIIEkTCCAnmgAwIBAgIUTpTAugWv4ZYQX9nk2zETfVcMi4AwDQYJKoZIhvcNAQELBQAwTDELMAkGA1UEBhMCREUxEzARBgNVBAgMClNvbWUtU3RhdGUxEzARBgNVBAoMCkV4YW1wbGUgQ0ExEzARBgNVBAMMCkV4YW1wbGUgQ0EwHhcNMjEwNDE1MjExNDM1WhcNMjIwNDE1MjExNDM1WjAzMR0wGwYDVQQKDBRFeGFtcGxlIGNoYWluIGNlcnQgMTESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuKe4H5GwuaKS02s6oAnQF0e30TLyB3joT5GNzwa94WXuLjU8SWKqOjLQyIN2ZBtZW1jNI3By6nsPoU3t181SBStFI25JZ8PUvJ9/Skf/adRmrtXHX8MYRBqN4d1JIRdOoLxwq+bI0UIyMmMNMTjvhnWwTx4FkXwup5fna9FFBbtOGP+7vMVl98L2/bDMJwwLdnzUs0CKLyqDRx0XWAnp6R6CN9YDeMgpdDviMkBfeY74AJ084v6pWnx+K0PlUuQAkiuPvcRsDxgjHRO18rq4wA6Dxh6My7Xh/uHFzb5cmLT7C7kfr+WN26va8IRGCF8NWdOYQ0HSo/vbY/eIOB/G0wIDAQABo4GDMIGAMB0GA1UdDgQWBBSmlyw0Ht9gF3rnI42Us1dK9+jZ/DAfBgNVHSMEGDAWgBR+/85DLJ8v0EP1y6kv/I9XPsHQ5TAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwEwDQYJKoZIhvcNAQELBQADggIBABMLMfSOAwk34LEK9L/A1qtHTJPQ2BF3XjnbswINNao0oOI3PSWKU0weWYlITH29hgyzrwO8A9ifaOFPtsRxe9/UNv6RNqwObLpxF+f2U3ulu2hTzd7l/ZXUGYaBUHLL3Cu1JlZWMRoTUBUHAvkwnQlUkQLJZ7A+N9y+FfV5apIMTwPA+C2lwiVtEd3Hje5Z9lUmjwiARRnsliRuCm2ZY0IHvneQN7NnOFCFFQQnu/7wMEywNWR3NMtj5AcMugs56OqcAglwq+HqYNCUkelt1/I7A/NwitaPEYu/1TDjQBckR6nbtJwHKFx2M9heB+E5iMI65r+ae01jBr+r7tes6UdEz7SCF3xHks3ubKfRQykZzTZ7ixeHYG5XjaUSSk8EDuBCdZOJ/AUAA+Rar/UPODUd1YQUZDUqs0MvB9zXQYBtEhwii75pCmkFBpZewo6xyktdP3964q7MZPZQZTZimh02CxcWdXZj6JkoL6ihuM36UciS9rXUgIGGdJcbhC5mP/PqRYsAzipOvQiRL7mGRB9L8H0Wt08yl3H0KFwGcgasML8tOOkf+4MsGIHJZaJ20cVfdWm1StOtLN1Bn+gAppq8nlvDgPiQ3NxSsvY+Qpb0WSVWknc1VyOPKexKaM20/alMv/fykVhVmmAcNVshIMAuKV5TnhqeZyg8L02pVAHL",
    "authID": "http://example.com/receiver"
  },
  "senderSig": {
    "type": "urn:oid:1.2.840.113549.1.1.10",
    "encoding": "base64",
    "sig": "S82Al/YgpfjywjagQ03tjr8WT2oiMSkuYGA5hoXL/LCZHJhR4UGuXyQe1lJ6+yDRiN8FbKcp6ZrClb645rKpIK9UP/Y50wOo/vXCdeUGRqWj4NduoJsBKAP9O4QfQQkT9POHwcbYDsbvEGm3M7fh7mrOn6PzQQgq8vNGayVP5VmFLofxhArc2cy7/TthDl5sBwngpIokHUGOIE+RXasifJ/KS+DALU2s51EZzP2NuTbOvC2328UD5yhvHTopwqn3OrMWbKjF8UUDFjQHYx383hrK3VPjqfrMMNT3OHiJB6t9pJwZ3lmD3PV0Axp6k1XV+oxckBaYN7dCNneQn+zkcw=="
  },
  "receiverSig": {
    "type": "urn:oid:1.2.840.113549.1.1.10",
    "encoding": "base64",
    "sig": "P70POEihM3V+pX+lPmvyoDzhERRuuat4P+jGIN/ME1n4hrl9vHb7l8yXy04iT2lNRXv2wkPfPC55nNCTCjWkPhF9Ca6KM6km0BHanPT9J7DZYuCes3RiPwEqO2UsVVZMxj/kMpwu0X23+SHjpAycGY7M/ZRG5iasQiu4N4f/O6pmNTOE6AqpgdhqACqUInbCN3afbdIUnFdbQSRn16VKmrmgUtus5XrVMsCEEZ3xlw8Pl+1toHgWllK4bnm3+DO4wdNb9wvM5TMrqCGHGZOkkxdlZ2pK3uSHuWtvifA49Ks113giNz6ZNjbWvmq9AJRY8/qVQUCBwZaBeSBqZRUMMw=="
  },
  "facts": [
    {
      "factID": "http://example.com/facts/fact1",
      "sha256": "5fc62b0e99a143ff2b99b56a6953f07e96f52023aa3739bba3fec1194292f48e",
      "serialization": "string"
    },
    {
      "factID": "http://example.com/facts/fact2",
      "sha256": "828bbc97b5b866992dc8bc532265e3094bc9e17cce05e16d90844d2160ad99cf",
      "serialization": "string"
    },
    {
      "factID": "http://example.com/facts/fact3",
      "sha256": "c646cfa0feda9af766e6eca97f8578f3eb2b126d2349ea7ce1fd2d3b3fe2d456",
      "serialization": "string"
    },
    {
      "factID": "http://example.com/facts/fact4",
      "sha256": "5845f61bccd9c5631dee29f9e87830b11eb5b531081a8888db42e80e2f153fc0",
      "serialization": "string"
    }
  ],
  "timestamp": "2021-04-15T21:50:29.940Z",
  "senderCustomContent": {
    "authMethod": "PublicKey",
    "authSuccessful": true,
    "authUserId": "user123456"
  },
  "receiverCustomContent": {
    "dbStorageId": "StorageCluster5"
  }
}

4.4.2 JSON-LD

We use the ReShare ontology v0.3, which we describe in Section 5. The ReShare Ontology, for defining the semantics of the JSON structure in a JSON-LD [JSON-LD11] representation for DTCs.

Instead of defining a schema for the JSON-LD representation of DTCs, we specify a procedure to transform a JSON representation of a DTC into a JSON-LD representation, and a procedure to transform a JSON-LD representation to a JSON representation.

JSON to JSON-LD

To raise a valid JSON DTC serialization to JSON-LD, the following transformation steps MUST be conducted:

  1. Add the static @context object
  2. Add @type keywords to the non-literal (sub-)objects
  3. Add the contract base IRI to the @context object as an IRI prefix
  4. Add @id keywords to the non-literal sub-objects

Details about the steps are presented in the following and MUST be followed when creating a JSON-LD representation of a DTC.

Note

In the following examples, the misuse of the triple-dot notation denotes that the rest of the JSON structure is not changed. As it is only used in informative examples, it does not violate the normative character of this section.

  1. The following static @context object (corresponding to version 0.3 of the ReShare ontology) MUST be added to the root of the DTC object:
    Example 2: DTC JSON-LD context 
    {
  "@context": {
    "fc": "https://w3id.org/reshare/ontology/0.3/#",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "facts": {
      "@id": "fc:fact",
      "@context": {
        "factID": {
          "@id": "fc:factOrigin",
          "@type": "@id"
        },
        "sha256": {
          "@id": "fc:sha256Sum",
          "@type": "xsd:hexBinary"
        },
        "sha384": {
          "@id": "fc:sha384Sum",
          "@type": "xsd:hexBinary"
        },
        "sha512": {
          "@id": "fc:sha512Sum",
          "@type": "xsd:hexBinary"
        },
        "serialization": "fc:serialization"
      }
    },
    "sender": {
      "@id": "fc:sender",
      "@context": {
        "authID": {
          "@id": "fc:identifies",
          "@type": "@id"
        },
        "type": "fc:certType",
        "cert": {
          "@id": "fc:x509Cert",
          "@type": "xsd:base64Binary"
        },
        "encoding": "fc:certEncoding"
      }
    },
    "receiver": {
      "@id": "fc:receiver",
      "@context": {
        "authID": {
          "@id": "fc:identifies",
          "@type": "@id"
        },
        "type": "fc:certType",
        "cert": {
          "@id": "fc:x509Cert",
          "@type": "xsd:base64Binary"
        },
        "encoding": "fc:certEncoding"
      }
    },
    "senderSig": {
      "@id": "fc:senderSig",
      "@context": {
        "type": {
          "@id": "fc:sigType",
          "@type": "@id"
        },
        "sig": {
          "@id": "fc:sigData",
          "@type": "xsd:base64Binary"
        },
        "encoding": "fc:sigEncoding"
      }
    },
    "receiverSig": {
      "@id": "fc:receiverSig",
      "@context": {
        "type": {
          "@id": "fc:sigType",
          "@type": "@id"
        },
        "sig": {
          "@id": "fc:sigData",
          "@type": "xsd:base64Binary"
        },
        "encoding": "fc:sigEncoding"
      }
    },
    "senderCustomContent": {
      "@id": "fc:senderCustomContent",
      "@type": "@json"
    },
    "receiverCustomContent": {
      "@id": "fc:receiverCustomContent",
      "@type": "@json"
    },
    "timestamp": {
      "@id": "fc:timestamp",
      "@type": "xsd:dateTimeStamp"
    }
  }
}

  2. The following (sub-)objects of the DTC object MUST be typed explicitly with the following types by adding a @type attribute to their root-level attributes:

    JSON object Type IRI
    Root DTC object fc:DTC
    Each entry of facts fc:Fact
    sender fc:Sender
    receiver fc:Receiver
    senderSig fc:Signature
    receiverSig fc:Signature
    Note

    All other contract fields do not need to be typed, as they are represented as literals in JSON-LD, and are typed through the @context objects.

    The assignment of @type attributes is illustrated with the following example.

    Example 3: Explicitly typing a DTC using @type (non-normative) 
    {
  "@type": "fc:DTC",
  "facts": [
    {
      "@type": "fc:Fact",
      ...
    },
    ...
  ],
  "receiver": {
    "@type": "fc:Receiver",
    ...
  },
  "receiverSig": {
    "@type": "fc:Signature",
    ...
  },
  "sender": {
    "@type": "fc:Sender",
    ...
  },
  "senderSig": {
    "@type": "fc:Signature",
    ...
  },
  ...
}

  3. An IRI prefix for the keyword contract MUST be added to the @context object. The prefix MUST be set to the baseIRI of the contract.

    The step is illustrated with the following example. Note that the baseIRI attribute existed beforehand. Its value is simply copied to the IRI prefix definition.

    Example 4: Adding the base IRI of the DTC to its context as an IRI prefix (non-normative) 
    {
  "@context": {
    "contract": "http://example.com/contracts/1#",
    ...
  },
  "baseIRI": "http://example.com/contracts/1#",
  ...
}

  4. The following (sub-)objects of the DTC object MUST be made identifiable with the following IRIs (relative to the root DTC IRI) by adding a @id attribute to their root-level attributes:

    JSON object Resource IRI
    Each entry of facts contract:fact-<i>, where <i> is the index of the entry within facts when sorted lexicographically by factID (starting with contract:fact-0)
    sender contract:sender
    receiver contract:receiver
    senderSig contract:senderSig
    receiverSig contract:senderSig
    Note

    All other contract fields are not assigned an IRI, as they are represented as literals in JSON-LD, and thus do not have their own IRIs. Instead, they can be queried through the data properties of the DTC resource.

    The assignment of @id attributes is illustrated with the following example.

    Example 5: Explicitly adding IRIs to the DTC subcomponents using @id (non-normative) 
    {
  "facts": [
    {
      "@id": "contract:fact-0",
      ...
    },
    {
      "@id": "contract:fact-1",
      ...
    },
    {
      "@id": "contract:fact-2",
      ...
    },
    {
      "@id": "contract:fact-3",
      ...
    }
  ],
  "receiver": {
    "@id": "contract:receiver",
    ...
  },
  "receiverSig": {
    "@id": "contract:receiverSig",
    ...
  },
  "sender": {
    "@id": "contract:sender",
    ...
  },
  "senderSig": {
    "@id": "contract:senderSig",
    ...
  },
  ...
}

In the following, we give the example of a DTC represented in JSON-LD, where the static part of the @context object is omitted for readability.

Example 6: Example DTC (JSON-LD) (non-normative) 
{
  "@context": {
    ...
  },
  "@id": "http://example.com/contracts/1",
  "@type": "fc:DTC",
  "facts": [
    {
      "@id": "contract:fact-0",
      "@type": "fc:Fact",
      "factID": "http://example.com/facts/fact1",
      "serialization": "string",
      "sha256": "5fc62b0e99a143ff2b99b56a6953f07e96f52023aa3739bba3fec1194292f48e"
    },
    {
      "@id": "contract:fact-1",
      "@type": "fc:Fact",
      "factID": "http://example.com/facts/fact2",
      "serialization": "string",
      "sha256": "828bbc97b5b866992dc8bc532265e3094bc9e17cce05e16d90844d2160ad99cf"
    },
    {
      "@id": "contract:fact-2",
      "@type": "fc:Fact",
      "factID": "http://example.com/facts/fact3",
      "serialization": "string",
      "sha256": "c646cfa0feda9af766e6eca97f8578f3eb2b126d2349ea7ce1fd2d3b3fe2d456"
    },
    {
      "@id": "contract:fact-3",
      "@type": "fc:Fact",
      "factID": "http://example.com/facts/fact4",
      "serialization": "string",
      "sha256": "5845f61bccd9c5631dee29f9e87830b11eb5b531081a8888db42e80e2f153fc0"
    }
  ],
  "receiver": {
    "@id": "contract:receiver",
    "@type": "fc:Receiver",
    "type": "X509",
    "encoding": "base64",
    "authID": "http://example.com/receiver",
    "cert": "MIIEkTCCAnmgAwIBAgIUTpTAugWv4ZYQX9nk2zETfVcMi4AwDQYJKoZIhvcNAQELBQAwTDELMAkGA1UEBhMCREUxEzARBgNVBAgMClNvbWUtU3RhdGUxEzARBgNVBAoMCkV4YW1wbGUgQ0ExEzARBgNVBAMMCkV4YW1wbGUgQ0EwHhcNMjEwNDE1MjExNDM1WhcNMjIwNDE1MjExNDM1WjAzMR0wGwYDVQQKDBRFeGFtcGxlIGNoYWluIGNlcnQgMTESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuKe4H5GwuaKS02s6oAnQF0e30TLyB3joT5GNzwa94WXuLjU8SWKqOjLQyIN2ZBtZW1jNI3By6nsPoU3t181SBStFI25JZ8PUvJ9/Skf/adRmrtXHX8MYRBqN4d1JIRdOoLxwq+bI0UIyMmMNMTjvhnWwTx4FkXwup5fna9FFBbtOGP+7vMVl98L2/bDMJwwLdnzUs0CKLyqDRx0XWAnp6R6CN9YDeMgpdDviMkBfeY74AJ084v6pWnx+K0PlUuQAkiuPvcRsDxgjHRO18rq4wA6Dxh6My7Xh/uHFzb5cmLT7C7kfr+WN26va8IRGCF8NWdOYQ0HSo/vbY/eIOB/G0wIDAQABo4GDMIGAMB0GA1UdDgQWBBSmlyw0Ht9gF3rnI42Us1dK9+jZ/DAfBgNVHSMEGDAWgBR+/85DLJ8v0EP1y6kv/I9XPsHQ5TAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwEwDQYJKoZIhvcNAQELBQADggIBABMLMfSOAwk34LEK9L/A1qtHTJPQ2BF3XjnbswINNao0oOI3PSWKU0weWYlITH29hgyzrwO8A9ifaOFPtsRxe9/UNv6RNqwObLpxF+f2U3ulu2hTzd7l/ZXUGYaBUHLL3Cu1JlZWMRoTUBUHAvkwnQlUkQLJZ7A+N9y+FfV5apIMTwPA+C2lwiVtEd3Hje5Z9lUmjwiARRnsliRuCm2ZY0IHvneQN7NnOFCFFQQnu/7wMEywNWR3NMtj5AcMugs56OqcAglwq+HqYNCUkelt1/I7A/NwitaPEYu/1TDjQBckR6nbtJwHKFx2M9heB+E5iMI65r+ae01jBr+r7tes6UdEz7SCF3xHks3ubKfRQykZzTZ7ixeHYG5XjaUSSk8EDuBCdZOJ/AUAA+Rar/UPODUd1YQUZDUqs0MvB9zXQYBtEhwii75pCmkFBpZewo6xyktdP3964q7MZPZQZTZimh02CxcWdXZj6JkoL6ihuM36UciS9rXUgIGGdJcbhC5mP/PqRYsAzipOvQiRL7mGRB9L8H0Wt08yl3H0KFwGcgasML8tOOkf+4MsGIHJZaJ20cVfdWm1StOtLN1Bn+gAppq8nlvDgPiQ3NxSsvY+Qpb0WSVWknc1VyOPKexKaM20/alMv/fykVhVmmAcNVshIMAuKV5TnhqeZyg8L02pVAHL"
  },
  "receiverCustomContent": {
    "dbStorageId": "StorageCluster5"
  },
  "receiverSig": {
    "@id": "contract:receiverSig",
    "@type": "fc:Signature",
    "sig": "JepGwNLofxFFCvewKe+OBFm7G+YOvfqrAz3+z+jEAiPlpNtuXrQo3WM8g9SHyMpccu4BBPlKflSynI/OC6X7JL9kuJchg93gRBk/PjfTj8bUSaewCW3CVPe50zznJC7R9rcjUVtyLDIva558RJaJwVzgwO6YH+1/+hU4qKVHUyUuxBJSbWrBuOHBjavQQdq2utaja6h8dx1bLcBHAMjKxM4rIfUzXgjzkJk/D/DEZvSIRMnBafnqDQFvjB/eSZQa+oSSxKXS6dXskOKlxS9HvnRn2CsWEjhDrCIyphwEUj8qqhv1rsPWpiIXYVewWcsRxaYDfoe6+5hgquXR1i3nrg==",
    "type": "urn:oid:1.2.840.113549.1.1.10",
    "encoding": "base64"
  },
  "sender": {
    "@id": "contract:sender",
    "@type": "fc:Sender",
    "type": "X509",
    "encoding": "base64",
    "authID": "http://example.com/sender",
    "cert": "MIIEkTCCAnmgAwIBAgIUTpTAugWv4ZYQX9nk2zETfVcMi38wDQYJKoZIhvcNAQELBQAwTDELMAkGA1UEBhMCREUxEzARBgNVBAgMClNvbWUtU3RhdGUxEzARBgNVBAoMCkV4YW1wbGUgQ0ExEzARBgNVBAMMCkV4YW1wbGUgQ0EwHhcNMjEwNDE1MjExMTExWhcNMjIwNDE1MjExMTExWjAzMR0wGwYDVQQKDBRFeGFtcGxlIGNoYWluIGNlcnQgMTESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvw8C6sqLUVSOwFPbZsqS/1cL/+7aaaxVPwXs7TjPVombwNLyJW8yPyyQLbsTN5evVCpNdzciYc9Nhh77AYrqCiOsZBb7hu/PMqNqDvU2FAHeTH9KZ1PSpsOdgzG4i9widL6FBKGrxvlyj0G5ztQoGtymJFdmQ8K/ZN2W5Bi27H24UgITO+mX5MGmzFfyib7bDnvNqZUMJEgpSGt+jUf/7pMtuQqusrE1bfg5vvCbHIPHx2KXqzQEjNiioDafzKjIY2NSakis1AZe+J46o/Za0L8TUMXPvO1nSX4VMm9w5Qqf8auKdlUnT7fVqGKxQvPgX/JM/ksduZqZdTE1giWDgQIDAQABo4GDMIGAMB0GA1UdDgQWBBQtTnbTodwlQnP0QXA2VRv6DBWgzzAfBgNVHSMEGDAWgBR+/85DLJ8v0EP1y6kv/I9XPsHQ5TAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwEwDQYJKoZIhvcNAQELBQADggIBAG47hxcjEY6kXojCadK15iW5t6P2p2NCfXpymeRuVaHiI7hhMwQEPymGqXZe0MKUKaRxb9BssG9UvndJw7PWdLx55Y498dgEVXWp7UWUg+VmLxE0wrS+7odJ6ZwsSTPhlgQVF3y9SOP18UX1Iy+ipkdPVbeiQB2QJOYLdxj3h26a/BevyWJU7jTbZO9fNX3FlopyQbB64QPJKJyQiYrT1td7lOcreyBJUS2e5p+hifW/ukxHQ9QtfN+mE/MlnUSHar6LgXPX3AoiVKc14L5E7jRHLDCvFWO1PfVCsS6RWIKdoWsEUytDnMYLHb2TmMJWQf8S69BLyqgEhKXNS9hZceGr32jM9O6TepYKZNH5A1QLjZcuHHKUAzXMjM9loNLra/VGcqrMTdZYautGl8EdEURqE063qDd+Hsp3Vqw0iALQHcbEb6R1b2o5dIrczo+PINTSvnFv+4GyqznXEYjcueLrR/R6kE9GNOiPUxpont+0s1JCAKPaaZk97Z09ldtD47rPQLQgWopDadVOm3Gu9+ef7uqqpJw9+q384mqgw4P1Yws6aVkXLdvh8MCXcMEYi2AeQVCCZv2CjAh8CZQC+0P2JtkhWlCxPoSDk4jbm6koCxcpL3CRcc5LtTTrev5+Mi0oDMiLzx09GNls3SQzdKdP9PM+Y7E7y4Xi2LW3FtoG"
  },
  "senderCustomContent": {
    "authMethod": "PublicKey",
    "authSuccessful": true,
    "authUserId": "user123456"
  },
  "senderSig": {
    "@id": "contract:senderSig",
    "@type": "fc:Signature",
    "sig": "XW5nUNXY+06Llu9i4vUABpm4CpTHTPBy7rAYjGV/FG8CIuYffr4xYZkm6VIDApWQ3F38CwLDzEgy4bAT/u+kQshCM4MzIyGnqTzatvV8ZM3gfBJ6307h+t8VdBW3siXYcqexpA5CWVtqNWhCIme/sXEXkJQDQl1q5NljIcWiaJMHNUwg0IvCP1LLL8fcMr0Yj0sVKN5l8WuBpr6lLIsxOJgN6iWt/wM43pBO2G62/BR7FCWY1jE72gedGy16BBpn/KNkCRIr0ACcZNArZPYlISsHXpjOk3QoiUMakxgvdbdlpKZNFchbXU6ZlZTu3xyc67uddy6QzNID3yJ35Kcp3w==",
    "type": "urn:oid:1.2.840.113549.1.1.10",
    "encoding": "base64"
  },
  "timestamp": "2021-04-15T21:53:24.446Z"
}
JSON-LD to JSON

To transfer a JSON-LD representation of a DTC to a JSON representation, one MUST execute the following steps:

  1. Build the @context object by adding a contract IRI prefix to the static @context object from the JSON-to-JSON-LD transformation by copying the IRI of the DTC, similarly to step 3 of the JSON-to-JSON-LD transformation.
  2. Use the JSON-LD compaction algorithm [JSON-LD11-API] to compact the JSON-LD document together with the context built in Step 1.
  3. Remove all @type, @id, and @context attributes. Note: The baseIRI of the DTC is unaffected by this, as it is aliased as @id, and thus is not removed!

4.5 Signature Creation & Verification

A valid DTC MUST always contain two signatures, one by the sender, and one by the receiver. These signatures constitute a central component of the trust chain of a DTC, connecting the information included in DTCs (e.g., the checksums in facts) to the public keys of sender and receiver. The signatures are included in the DTC itself in the senderSig and receiverSig fields (see 4.3 DTC Data Structure).

The processes of creating and verifying DTC signatures, which are specified in the following, are the same for any party (sender or receiver). Thus, we only consider the sender in the following. For receiver signatures, analogous steps apply.

Each party (sender and receiver) MUST have an RSA public/private key pair which they use for creating DTC signatures. The public key of the key pair used to create DTC signatures MUST be included in the cert property of the respective identity field of the DTC, i.e., sender or receiver (see 4.3 DTC Data Structure).

4.5.1 Overview

The processes of signature creation and verification can be divided into three low-level processes: A pre-processing pipeline for generating a normalized binary serialization of a DTC (further described in Section 4.5.2 Pre-Processing), and both a signature creation and verification process based on the pre-processed form of a DTC (further described in Sections 4.5.3 Signature Creation and 4.5.4 Signature Verification respectively).

The integration of said low-level processes into the high-level processes of signature creation and verification is visualized in the two figures below.

DTC signature creation process (high-level)

Figure 3 The high-level process of creating a DTC signature. The DTC is pre-processed first before creating the DTC signature using the signer's private key.

DTC signature verification process (high-level)

Figure 4 The high-level process of verifying a DTC signature. The DTC is pre-processed first before verifiying the given DTC signature using the signer's public key.

4.5.2 Pre-Processing

The DTC pre-processing pipeline, as visualized below, consists of four steps and starts with the implementation-dependent internal representation of the DTC.

The pre-processing steps for creating and verifying DTC signatures

Figure 5 The pre-processing steps for creating and verifying DTC signatures. The internal DTC is serialized as specified by the JSON DTC represenation, pruned by removing unsigned material, normalized, and encoded as a UTF-8 string [RFC3629].

The four pre-processing steps MUST be executed as follows in order to uniquely serialize and normalize the DTC.

  1. Serialize: The (potentially incomplete) DTC MUST be serialized as JSON according to Section 4.4 DTC Representations. This representation MUST match the schema of a partial DTC, where only the two signatures may be missing, as defined in Section 4.4 DTC Representations.
  2. Remove unsigned content: To not impose a dependency on the ordering of signatures by the parties, pre-existing signature material MUST NOT be included in the signature. Thus, both the senderSig and receiverSig fields (if existing) MUST be removed in this step.
  3. Normalize: First, in order to achieve a unique order of the included facts, the facts array MUST be sorted by the ascending lexicographic order of the factID subproperty in UTF-8 encoding [RFC3629]. Afterward, the JSON document MUST be canonicalized according to the JSON Canonicalization Scheme (JCS) [RFC8785].
  4. Encode: To discretize the string encoding of the normalized JSON contract, it MUST be encoded using UTF-8 [RFC3629].

4.5.3 Signature Creation

The process of creating a DTC signature, based on its pre-processed form.

Figure 6 The process of creating a DTC signature, based on its pre-processed form. Using said pre-processed DTC and its own private key, the signing party creates an RSA signature, which is encoded as Base64 [RFC4648].

The signature MUST be created using the pre-processed form of the DTC as described in Section 4.5.2 Pre-Processing as the input to the RSASSA-PSS-SIGN operation specified in PKCS #1 [RFC8017].

For the EMSA-PSS-ENCODE encoding operation used in the RSASSA-PSS-SIGN operation, the following parameters MUST be selected:

  • Hash function (Hash): SHA-256 [FIPS-180-4]
  • Mask generation function (MGF): MGF1 [RFC8017]
  • Salt length (sLen): 32 (=hLen, i.e., the length of a SHA-256 hash in octets)

The binary output of the RSASSA-PSS signature creation primitive MUST be encoded as Base64 [RFC4648].

The encoded signature can be used as the sig subfield of the senderSig or receiverSig DTC fields (the field associated with the signer), as specified in Section 4.3 DTC Data Structure.

4.5.4 Signature Verification

The process of verifying a DTC signature, based on its pre-processed form.

Figure 7 The process of verifying a DTC signature, based on its pre-processed form. Requires said pre-processed DTC, the DTC signature encoded as Base64 [RFC4648], and the signing party's public key. The signature is first decoded into a binary form, and then verified using the pre-processed DTC and the public key.

To verify a given signature, as included in the senderSig or receiverSig DTC fields (see 4.3 DTC Data Structure), the encoded signature (here: senderSig) MUST be decoded as Base64 [RFC4648].

The DTC MUST be pre-processed according to 4.5.2 Pre-Processing.

Together with the pre-processed DTC, and the public key associated with the signature, the signature MUST then be verified according to the RSASSA-PSS-VERIFY operation as specified in PKCS #1 [RFC8017].

For the EMSA-PSS-VERIFY operation, which is used in the RSASSA-PSS-VERIFY operation, the same parameters as for EMSA-PSS-ENCODE (see 4.5.3 Signature Creation) MUST be used.

5. The ReShare Ontology

Standalone documentation:
Documentation v0.3
Revision:
0.3
Download serialization:
JSON-LD RDF/XML N-Triples TTL
Visualization:
Visualize with WebVowl

To enable the interpretation of DTCs as Linked Data, we propose the ReShare ontology. The ontology defines the properties and classes used in the JSON-LD representation of DTCs as specified in Section 4.4 DTC Representations.

5.1 Overview

5.2 Classes

Digital Transmission Contractc

IRI: http://w3id.org/reshare/ontology/0.3/#DTC

A Digital Transmisson Contract (DTC), used to create data immutability through bilateral signatures.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
is in domain of
custom content dp, has fact op, receiver op, receiver custom content dp, receiver signature op, sender op, sender custom content dp, sender signature op, timestamp dp

Factc

IRI: http://w3id.org/reshare/ontology/0.3/#Fact

A resource checksum which is included in a DTC.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
is in domain of
fact checksum (sha256) dp, fact checksum (sha384) dp, fact checksum (sha512) dp, fact origin op, fact serialization dp, requested fact origin op
is in range of
has fact op

Identityc

IRI: http://w3id.org/reshare/ontology/0.3/#Identity

An identity of a transmission party.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has sub-classes
Receiver c, Sender c
is in domain of
X.509 certificate dp, certificate encoding dp, certificate type dp, identifies op

Receiverc

IRI: http://w3id.org/reshare/ontology/0.3/#Receiver

The receiver of a transmission.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has super-classes
Identity c
is in range of
receiver op

Senderc

IRI: http://w3id.org/reshare/ontology/0.3/#Sender

The data source (sender) of a transmission.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has super-classes
Identity c
is in range of
sender op

Signaturec

IRI: http://w3id.org/reshare/ontology/0.3/#Signature

A contract signature created by one of the transmission parties.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
is in domain of
signature data dp, signature encoding dp, signature type op
is in range of
receiver signature op, sender signature op

5.3 Object Properties

fact originop

IRI: http://w3id.org/reshare/ontology/0.3/#factOrigin

The resource which is referenced by the fact.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Fact c

has factop

IRI: http://w3id.org/reshare/ontology/0.3/#fact

A fact included in a DTC.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Digital Transmission Contract c
has range
Fact c

identifiesop

IRI: http://w3id.org/reshare/ontology/0.3/#identifies

Links an identity of a receiver or sender as part of a contract to that entity. It is best practice to use an instance of foaf:Agent as the object to this property.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Identity c

receiverop

IRI: http://w3id.org/reshare/ontology/0.3/#receiver

The data receiver of the underlying transmission of a DTC.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Digital Transmission Contract c
has range
Receiver c

receiver signatureop

IRI: http://w3id.org/reshare/ontology/0.3/#receiverSig

The contract signature created by the receiver of the DTC.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Digital Transmission Contract c
has range
Signature c

requested fact originop

IRI: http://w3id.org/reshare/ontology/0.3/#requestedFactOrigin

The resource which was referenced by the receiver when initially requesting a contract. This property is used when the resource reference is updated by the sender during the contract generation handshake.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Fact c

senderop

IRI: http://w3id.org/reshare/ontology/0.3/#sender

The data source (sender) of the underlying transmission of a DTC.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Digital Transmission Contract c
has range
Sender c

sender signatureop

IRI: http://w3id.org/reshare/ontology/0.3/#senderSig

The contract signature created by the sender of the DTC.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Digital Transmission Contract c
has range
Signature c

signature typeop

IRI: http://w3id.org/reshare/ontology/0.3/#sigType

The type of a contract signature. The object should be an OID URN to a cryptographic signature scheme. As of now, 'urn:oid:1.2.840.113549.1.1.10' is considered the default value, identifying the RSASSA-PSS signature scheme as specified in PKCS #1 v2.2.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Signature c

5.4 Data Properties

certificate encodingdp

IRI: http://w3id.org/reshare/ontology/0.3/#certEncoding

Encoding of the (binary) certificate data object to the x509Cert property. 'base64' is considered the default value, expressing that the (binary) certificate data which is object to the x509Cert property is encoded using Base64.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Identity c
has range
literal

certificate typedp

IRI: http://w3id.org/reshare/ontology/0.3/#certType

The type of the certificate provided by the Identity. 'X509'/'X509-single' identify single X.509 certificates in ASN.1 DER notation, and 'PKCS7'/'X509-PKCS7-chain' identify an X.509 certificate chain encoded as a PKCS#7 message.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Identity c
has range
literal

custom contentdp

IRI: http://w3id.org/reshare/ontology/0.3/#customContent

The property linking a DTC to the custom content included by one of the parties. The object should be a literal with the JSON type (http://www.w3.org/1999/02/22-rdf-syntax-ns#JSON). Abstract property, use the sub-properties instead.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has sub-properties
receiver custom content dp, sender custom content dp
has domain
Digital Transmission Contract c
has range
literal

fact checksum (sha256)dp

IRI: http://w3id.org/reshare/ontology/0.3/#sha256Sum

A SHA-256 checksum of a fact. Should be encoded as a hex stream using the xsd:hexBinary literal type.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Fact c
has range
literal

fact checksum (sha384)dp

IRI: http://w3id.org/reshare/ontology/0.3/#sha384Sum

A SHA-384 checksum of a fact. Should be encoded as a hex stream using the xsd:hexBinary literal type.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Fact c
has range
literal

fact checksum (sha512)dp

IRI: http://w3id.org/reshare/ontology/0.3/#sha512Sum

A SHA-512 checksum of a fact. Should be encoded as a hex stream using the xsd:hexBinary literal type.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Fact c
has range
literal

fact serializationdp

IRI: http://w3id.org/reshare/ontology/0.3/#serialization

The serialization method used to create a verifiable fact checksum. Some string identifiers are defined in the specification of ReShare (see TODO: ref to ReShare)

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Fact c
has range
literal

receiver custom contentdp

IRI: http://w3id.org/reshare/ontology/0.3/#receiverCustomContent

The receiver's custom content.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has super-properties
custom content dp
has domain
Digital Transmission Contract c
has range
literal

sender custom contentdp

IRI: http://w3id.org/reshare/ontology/0.3/#senderCustomContent

The sender's custom content.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has super-properties
custom content dp
has domain
Digital Transmission Contract c
has range
literal

signature datadp

IRI: http://w3id.org/reshare/ontology/0.3/#sigData

The signature data, encoded as a character sequence. More information about the type and encoding can be provided with the sigType and sigEncoding properties. If Base64 is used for the character encoding, the literal type should be xsd:base64Binary.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Signature c
has range
literal

signature encodingdp

IRI: http://w3id.org/reshare/ontology/0.3/#sigEncoding

The signature encoding. 'base64' is considered the default value, expressing that the (binary) signature data which is object to the sigData property is encoded using Base64.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Signature c
has range
literal

timestampdp

IRI: http://w3id.org/reshare/ontology/0.3/#timestamp

The timestamp of a DTC. Should be in the RFC3339 profile of ISO 8601, and should have the xsd:dateTimeStamp literal type.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Digital Transmission Contract c
has range
literal

X.509 certificatedp

IRI: http://w3id.org/reshare/ontology/0.3/#x509Cert

The public key certificate of a transmission party. Should be the full certificate chain, excluding the root certificate, encoded as a character sequence. Further information about the certificate can be included in the certType and certEncoding properties. If Base64 is used for the character encoding, the xsd:base64Binary literal type should be used.

Is defined by
http://w3id.org/reshare/ontology/0.3/
Term status
stable
has domain
Identity c
has range
literal

Legend

c: Classes
op: Object Properties
dp: Datatype Properties
ni: Named Individuals

6. DTC Generation & Verification

Two core mechanisms are defined as part of ReShare:

Any implementation MUST implement the verification mechanism mechanism according to Section 6.2 DTC Verification.

The generation mechanism, which is specified in Section 6.1 DTC Generation Handshake, follows a client-server-paradigm. To allow for application-dependent lightweight implementations, the client and server parts of the generation mechanism MAY not be implemented. The following combinations are possible:

Server implemented Client implemented Description
Yes Yes Full implementation
Yes No Only supports sender role & DTC verification
No Yes Only supports receiver role & DTC verification
No No Only supports DTC verification

6.1 DTC Generation Handshake

The DTC generation mechanism constitutes a handshake, in which sender and receiver jointly create and sign a DTC in a client-server paradigm.

We specify two versions of this generation handshake: A complete 3-way version, which can be carried out completely in parallel to the underlying data transmission, and an abbreviated 2-way handshake, which can be used if the receiver has access to the complete underlying data of the DTC (i.e., the data transmission has to be completed already).

The benefits of the independence of DTC generation to the data transmission are expected to outweigh the effects of the increased overhead in most use cases. Thus, we consider the complete 3-way handshake the default handshake version. A brief elaboration on this discussion can be found in Section A.3 DTC Generation: Two Handshake Versions.

We do not specify any mechanism to separate handshake versions or negotiate the handshake version. Instead, such a mechanism MAY be implemented on a lower layer (e.g., by using HTTP content negotiation or using two ports for separating the two handshake versions).

6.1.1 Overview

This section is non-normative.

The specification of the DTC generation mechanism is divided into the following components:

  • Client and server implementations: Define the behavior which implements the handshake itself, depending on the handshake version (i.e., complete or abbreviated). The client and server implementations receive messages from the abstraction components for the lower-layer communication stack, build new messages, and send these messages to the abstraction components of the communication stack.
  • Helper components: We define a message builder, a message validator, and an error message builder, which are used by the client and server implementations to validate and build message objects.
  • Communication abstraction components: Directly communicate with the deployment-specific communication stack, such that the client and server implementations can be transparent w.r.t. the underlying communication stack.

The DTC generation components are visualized in the following figure.

Overview of the components of the DTC generation mechanism.

Figure 8 A schematic overview of the components of the DTC generation mechanism.

6.1.2 Complete (3-way) Handshake

The complete DTC generation handshake consists of the following three steps, which are described in detail in the following:

  1. The receiver initiates the DTC generation by stating its identity and the set of facts to be included in the DTC. The current version of the DTC only contains the receiver, facts (only IRIs, no checksums), and receiverCustomContent fields.
  2. Upon receipt of the initiation message, the sender compiles and signs the contract. The current version of the DTC is only missing the receiverSig field.
  3. Upon receipt of the sender-signed (partial) DTC, the receiver verifies the current state of the DTC and signs it afterward. The DTC is now complete and valid, and is sent back to the sender for mutual storage.

The following figure gives an overview of the handshake messages and computations. Note that only the differential message contents are listed, as the previously existing DTC content is carried over to the next messages. The caption includes a mapping from the message abbreviations used in the figure to the message identifiers defined in Section 6.1.4 Message Identifiers.

The 3-way contract generation handshake

Figure 9 A message diagram of the 3-way contract generation handshake, initiated by the receiver (R). Upon a request (R1=ContractRequest), the sender (S) assembles the DTC, signs it, and sends it to the receiver (S1=SenderContract). Finally, the receiver verifies and signs the DTC, and sends its own signature to the sender (R2=ReceiverContract).

In the following, we define the behavior of client and server implementations in detail.

Handshake Initiation (Client-side)

The client is responsible for initiating the DTC generation handshake. For this, an appropriate user interface (manual trigger) or interface to the data-sharing system (automatic trigger) SHOULD be implemented.

To initiate the DTC generation, the client MUST first compile a partial DTC only consisting of the receiver, the facts, and the (optional) receiverCustomContent fields. The content of the receiver and receiverCustomContent fields MUST comply with the contents specified in Section 4.3 DTC Data Structure. The content of facts MUST comply with its definition in Section 4.3 DTC Data Structure, except that the requestedID, <alg>, and serialization sub-fields MUST NOT be present for any entry.

The client then MUST use the partial DTC to build the ContractRequest message by passing the partial DTC to the message builder defined in Section 6.1.5 Message Builder, and use the outgoing message interface (see Section 6.1.9 Protocol Stack) to send it to the server.

Client-side Incoming Message Handling

Once the client implementation is called by the incoming message handler (see Section 6.1.9 Protocol Stack), the following procedure MUST be carried out.

Start with step 1. If no "continue with step x" phrase is hit, the procedure is finished.

  1. The client MUST pass the received message, together with an arbitrarily ordered list of the tuples (id,schema) of all error message identifiers (defined in Section 6.1.4 Message Identifiers) and their respective schemas (defined in Section 6.1.6 Message Schemas), to the message validator (see Section 6.1.7 Message Validator). If the validation returns None, continue with step 2. If the validation returns one of the error message identifiers, the implementation MAY behave arbitrarily (see the discussion and behavior recommendation in Section 6.1.8 Error Message Builder & Error Handling).
  2. The client MUST pass the message, along with the schema for an S1 message (defined in Section 6.1.6 Message Schemas), to the message validator (see Section 6.1.7 Message Validator). If None is returned by the message validator, the client SHOULD send an UnknownMessage error to the server according to Section 6.1.8 Error Message Builder & Error Handling. If the validator returns S1, continue with step 3.
  3. The client SHOULD check whether the received S1 message belongs to an unanswered previous ContractRequest message. The implementation of this check is not further specified, but MAY be implemented by matching HTTP requests and responses (see Section 6.1.9 Protocol Stack for a specification of the protocol stack) or by implementing a custom caching mechanism. If the check fails, the client SHOULD send an UnexpectedSenderContract error to the server according to Section 6.1.8 Error Message Builder & Error Handling. If the check succeeds, or if no check was executed, continue with step 4.

  4. The client MUST extract and parse the partial DTC contained in the content attribute of the JSON message, and verify

    • that the sender's identity (in sender) is as expected
    • that the sender's public key certificate (in sender) is valid and trusted
      Note

      This step SHOULD include checking whether the public key certificate has been issued for the authority identified by the IRI contained in the sender field. We further discuss this verification step in Section A.2 Identity Management.

    • that the sender's signature (in senderSig) is valid by verifying the signature according to Section 4.5.4 Signature Verification. The sender's public key contained in the public key certificate in sender MUST be used for the verification procedure.
    • (optional) that the fact checksums contained in facts are valid. This is dependent on a completed data transaction and an interface to the data within the client-side handshake implementation, and thus, is not mandatory to implement.
    If any of these verifications fail, the client MUST send an InvalidSenderContract error message to the server according to Section 6.1.8 Error Message Builder & Error Handling, and SHOULD consider the ContractRequest message, to which the S1 message was matched, as unanswered, such that the server can retry sending a valid matching S1 message. If all of the verifications succeeded, continue with step 5.
  5. The client MUST create a signature according to Section 4.5.3 Signature Creation using the partial DTC from the S1 message and the private key associated with the public key included in the public key certificate in the receiver field, and add it as the receiverSig field according to Section 4.3 DTC Data Structure. The client SHOULD accept the complete DTC and SHOULD forward it so a DTC storage system. Finally, the client MUST build the R2 message by passing the now-complete DTC to the message builder (see Section 6.1.5 Message Builder), and use the outgoing message interface (see Section 6.1.9 Protocol Stack) to send it to the server.
Server-side Incoming Message Handling

Once the server implementation is called by the incoming message handler (see Section 6.1.9 Protocol Stack), the following procedure MUST be carried out.

Start with step 1. If no "continue with step x" phrase is hit, the procedure is finished.

  1. The server MUST pass the received message, together with an arbitrarily ordered list of the tuples (id,schema) of all error message identifiers (defined in Section 6.1.4 Message Identifiers) and their respective schemas (defined in Section 6.1.6 Message Schemas), to the message validator (see Section 6.1.7 Message Validator). If the validation returns None, continue with step 2. If the validation returns one of the error message identifiers, the implementation MAY behave arbitrarily (see the discussion and behavior recommendation in Section 6.1.8 Error Message Builder & Error Handling).
  2. The server MUST pass the message, together with the list containing the ContractRequest and R2 message schemas (in this order, defined in Section 6.1.6 Message Schemas) to the message validator (see 6.1.7 Message Validator). If the validator returns None, the server MUST send an UnknownMessage error to the client according to Section 6.1.8 Error Message Builder & Error Handling. If the validator returns ContractRequest, continue with step 3. If the validator returns R2, continue with step 6.
  3. The server MUST parse the partial DTC in the contract attribute of the JSON message. Then, the server MAY verify that the client is authorized to request the DTC for the facts contained in the facts field.
    Note

    Such an access-control mechanism is not specified, but could be implemented on a lower layer (e.g., using the HTTP Authorization header). Therefore, error handling for access control should also be implemented on a lower layer.

    Subsequently, the server compiles the DTC. Therefore, it MUST carry out the following steps on the received partial DTC in any order:

    Continue with step 4.

  4. The server creates a signature according to Section 4.5.3 Signature Creation for the compiled DTC and the private key associated with the public key included in the public key certificate in the sender field. The server then adds it as the senderSig field according to Section 4.3 DTC Data Structure. Continue with step 5.
  5. The server MUST build the S2 message by passing the compiled (partial) DTC to the message builder (see Section 6.1.5 Message Builder), and MUST then use the outgoing message interface (see Section 6.1.9 Protocol Stack) to send the resulting message to the client.
  6. The server MUST parse the DTC contained in the contract field of the JSON message. Then, the server MUST verify that its own public key certificate is contained in the sender field. If not, the server MUST send a BogusSenderCert error to the client according to Section 6.1.8 Error Message Builder & Error Handling.
    Note

    This step prevents the client from simply replacing the sender's public key certificate with a bogus certificate, for which it controls the private key, and can thus create a signature (and thus a valid DTC) independent of the sender. While such an attack would not lead to a valid DTC issued by the sender, it would lead to an invaluable DTC, which is not recognized by the sender by simply verifying the DTC using the procedure specified in Section 6.2 DTC Verification.

    If the public key certificate is correct, continue with step 7.
  7. The server MUST verify
    • that the receiver's identity (in receiver) is as expected
    • that the receiver's public key certificate (in receiver) is valid and trusted
      Note

      This step SHOULD include checking whether the public key certificate has been issued for the authority identified by the IRI contained in the receiver field. We further discuss this verification step in Section A.2 Identity Management.

    • that the receiver's signature (in receiverSig is valid by verifying the signature according to Section 4.5.4 Signature Verification. The receiver's public key contained in the public key certificate in receiver MUST be used for the verification procedure.
    If any of these verifications fail, the server MUST send an InvalidReceiverContract error message to the client according to 6.1.8 Error Message Builder & Error Handling. Otherwise, the server SHOULD accept the DTC and SHOULD forward it to a DTC storage system.

6.1.3 Abbreviated (2-way) Handshake

The abbreviated handshake assumes that the receiver has full access to the underlying data of the DTC, i.e., that the data transmission is completed. Further, it assumes that the receiver has access to the sender's identity and public certificate, i.e., the contents of the sender field according to Section 4.3 DTC Data Structure.

If these two assumptions hold, the receiver is able to compile the DTC except for the sender's signature. In this case, only two messages are necessary to establish a valid DTC.

Note that if the senderCustomContent is to be used, its content MUST be pre-shared before the receiver initiates the handshake, such that the client has access to it when initially compiling the DTC.

The following figure gives an overview of the handshake messages and computations. Note that only the differential message contents are listed, as the previously existing DTC content is carried over to the next messages. The caption includes a mapping from the message abbreviations used in the figure to the message identifiers defined in Section 6.1.4 Message Identifiers.

A shortened 2-way handshake dependent on a completed data transmission is shown below:

The transmission-dependent 2-way contract generation handshake

Figure 10 A message diagram of the 2-way contract generation handshake, initiated by the receiver (R). The receiver compiles the complete DTC, and the sender (S) verifies and signs it afterward. Message abbreviations: R1'=AbbrevContractRequest, S1'=AbbrevContract.

In the following, we define the behavior of client and server implementations in detail.

Handshake initiation (Client-side)

The client is responsible for initiating the DTC generation handshake. For this, an appropriate user interface (manual trigger) or interface to the data-sharing system (automatic trigger) SHOULD be implemented.

  1. To initiate the DTC generation, the client MUST first compile a partial DTC. For this, the following steps MUST be carried out in any order:
    • The client adds the receiver field with its own information, such that the content complies with Section 4.3 DTC Data Structure.
    • The client adds the sender field with the sender's information, such that the content complies with Section 4.3 DTC Data Structure.
      Note

      As mentioned above, the content of the sender field needs to be pre-shared between sender and receiver for the abbreviated handshake.

    • Based on the set of IRIs of the underlying data transmission, the client compiles the facts field in compliance with Section 4.3 DTC Data Structure. For this, the client looks up or computes the checksums for the facts identified by the IRIs of the data transmission. It then adds each checksum to the <alg> sub-field of the respective facts entry in accordance with Section 4.3 DTC Data Structure. As specified in Section 4.3 DTC Data Structure, the checksum is associated with a specific serialization of the fact. The client MUST add the serialization identifier to the serialization sub-field of each entry of facts according to Section 4.3 DTC Data Structure. The requestedID subfield SHOULD NOT be present for any entry of facts.
      Note

      Note that in the abbreviated handshake, the sender cannot update the entries of factID, as the receiver's signature already exists in the first message addressed to the sender. Instead, an IRI negotiation, as discussed in Section 4.3 DTC Data Structure SHOULD be implemented together with the data transmission, as this has to be completed before the handshake if using the abbreviated handshake version.

    • The client creates a timestamp of its current time and adds it to the timestamp field according to Section 4.3 DTC Data Structure.
    • The client assigns a base IRI to the baseIRI field according to Section 4.3 DTC Data Structure, which can be used to uniquely identify the created DTC. This IRI MAY be created by the receiver itself, or negotiated or created by the sender during the transmission of the data subject to the DTC.
    • (Optional) The client adds content to the receiverCustomContent and senderCustomContent fields according to 4.3 DTC Data Structure.
      Note

      As mentioned above, the content of the senderCustomContent field has to be pre-shared before the abbreviated handshake.

    Continue with step 2.

  2. The client MUST create a signature according to Section 4.5.3 Signature Creation for the compiled DTC and the private key associated with the public key included in the public key certificate in the receiver field. The client then MUST add it as the receiverSig field according to Section 4.3 DTC Data Structure. Continue with step 3.

  3. The client then MUST use the partial DTC to build the AbbrevContractRequest message by passing the partial DTC to the message builder defined in Section 6.1.5 Message Builder, and pass it to the outgoing message interface (see Section 6.1.9 Protocol Stack).

Client-side Incoming Message Handling

Once the client implementation is called by the incoming message handler (see Section 6.1.9 Protocol Stack), the following procedure MUST be carried out.

Start with step 1. If no "continue with step x" phrase is hit, the procedure is finished.

  1. The client MUST pass the received message, together with an arbitrarily ordered list of the tuples (id,schema) of all error message identifiers (defined in Section 6.1.4 Message Identifiers) and their respective schemas (defined in Section 6.1.6 Message Schemas), to the message validator (see Section 6.1.7 Message Validator). If the validation returns None, continue with step 2. If the validation returns one of the error message identifiers, the implementation MAY behave arbitrarily (see the discussion and behavior recommendation in Section 6.1.8 Error Message Builder & Error Handling).
  2. The client MUST pass the message, along with the schema for an AbbrevContract message (defined in Section 6.1.6 Message Schemas), to the message validator (see Section 6.1.7 Message Validator). If None is returned by the message validator, the client SHOULD send an UnknownMessage error to the server according to Section 6.1.8 Error Message Builder & Error Handling. If the validator returns S1, continue with step 3.
  3. The client MUST parse the DTC contained in the contract field of the JSON message. Then, the client MUST verify that its own public key certificate is contained in the receiver field. If not, the client MUST send a BogusReceiverCert error to the server according to Section 6.1.8 Error Message Builder & Error Handling.
    Note

    This step prevents the server from simply replacing the receiver's public key certificate with a bogus certificate, for which it controls the private key, and can thus create a signature (and thus a valid DTC) independent of the receiver. While such an attack would not lead to a valid DTC issued by the receiver, it would lead to an invaluable DTC, which is not recognized by the receiver by simply verifying the DTC using the procedure specified in Section 6.2 DTC Verification.

    If the public key certificate is correct, continue with step 4.
  4. The client MUST verify
    • that the sender's identity (in sender) is as expected
    • that the sender's public key certificate (in sender) is valid and trusted
      Note

      This step SHOULD include checking whether the public key certificate has been issued for the authority identified by the IRI contained in the sender field. We further discuss this verification step in Section A.2 Identity Management.

    • that the sender's signature (in senderSig is valid by verifying the signature according to Section 4.5.4 Signature Verification. The sender's public key contained in the public key certificate in sender MUST be used for the verification procedure.
    If any of these verifications fail, the client MUST send a InvalidAbbrevContract error message to the server according to 6.1.8 Error Message Builder & Error Handling. Otherwise, the client SHOULD accept the DTC and SHOULD forward it to a DTC storage system.
Server-side Incoming Message Handling

Once the server implementation is called by the incoming message handler (see Section 6.1.9 Protocol Stack), the following procedure MUST be carried out.

Start with step 1. If no "continue with step x" phrase is hit, the procedure is finished.

  1. The server MUST pass the received message, together with an arbitrarily ordered list of the tuples (id,schema) of all error message identifiers (defined in Section 6.1.4 Message Identifiers) and their respective schemas (defined in Section 6.1.6 Message Schemas), to the message validator (see Section 6.1.7 Message Validator). If the validation returns None, continue with step 2. If the validation returns one of the error message identifiers, the implementation MAY behave arbitrarily (see the discussion and behavior recommendation in Section 6.1.8 Error Message Builder & Error Handling).
  2. The server MUST pass the message, together with the AbbrevContractRequest schema (see Section 6.1.6 Message Schemas) to the message validator (see 6.1.7 Message Validator). If the validator returns None, the server MUST send an UnknownMessage error to the client according to Section 6.1.8 Error Message Builder & Error Handling. If the validator returns AbbrevContractRequest, continue with step 3.

  3. The server MUST extract and parse the partial DTC contained in the content attribute of the JSON message, and verify

    • that the receiver's identity (in receiver) is as expected
    • that the receiver's public key certificate (in receiver) is valid and trusted
      Note

      This step SHOULD include checking whether the public key certificate is issues for the authority identified by the IRI contained in the receiver field. We further discuss this verification step in Section A.2 Identity Management.

    • that the receiver's signature (in receiverSig) is valid by verifying the signature according to Section 4.5.4 Signature Verification. The receiver's public key contained in the public key certificate in receiver MUST be used for the verification procedure.
    • that the fact checksums contained in facts are valid. This verification step can be done by re-computing or looking up the fact checksums given the serialization identified by the serialization field.
      Note

      In contrast to the 3-way handshake (see Section 6.1.2 Complete (3-way) Handshake), this step is not optional, as the 2-way handshake requires a previously completed data transmission. Thus, making this step mandatory does not constrain the application of the procedure.

    If any of these verifications fail, the server MUST send an InvalidAbbrevContractRequest error message to the client according to Section 6.1.8 Error Message Builder & Error Handling. If all of the verifications succeeded, continue with step 5.
  4. The server MUST verify that its own identity and public key certificate are correctly included in the sender field.
    Note

    This information has to be pre-shared between sender and receiver for the abbreviated handshake. If this information is not correct, the signature in step 6 cannot be created with the matching private key.

    If not, the server MUST send a BogusSenderCert error message to the client according to Section 6.1.8 Error Message Builder & Error Handling. If the information is correct, continue with step 6.
  5. The server MUST create a signature according to Section 4.5.3 Signature Creation using the partial DTC from the AbbrevContractRequest message and the private key associated with the public key included in the public key certificate in the sender field, and add it as the senderSig field according to Section 4.3 DTC Data Structure. The server SHOULD accept the complete DTC and SHOULD forward it so a DTC storage system. Finally, the server MUST build the AbbrevContract message by passing the now-complete DTC to the message builder (see Section 6.1.5 Message Builder), and use the outgoing message interface (see Section 6.1.9 Protocol Stack) to send it to the client.

6.1.4 Message Identifiers

The defined message identifiers are partitioned into non-error message identifiers and error message identifiers.

We do not further specify the implementation of the message identifiers. They could, for example, be implemented using constant string values, or with an enum-like structure.

We define the following non-error message identifiers:

We define the following error message identifiers:

  • UnknownMessage: Indicates that the message could not be validated against any message schema.
  • UnexpectedSenderContract: Indicates that an S1 message was received by the client without expecting it (see Section 6.1.2 Complete (3-way) Handshake).
  • InvalidSenderContract: Indicates that the verification of an S1 message failed (see Section 6.1.2 Complete (3-way) Handshake).
  • BogusSenderCert: Indicates that the public key certificate contained in the sender field of an R2 message did not equal the sender's actual certificate (see Section 6.1.2 Complete (3-way) Handshake).
  • InvalidReceiverContract: Indicates that the verification of the previously transmitted ReceiverContract message on the server side failed.
  • BogusReceiverCert: Indicates that the receiver's certificate, as included in the receiver field of the partial DTC within the previously transmitted SenderContract message, was not the correct certificate of the handshake client.
  • InvalidAbbrevContract: Indicates that the client-side verification of the previously transmitted AbbrevContract message failed.
  • InvalidAbbrevContractRequest: Indicates that the server-side verification of the previously transmitted AbbrevContractRequest message failed.

6.1.5 Message Builder

The message builder is used to build JSON messages to be transmitted according to Section 6.1.9 Protocol Stack. Its behavior is the same for client and server implementations, and it provides an interface for the implementation of both server and client behavior, as specified in Sections 6.1.2 Complete (3-way) Handshake and 6.1.3 Abbreviated (2-way) Handshake.

If an implementation implements the client or server part of the generation handshake, it MUST also implement the message builder.

The message builder MUST implement the following functionality.

The following is an informative example of an S1 message (see Section 6.1.2 Complete (3-way) Handshake) as generated by the message builder.

Example 7: Example handshake message (SenderContract) 
{
  "messageType": "SenderContract",
  "contract": {
    "baseIRI": "https://example.com/contracts/2021-09-24/134",
    "sender": {
      "type": "X509",
      "encoding": "base64",
      "cert": "MIIEkTCCAnmgAwIBAgIUTpTAugWv4ZYQX9nk2zETfVcMi38wDQYJKoZIhvcNAQELBQAwTDELMAkGA1UEBhMCREUxEzARBgNVBAgMClNvbWUtU3RhdGUxEzARBgNVBAoMCkV4YW1wbGUgQ0ExEzARBgNVBAMMCkV4YW1wbGUgQ0EwHhcNMjEwNDE1MjExMTExWhcNMjIwNDE1MjExMTExWjAzMR0wGwYDVQQKDBRFeGFtcGxlIGNoYWluIGNlcnQgMTESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvw8C6sqLUVSOwFPbZsqS/1cL/+7aaaxVPwXs7TjPVombwNLyJW8yPyyQLbsTN5evVCpNdzciYc9Nhh77AYrqCiOsZBb7hu/PMqNqDvU2FAHeTH9KZ1PSpsOdgzG4i9widL6FBKGrxvlyj0G5ztQoGtymJFdmQ8K/ZN2W5Bi27H24UgITO+mX5MGmzFfyib7bDnvNqZUMJEgpSGt+jUf/7pMtuQqusrE1bfg5vvCbHIPHx2KXqzQEjNiioDafzKjIY2NSakis1AZe+J46o/Za0L8TUMXPvO1nSX4VMm9w5Qqf8auKdlUnT7fVqGKxQvPgX/JM/ksduZqZdTE1giWDgQIDAQABo4GDMIGAMB0GA1UdDgQWBBQtTnbTodwlQnP0QXA2VRv6DBWgzzAfBgNVHSMEGDAWgBR+/85DLJ8v0EP1y6kv/I9XPsHQ5TAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwEwDQYJKoZIhvcNAQELBQADggIBAG47hxcjEY6kXojCadK15iW5t6P2p2NCfXpymeRuVaHiI7hhMwQEPymGqXZe0MKUKaRxb9BssG9UvndJw7PWdLx55Y498dgEVXWp7UWUg+VmLxE0wrS+7odJ6ZwsSTPhlgQVF3y9SOP18UX1Iy+ipkdPVbeiQB2QJOYLdxj3h26a/BevyWJU7jTbZO9fNX3FlopyQbB64QPJKJyQiYrT1td7lOcreyBJUS2e5p+hifW/ukxHQ9QtfN+mE/MlnUSHar6LgXPX3AoiVKc14L5E7jRHLDCvFWO1PfVCsS6RWIKdoWsEUytDnMYLHb2TmMJWQf8S69BLyqgEhKXNS9hZceGr32jM9O6TepYKZNH5A1QLjZcuHHKUAzXMjM9loNLra/VGcqrMTdZYautGl8EdEURqE063qDd+Hsp3Vqw0iALQHcbEb6R1b2o5dIrczo+PINTSvnFv+4GyqznXEYjcueLrR/R6kE9GNOiPUxpont+0s1JCAKPaaZk97Z09ldtD47rPQLQgWopDadVOm3Gu9+ef7uqqpJw9+q384mqgw4P1Yws6aVkXLdvh8MCXcMEYi2AeQVCCZv2CjAh8CZQC+0P2JtkhWlCxPoSDk4jbm6koCxcpL3CRcc5LtTTrev5+Mi0oDMiLzx09GNls3SQzdKdP9PM+Y7E7y4Xi2LW3FtoG",
      "authID": "http://example.com/sender"
    },
    "receiver": {
      "type": "X509",
      "encoding": "base64",
      "cert": "MIIEkTCCAnmgAwIBAgIUTpTAugWv4ZYQX9nk2zETfVcMi4AwDQYJKoZIhvcNAQELBQAwTDELMAkGA1UEBhMCREUxEzARBgNVBAgMClNvbWUtU3RhdGUxEzARBgNVBAoMCkV4YW1wbGUgQ0ExEzARBgNVBAMMCkV4YW1wbGUgQ0EwHhcNMjEwNDE1MjExNDM1WhcNMjIwNDE1MjExNDM1WjAzMR0wGwYDVQQKDBRFeGFtcGxlIGNoYWluIGNlcnQgMTESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuKe4H5GwuaKS02s6oAnQF0e30TLyB3joT5GNzwa94WXuLjU8SWKqOjLQyIN2ZBtZW1jNI3By6nsPoU3t181SBStFI25JZ8PUvJ9/Skf/adRmrtXHX8MYRBqN4d1JIRdOoLxwq+bI0UIyMmMNMTjvhnWwTx4FkXwup5fna9FFBbtOGP+7vMVl98L2/bDMJwwLdnzUs0CKLyqDRx0XWAnp6R6CN9YDeMgpdDviMkBfeY74AJ084v6pWnx+K0PlUuQAkiuPvcRsDxgjHRO18rq4wA6Dxh6My7Xh/uHFzb5cmLT7C7kfr+WN26va8IRGCF8NWdOYQ0HSo/vbY/eIOB/G0wIDAQABo4GDMIGAMB0GA1UdDgQWBBSmlyw0Ht9gF3rnI42Us1dK9+jZ/DAfBgNVHSMEGDAWgBR+/85DLJ8v0EP1y6kv/I9XPsHQ5TAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwEwDQYJKoZIhvcNAQELBQADggIBABMLMfSOAwk34LEK9L/A1qtHTJPQ2BF3XjnbswINNao0oOI3PSWKU0weWYlITH29hgyzrwO8A9ifaOFPtsRxe9/UNv6RNqwObLpxF+f2U3ulu2hTzd7l/ZXUGYaBUHLL3Cu1JlZWMRoTUBUHAvkwnQlUkQLJZ7A+N9y+FfV5apIMTwPA+C2lwiVtEd3Hje5Z9lUmjwiARRnsliRuCm2ZY0IHvneQN7NnOFCFFQQnu/7wMEywNWR3NMtj5AcMugs56OqcAglwq+HqYNCUkelt1/I7A/NwitaPEYu/1TDjQBckR6nbtJwHKFx2M9heB+E5iMI65r+ae01jBr+r7tes6UdEz7SCF3xHks3ubKfRQykZzTZ7ixeHYG5XjaUSSk8EDuBCdZOJ/AUAA+Rar/UPODUd1YQUZDUqs0MvB9zXQYBtEhwii75pCmkFBpZewo6xyktdP3964q7MZPZQZTZimh02CxcWdXZj6JkoL6ihuM36UciS9rXUgIGGdJcbhC5mP/PqRYsAzipOvQiRL7mGRB9L8H0Wt08yl3H0KFwGcgasML8tOOkf+4MsGIHJZaJ20cVfdWm1StOtLN1Bn+gAppq8nlvDgPiQ3NxSsvY+Qpb0WSVWknc1VyOPKexKaM20/alMv/fykVhVmmAcNVshIMAuKV5TnhqeZyg8L02pVAHL",
      "authID": "http://example.com/receiver"
    },
    "senderSig": {
      "type": "urn:oid:1.2.840.113549.1.1.10",
      "encoding": "base64",
      "sig": "S82Al/YgpfjywjagQ03tjr8WT2oiMSkuYGA5hoXL/LCZHJhR4UGuXyQe1lJ6+yDRiN8FbKcp6ZrClb645rKpIK9UP/Y50wOo/vXCdeUGRqWj4NduoJsBKAP9O4QfQQkT9POHwcbYDsbvEGm3M7fh7mrOn6PzQQgq8vNGayVP5VmFLofxhArc2cy7/TthDl5sBwngpIokHUGOIE+RXasifJ/KS+DALU2s51EZzP2NuTbOvC2328UD5yhvHTopwqn3OrMWbKjF8UUDFjQHYx383hrK3VPjqfrMMNT3OHiJB6t9pJwZ3lmD3PV0Axp6k1XV+oxckBaYN7dCNneQn+zkcw=="
    },
    "facts": [
      {
        "factID": "http://example.com/facts/fact1",
        "sha256": "5fc62b0e99a143ff2b99b56a6953f07e96f52023aa3739bba3fec1194292f48e",
        "serialization": "string"
      },
      {
        "factID": "http://example.com/facts/fact2",
        "sha256": "828bbc97b5b866992dc8bc532265e3094bc9e17cce05e16d90844d2160ad99cf",
        "serialization": "string"
      },
      {
        "factID": "http://example.com/facts/fact3",
        "sha256": "c646cfa0feda9af766e6eca97f8578f3eb2b126d2349ea7ce1fd2d3b3fe2d456",
        "serialization": "string"
      },
      {
        "factID": "http://example.com/facts/fact4",
        "sha256": "5845f61bccd9c5631dee29f9e87830b11eb5b531081a8888db42e80e2f153fc0",
        "serialization": "string"
      }
    ],
    "timestamp": "2021-04-15T21:50:29.940Z",
    "senderCustomContent": {
      "authMethod": "PublicKey",
      "authSuccessful": true,
      "authUserId": "user123456"
    },
    "receiverCustomContent": {
      "dbStorageId": "StorageCluster5"
    }
  }
}

6.1.6 Message Schemas

We define one message schema per message identifier.

For this, we build upon the same specification of JSON Schema [JSON-SCHEMA][JSON-SCHEMA-VALIDATION] as in Section 4.4.1 JSON.

The message schemas can be obtained through the following links:

  • Abstract (generic) schemas:
  • Non-error message schemas:
  • Error message schemas:

6.1.7 Message Validator

The message validator is used to validate a JSON message against an ordered list of schemas. It provides an interface to the client and server implementations specified in Sections 6.1.2 Complete (3-way) Handshake and 6.1.3 Abbreviated (2-way) Handshake.

Any implementation implementing the client or server part of the generation handshake MUST also implement the message validator.

The behavior of the message validator MUST be implemented as follows:

  • Input: A JSON object (referred to as msg) and a list of tuples (id_0,schema_0),...,(id_n-1,schema_n-1), where for i=0,...,n-1, id_i is a message identifier, and schema_i is the according JSON schema according to Section 6.1.6 Message Schemas.
  • Behavior: The validator tries to validate msg against the JSON Schemas, starting with schema_0, applying a first-match policy. That is, for the first tuple (id_i,schema_i), such that msg matches schema_i, the message validator terminates and returns id_i to the caller. If none of the schemas match msg, the validator returns None (which MAY be represented as a string or as a language-internal representation of a null value).

6.1.8 Error Message Builder & Error Handling

We define a special message builder for error message identifiers, which provides an interface to the client and server implementations in Sections 6.1.2 Complete (3-way) Handshake and 6.1.3 Abbreviated (2-way) Handshake.

Any implementation implementing the client or server part of the generation handshake MUST also implement the error message builder.

The error message builder MUST be implemented with the following functionality:

  • Input: An error message identifier
  • Behavior: The error message builder MUST carry out the following steps:
    1. Create an empty JSON object ({}) referred to as res.
    2. Assign the error message identifier as a string to the messageType attribute of res.
    3. Assign an implementation-dependent error message as a string to the errorMessage attribute of res.
      Note

      This field can be used to carry further meta-information about the error occurrence, but is not further specified.

    4. Return res to the caller.

The following is an informative example of an error message with the UnknownMessage message identifier as generated by the error message builder.

Example 8: Example error message (UnknownMessage) 
{
  "messageType": "UnknownMessage",
  "errorMessage": "Unrecognized message format!"
}

Note that we do not specify how error messages are handled. However, we recommend that error messages SHOULD NOT simply be ignored, as this behavior MAY lead to invalid (and thus invaluable) DTCs. An implementation SHOULD instead decide to either repeat the handshake step which caused the error, or abort the generation handshake, such that a new handshake can be initiated.

6.1.9 Protocol Stack

The JSON messages are either transmitted directly on top of TCP [RFC793], via TLS directly on top of TCP, or wrapped into HTTP [HTTP11] requests, optionally over TLS (HTTPS) [HTTP-TLS].

In order for the lower protocol stack to be transparent for the client and server implementation, we define an additional abstraction layer. This abstraction layer MUST implement two components:

  • An outgoing message interface, which can be called using JSON objects to send messages.
  • An incoming message handler, which forwards valid JSON messages to the client or server implementation.

Depending on the protocol stack, these components are implemented differently, as we specify in the following.

If only TCP is used (no TLS or HTTP on top), the server MUST provide an open port that can be contacted by the client. Upon contract handshake initiation, the client MUST open a connection to the server, such that both the client and the server have an open bi-directional TCP socket. The two abstraction components MUST be implemented as follows for client and server:

  • Outgoing message interface: Whenever called with a valid JSON object, the implementation MUST serialize the JSON as a string in UTF-8 encoding [RFC3629] and send it through the TCP socket with a trailing newline character.
  • Incoming message handler: Whenever the incoming data can be aggregated to a valid JSON object, it MUST be parsed as a JSON object, and the associated client or server implementation MUST be called with said JSON object.

If TLS is used on top of TCP without HTTP, the server MUST provide an open TCP port that can be contacted by the client, but only accepts TLS traffic. Upon contract handshake initiation, the client MUST open a connection to the server and carry out a TLS handshake, such that a TLS-protected tunnel is established. Then, the abstraction components (i.e., the outgoing message interface and the incoming message handler) MUST be implemented as in the no-TLS case, but using the TLS tunnel instead.

If HTTP or HTTPS is used, the server MUST provide an HTTP(S) server to which the client can connect. Upon contract handshake initiation, the client MUST open a TCP connection (without TLS) or create a TLS tunnel through a TLS handshake (with TLS), through which HTTP traffic can be sent. For the abstraction components, we differentiate between client and sender.

The client-side abstraction components for HTTP(S) MUST be implemented as follows:

  • Outgoing message interface: Whenever called with a valid JSON object, the implementation MUST create and send an HTTP POST request through the established tunnel, containing the serialized JSON object as its body, and MUST set the Content-Type header to application/json. It MUST then install the incoming message handler, such that it gets called with the response to the request.
  • Incoming message handler: Is called with the response of a previously executed POST request. If the response Content-Type header does not indicate the application/json type, the implementation SHOULD initiate a retransmission of the previous message by either sending an UnknownMessage error message (see Sections 6.1.4 Message Identifiers and 6.1.8 Error Message Builder & Error Handling), or by retransmitting the previous message, using the outgoing message interface.
    Note

    Because the client is not simply able to provide feedback in the form of an HTTP status code, as it only performs requests, we leave error handling to the implementation. We refer to the general discussion of ReShare's approach on error handling in Section 6.1.8 Error Message Builder & Error Handling.

The server-side abstraction components for HTTP(S) MUST be implemented as follows:

  • Outgoing message interface: MUST be called with the context of a previously received incoming HTTP POST request. The implementation MUST create and send a response to the request in the context with which the outgoing message interface was called. The body of the response MUST be set to the JSON object, with which the outgoing message interface was called. The status code of a message with a non-error message identifier (see Section 6.1.4 Message Identifiers) MUST be set to 200. The status code of a message with an error message identifier (see Section 6.1.4 Message Identifiers) SHOULD be set to one of the acceptable status codes from the table below, depending on the message identifier. The Content-Type header MUST be set to application/json.
    Note

    A 200 status code is considered acceptable for every defined error message, as these higher-layer errors are already uniquely identified through their respective message schemas. Thus, using a 200 status code does not hinder an implementation's functionality, but we consider the usage of proper error status codes good practice.

  • Incoming message handler: MUST be called whenever an HTTP request is received from the client. If the Content-Type header of the request does not indicate the application/json type, the incoming message handler MUST respond with an empty response with a 406 status code, without calling the server-side implementation of the handshake. Else, the body of the request is parsed as a JSON object, and the server-side implementation of the handshake (defined in Sections 6.1.2 Complete (3-way) Handshake and 6.1.3 Abbreviated (2-way) Handshake) is called with the parsed JSON object. Additionally, the incoming message handler SHOULD store the context of the request, such that it can be passed to the outgoing message interface once it is called by the server implementation.

We define the following acceptable status codes for error messages based on the error message identifiers (see Section 6.1.4 Message Identifiers):

Note

We only define status codes for error messages which can be sent by the server during the handshake, as a client only sends HTTP requests, which do not carry a status code.

Message identifier Recommended HTTP Status Codes
UnknownMessage 200, 400
BogusSenderCert 200, 422
InvalidReceiverContract 200, 422
InvalidAbbrevContractRequest 200, 422

6.2 DTC Verification

DTC verification can be executed fully locally, as the DTC itself contains all information necessary for its verification. This self-containing property of DTCs allows for efficient and unambiguous verification without the need to directly communicate with the involved parties.

To verify a DTC and the resources for which it contains checksums, access to the following information is required:

  • The DTC itself
  • The resource(s) to be verified
  • A list of trusted root CAs (and their public keys)

The verification steps immediately emerge from the design of the trust chain of DTCs. In order to verify a syntactically valid DTC, one MUST execute the following verification steps in any order:

  • Verify the public key certificates by verifying the certificate chains in sender and receiver using a pre-installed trusted root CA's public key as the trust anchor.
    Note

    This step SHOULD include checking whether the public key certificates are issued for the respective authorities identified by the IRIs contained in the sender and receiver fields. We further discuss this verification step in Section A.2 Identity Management.

  • Verify the DTC signatures in senderSig and receiverSig using the public keys contained in the certificates in the sender and receiver fields and the signature verification process specified in Section 4.5.4 Signature Verification.
  • Verify the fact checksums using the original data. For this, the facts need to be serialized according to the serialization format identified in the serialization field. Subsequently, the checksums need to be re-computed given the serialized facts, and compared to the checksum included in the DTC.
    Note

    We do not further specify this verification step, as the process of serializing facts of different types is deemed out-of-scope for this document.

If any of the verification steps fail, the verification mechanism MUST terminate with a negative result.

Depending on the use case, it MAY be desirable to extend these verification steps, e.g., by verifying that the owner of the certificates in the receiver and sender fields are as expected. While such extensions are not part of this verification mechanism, we advise implementors to carefully review that no unverified assumptions are made about the contents of a DTC.

ReShare with its specification of DTCs, the ontology, and the DTC creation and verification process, enables users to achieve data trustworthiness and reliability in a scalable manner. In this context, the central aspect not covered before by Web technology, but essential in the context of data-driven or industrial data sharing settings is the accountable involvement of both parties in the data transmission process, which is implemented using bilateral signatures in ReShare.

A. Considerations

This section is non-normative.

In the following section, we briefly elaborate on some of the design decisions and considerations w.r.t. ReShare.

A.1 Relation to Other W3C Documents

This section is non-normative.

In recent years, both W3C itself and W3C Community Groups have been quite active in the field of expressing cryptographically-backed claims or statements about data. To the best of our knowledge, the following three documents are especially noteworthy:

ReShare was developed largely in parallel to these developments throughout years 2020 until early 2021, and the major parts of this document were created mostly from April to the end of 2021. ReShare was designed with backward-compatability with the existing Web infrastructure in mind and as such makes use of established standards at the time of design as a largely self-contained solution. That being said, future work, e.g., towards standardization, may potentially also make use of these related efforts. A potential role of Decentralized Identifiers in ReShare is discussed in Section A.2 Identity Management. In the following, we focus on Verifiable Credentials and the Data Integrity specification.

Verifiable Credentials

Verifiable Credentials (VC) [VC-DATA-MODEL] provide a cryptographically-secure and machine-readable approach to expressing credentials. An overview of conceivable use cases can be found in [VC-USE-CASES], and include a variety of claims in the areas of education, finance, healthcare and more.

The data model of a VC is defined independently from its representation. However, the specification defines both a JSON, and a JSON-LD representation, thus taking a very similar approach to ReShare.

As VCs represent very general means of expressing, presenting, and proving a set of claims in the form of credentials, it is conceivable that VCs could be used as a framework for an implementation of DTCs, together with a DTC generation mechanism similar to the one we currently specify.

However, the following two considerations have lead us to the decision of refraining from the use of VCs in ReShare as of now:

  1. While a credential is defined as essentially consisting of metadata, one ore more claims, and one or more proofs, which is applicable to the model of a DTC, the use cases in [VC-USE-CASES] are very much centered around use cases of a single individual in everyday life.

    This makes us wonder whether applicability in typical use-cases of inter-organizational data sharing of ReShare is given, as such scenarios might not have been considered in the design of the VC specification.

  2. Probably the most essential design choice defining the paradigm of DTCs lies in the idea of bilateral on-demand signatures, as we describe in-detail in Section 4.1 Mutual Commitment through Bilateral Signatures.

    In the VC specification, while multiple proofs within a single VC are supported, a VC always has one issuer by design (see 4.5 Issuer), which is incompatible with the paradigm of a DTC having two equally-involved parties, the sender and the receiver, whose signatures are both required for a DTC to be considered valid.

Of course, depending on future developments, the suitability of VC as a framework for DTCs should be re-assessed if a new version of ReShare is to be designed in future.

For example, as we discuss below, signature sets, as used in contracts, are included in the Data Integrity [DATA-INTEGRITY] specification, and could find their way into a future version of the VC specification, possibly expanding the set of use cases to those of DTCs.

Data Integrity

The Data Integrity specification [DATA-INTEGRITY] strives to provide data models and representations of cryptographic proofs, such as signatures and integrity checksums, within the context of Linked Data.

Such mechanisms clearly find a promising use case in DTCs, as DTCs include integrity checksums of the data subject to the underlying data transmission (see facts), as well as digital signatures of both DTC parties (see sender and receiver). Even proof sets are already included in the Data Integrity specification (see 3.1 Proof Sets), for which we deem DTCs a very interesting use case.

Naturally, ReShare would greatly profit from employing a standardized mechanism of including and structuring these cryptographic proofs in DTCs. Therefore, we consider the Data Integrity specification as a promising mechanism to be used in a future version of ReShare.

As of now, ReShare uses a custom implementation of embedding signatures and checksums in DTCs, which has to be attributed to the temporal overlap of ReShare and the Data Integrity specification, as the Data Integrity specification is in a relatively early stage of standardization.

A.3 DTC Generation: Two Handshake Versions

This section is non-normative.

We have introduced the shortened 2-way handshake as a way to reduce the communication overhead in an application scenario with high communication latencies. However, this shortened version requires that the transmission of the data which is signed in a given DTC is completed before DTC generation. With the complete 3-way handshake, the DTC generation is completely independent of the underlying data transmission, except that the receiver has to know which resources are transmitted.

The sequentiality arising from a dependency on the data transmission has practical disadvantages in many cases, such as an increased management and implementation overhead by more closely integrating the data transmission process into the DTC generation mechanism. Given the context system, configuration or implementation changes in the data transmission backend might be necessary to implement the necessary pre-sharing to allow for a short handshake.

Therefore, we consider the complete 3-way handshake the default handshake, but still specify the shortened 2-way handshake for special high-latency environments. Without a strong argument against it, we advise to use the 3-way handshake.

B. Acknowledgements

The authors are grateful for the supervision of Prof. Dr. Stefan Decker and Prof. Dr.-Ing. Klaus Wehrle.

The authors would like to thank Silvio Peroni for developing LODE, a Live OWL Documentation Environment, which is used for representing the Cross Referencing Section of this document and Daniel Garijo for developing Widoco, the program used to create the template used in this documentation.

The authors would further like to thank the reviewers of the ESWC paper [ReShare] for providing insightful and constructive feedback on the topic.

Funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under Germany's Excellence Strategy -- EXC-2023 Internet of Production -- 390621612.

C. List of Figures

D. References

D.1 Normative references

[FIPS-180-4]
FIPS PUB 180-4: Secure Hash Standard (SHS). U.S. Department of Commerce/National Institute of Standards and Technology. August 2015. National Standard. URL: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf
[HTTP-TLS]
HTTP Over TLS. E. Rescorla. IETF. May 2000. Informational. URL: https://httpwg.org/specs/rfc2818.html
[HTTP11]
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
[ISO8601]
Representation of dates and times. ISO 8601:2004.. International Organization for Standardization (ISO). 2004. ISO 8601:2004. URL: http://www.iso.org/iso/catalogue_detail?csnumber=40874
[JSON-LD11]
JSON-LD 1.1. Gregg Kellogg; Pierre-Antoine Champin; Dave Longley. W3C. 16 July 2020. W3C Recommendation. URL: https://www.w3.org/TR/json-ld11/
[JSON-LD11-API]
JSON-LD 1.1 Processing Algorithms and API. Gregg Kellogg; Dave Longley; Pierre-Antoine Champin. W3C. 16 July 2020. W3C Recommendation. URL: https://www.w3.org/TR/json-ld11-api/
[JSON-SCHEMA]
JSON Schema: A Media Type for Describing JSON Documents. Austin Wright; Henry Andrews; Ben Hutton; Greg Dennis. Internet Engineering Task Force (IETF). 8 December 2020. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema
[JSON-SCHEMA-VALIDATION]
JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Austin Wright; Henry Andrews; Ben Hutton. Internet Engineering Task Force (IETF). 11 June 2021. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation
[N-Quads]
RDF 1.1 N-Quads. Gavin Carothers. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/n-quads/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC2315]
PKCS #7: Cryptographic Message Syntax Version 1.5. B. Kaliski. IETF. March 1998. Informational. URL: https://www.rfc-editor.org/rfc/rfc2315
[RFC3001]
A URN Namespace of Object Identifiers. M. Mealling. IETF. November 2000. Informational. URL: https://www.rfc-editor.org/rfc/rfc3001
[RFC3061]
A URN Namespace of Object Identifiers. M. Mealling. IETF. February 2001. Informational. URL: https://www.rfc-editor.org/rfc/rfc3061
[RFC3339]
Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
[RFC3629]
UTF-8, a transformation format of ISO 10646. F. Yergeau. IETF. November 2003. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3629
[RFC4648]
The Base16, Base32, and Base64 Data Encodings. S. Josefsson. IETF. October 2006. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4648
[RFC793]
Transmission Control Protocol. J. Postel. IETF. September 1981. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc793
[RFC8017]
PKCS #1: RSA Cryptography Specifications Version 2.2. K. Moriarty, Ed.; B. Kaliski; J. Jonsson; A. Rusch. IETF. November 2016. Informational. URL: https://www.rfc-editor.org/rfc/rfc8017
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[RFC8259]
The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. December 2017. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc8259
[RFC8785]
JSON Canonicalization Scheme (JCS). A. Rundgren; B. Jordan; S. Erdtman. IETF. June 2020. Informational. URL: https://www.rfc-editor.org/rfc/rfc8785

D.2 Informative references

[DATA-INTEGRITY]
Data Integrity. Manu Sporny; Dave Longley. Credentials Community Group. CG-DRAFT. URL: https://w3c-ccg.github.io/data-integrity-spec/
[DID-CORE]
Decentralized Identifiers (DIDs) v1.0. Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed. W3C. 19 July 2022. W3C Recommendation. URL: https://www.w3.org/TR/did-core/
[FactDAG]
FactDAG: Formalizing Data Interoperability in an Internet of Production. Lars Gleim; Jan Pennekamp; Martin Liebenberg; Melanie Buchsbaum; Phillip Niemietz; Simon Knape; Alexander Epple; Daniel Trauth; Thomas Bergs; Christian Brecher; Stefan Decker; Gerhard Lakemeyer; Klaus Wehrle. IEEE Internet of Things Journal, vol. 7, no. 4, pp. 3243-3253. April 2020. Research Paper. URL: https://doi.org/10.1109/JIOT.2020.2966402
[OEZER-TRUST]
Establishing Trust and Trustworthiness for Supply Chain Information Sharing. Özalp Özer, Yanchong Zheng. Handbook of Information Exchange in Supply Chain Management. Springer Series in Supply Chain Management, vol 5. Springer, Cham. 2017. Research Paper. URL: https://doi.org/10.1007/978-3-319-32441-8_14
[ReShare]
Data Reliability and Trustworthiness Through Digital Transmission Contracts. Simon Mangel; Lars Gleim; Jan Pennekamp; Klaus Wehrle; Stefan Decker. The Semantic Web. ESWC 2021. Lecture Notes in Computer Science, vol 12731. Springer, Cham. 2021. Research Paper. URL: https://doi.org/10.1007/978-3-030-77385-4_16
[RFC3987]
Internationalized Resource Identifiers (IRIs). M. Duerst; M. Suignard. IETF. January 2005. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3987
[RFC4880]
OpenPGP Message Format. J. Callas; L. Donnerhacke; H. Finney; D. Shaw; R. Thayer. IETF. November 2007. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4880
[RFC7517]
JSON Web Key (JWK). M. Jones. IETF. May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7517
[TowardsIoP]
Towards an Infrastructure Enabling the Internet of Production. Jan Pennekamp; René Glebke; Martin Henze; Tobias Meisen; Christoph Quix; Rihan Hai; Lars Gleim; Philipp Niemitz; Maximilian Rudack; Simon Knape; Alexander Epple; Daniel Trauth; Uwe Vroomen; Thomas Bergs; Christian Brecher; Andreas Bührig-Polaczek; Matthias Jarke; Klaus Wehrle. 2019 IEEE International Conference on Industrial Cyber Physical Systems (ICPS). 2019. Research Paper. URL: https://doi.org/10.1109/ICPHYS.2019.8780276
[VC-DATA-MODEL]
Verifiable Credentials Data Model v1.1. Manu Sporny; Grant Noble; Dave Longley; Daniel Burnett; Brent Zundel; Kyle Den Hartog. W3C. 3 March 2022. W3C Recommendation. URL: https://www.w3.org/TR/vc-data-model/
[VC-USE-CASES]
Verifiable Credentials Use Cases. Shane McCarron; Joe Andrieu; Matt Stone; Tzviya Siegman; Gregg Kellogg; Ted Thibodeau. W3C. 24 September 2019. W3C Working Group Note. URL: https://www.w3.org/TR/vc-use-cases/