protocol.jlinc.orgJLINC Protocol

Protocol Protocol Schema Context DID Protocol version 7 - March 26, 2020 Abstract is a protocol for sharing data protected by an agreement on the terms under which the data is being shared. The agreement is known as an Information Sharing Agreement, and can be a reference to a standardized agreement (a Standard Information Sharing Agreement or SISA) or a one-off specialized contract. The base profile is HTTP-based, but any protocol that affords methods for initiating and responding to data transactions, along with metadata (headers) accompanying those interactions could be adapted. Copyright Notice © Labs 2020 Table of Contents Notation and Conventions Definitions Overview Establishing a SISA SISA Events Consent Receipts Audit 1. Notation and Conventions The key words MUST”, MUST NOT”, REQUIRED”, SHALL”, SHALL NOT”, SHOULD”, SHOULD NOT”, RECOMMENDED”, MAY”, and OPTIONAL” in this document are to be interpreted as described in RFC 2119 . 2. Definitions - the overall protocol as described in the sections below. SISA - a Standard Information Sharing Agreement. A format for a data Rights-Holder and one or more Data-Custodians to memorialize and validate an agreement regarding the Data-Custodian’s usage of the Rights-Holder’s data. Rights-Holder - the person or entity that has legal and/or moral rights to the data being shared, or a software agent acting on their behalf. Also known as the data subject or resource owner. Data-Custodian - the entity which, having been given rights to share or receive the data by the Rights-Holder, transmits or receives the data being shared, or a software agent acting on their behalf. Also known as the data controller or the requesting or relying party. DID - a Decentralized Identifier as defined in https://w3c.github.io/did-core/ and specifically in the DID Method Specification . Ledger - a global append-only ledger maintained by an independent credential and transaction ledger provider. SISA Terms Resource - a third-party service that hosts SISAs at a well-known URI, as defined in RFC 5785 , in human readable and JSON-LD formats. SISA Event - both a capability for (and serves as a record of) data transmission under an SISA, cryptographically signed by both parties to the exchange. Consent Receipt - a record of the state of the permissions granted by the Rights-Holder to a Data-Custodian at a given point in time. JWT - a JSON Web Token, as defined in RFC 7519 . JWT payload - what RFC 7519 refers to as the claims set” section of JWT. We refer to this as the decoded JWT’s payload. JSON-LD - the JSON based serialization format defined at https://www.w3.org/TR/json-ld/ . Base64 - the URL-safe variant of Base64 encoding defined in RFC 4648 as base64url without padding. 3. Overview The protocol is in essence very simple. It starts with the existence of one or more Standard Information Sharing Agreements (SISAs) for a given industry or activity type. We envision these being hammered out by citizen representative groups together with industry organizations. Labs has created a basic SISA to kick off the process. The SISA is chosen and cryptographically signed by the initiating party (a Rights-Holder or Data-Custodian) and offered to the receiving party. The receiving party, if it recognizes and accepts the SISA, counter-signs it and returns it to the initiating party. Both parties retain a copy of the signed and counter-signed SISA, and may submit it to a Ledger of their choice to facilitate non-repudiation. Once the SISA has been completed, the parties may use the protocol to exchange information accompanied by a hash of the SISA, indicating that the exchange is understood to be happening in the context of the SISA. Records of these exchanges (SISA events) are also retained by both parties and may also be submitted to a Ledger. 4. Establishing a SISA A completed SISA records an agreement between two parties. One of the parties may be a Rights-Holder and the other a Data-Custodian, or in some use cases both parties may be considered to be Data-Custodians. The heart of the SISA is the agreement itself, which may be the text of the agreement, or a URI pointing to a specific agreement instance at a SISA Terms Resource. The format of that URI SHOULD be {scheme}{host}{version}{hash-of-the-agreement} . A JSON-LD document is then created, which MUST include a @context, a version, a jlincId (which SHOULD be a collision resistant nonce), and one of either agreementText or agreementURI. Example: { "@context": "https://protocol.jlinc.org/context/jlinc-v7.jsonld", "jlincId": "36ea8b9202bf0fb2e6c908c59394891c", "agreementURI": "https://sisa.jlinc.org/v1/3b39160c2b9ae7b2ef81c3311c7924f1c4d4fa9ca47cfe7c840c9852b50d68d5" } This JSON-LD document MUST then be encapsulated in a JWT, which we’ll call the Agreement JWT. That Agreement JWT is the byte-for-byte canonical representation of the agreement – the value which is to be hashed and signed. The Agreement JWT SHOULD be secured with the SHA256 HMAC method, using a secret value known to the party offering the SISA, so that offerer can later check that the SISA being exchanged is the identical one that they proposed. The initiator of the exchange, having chosen a SISA to offer, MUST then create hash of the Agreement JWT above and sign it with their private key. Another JSON-LD document is created containing the JWT that was signed as agreementJwt”, the hashing method used and the key type as dataCustodianSigType”, the Data-Custodian Did id as dataCustodianDid”, the Data-Custodian public key in Base64 encoding as dataCustodianPublicKey”, and the signature itself, also in Base64 encoding as dataCustodianSig”, a timestamp as createdAt” in RFC 3339 format N.B. - if a Rights-Holder is initiating the exchange the corresponding rightsHolder* keys should be used instead of the dataCustodian* keys. This document is packaged up in a JSON-LD object under the offeredSisa” key and sent to the other party in the exchange. Example: { "@context": "https://protocol.jlinc.org/context/jlinc-v7.jsonld", "offeredSisa": { "@context": "https://protocol.jlinc.org/context/jlinc-v7.jsonld", "agreementJwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "dataCustodianSigType": "sha256:ed25519", "dataCustodianDid": "did:jlinc:68C659BSZoQ1NeCJ0OVAdDpcfQJfFTMnwD53z-S5Ips", "dataCustodianPublicKey": "68C659BSZoQ1NeCJ0OVAdDpcfQJfFTMnwD53z-S5Ips", "dataCustodianSig": "t-G1zZOpORau6jrE3wmk9wBEF-B4KRmAAp...", "createdAt": "2018-05-25T18:44:14.528Z" } } The recipient SHOULD take a hash of the JWT value under the agreement” key and then verify the offering party’s signature with their public key. Next the recipient SHOULD decode the payload of the JWT value under the agreement” key and ascertain that the offered Agreement is acceptable. An elaboration of this protocol is under consideration describing methods for negotiating Agreements which may be followed if the offered Agreement is not acceptable. Assuming the Agreement is acceptable, the recipient MUST encapsulate the object under the offeredSisa” key in another JWT, secured this time with the recipient’s secret using the SHA256 HMAC method. This we will call the offeredSisa JWT. It is a hash of this object, the offeredSisa JWT, that the recipient will sign to accept the offer. The recipient then creates the accepted JSON-LD object in the same manner as above, but with the offeredSisaJwt” key’s value being the offeredSisa JWT, and in our example the signer being the Rights-Holder. Example: { "@context": "https://protocol.jlinc.org/context/jlinc-v7.jsonld", "offeredSisaJwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "rightsHolderSigType": "sha256:ed25519", "rightsHolderDid": "did:jlinc:DKHFTOEcTYdQ1EADyhT95A9UkMmlkQn8_CtdHm2v_pg", "rightsHolderPublicKey": "DKHFTOEcTYdQ1EADyhT95A9UkMmlkQn8_CtdHm2v_pg", "rightsHolderSig": "uidhE6-GyICSXwh9F8cN0ZKV2mzUJWqWot...", "createdAt": "2018-05-25T18:44:15.368Z" } Finally, the recipient MUST encapsulate the accepted SISA in another JWT along...